Installation et authentification

Installez la CLI sur votre machine, puis fournissez-lui une clé qu'elle peut conserver.

La CLI est un paquet Node. Une installation globale et un aller-retour dans le navigateur suffisent.

Prérequis

Node.js 22 ou version ultérieure. wajub doctor le vérifie : un ancien runtime échoue donc avec un message clair plutôt qu'une trace de pile.

Vérifier avant l'installation

node --version

Installation

npm install -g @wajub/cli

Confirmez l'installation et notez le runtime indiqué. Le support vous demandera cette ligne.

wajub version

$ wajub version
@wajub/cli/1.7.3 darwin-arm64 node-v22.11.0

Sans rien installer

npx @wajub/cli listen --forward-to localhost:3000/webhooks exécute la version actuelle sans rien laisser derrière. Cette méthode est utile sur une machine qui ne vous appartient pas ou dans un conteneur temporaire.

Pour effectuer une mise à jour, relancez l'installation. La CLI vous avertit aussi lorsqu'une nouvelle version est publiée.

Authentification

wajub login ouvre votre navigateur. Un membre de votre équipe approuve la demande dans le Dashboard et la CLI reçoit une clé qu'elle conserve localement. Vous ne saisissez rien dans le terminal, donc aucune clé n'apparaît dans l'historique du shell.

Le parcours normal

wajub login
wajub login --environment live

La sandbox est utilisée par défaut. Connectez-vous deux fois, une fois par environnement, pour obtenir deux profils entre lesquels basculer.

Option	Utilisation
`--environment`	`sandbox` ou `live`, l'environnement que vous demandez. La personne qui approuve choisit celui de la clé
`--manual`	Colle une clé existante dans une invite masquée, sans navigateur
`--no-browser`	Affiche l'URL au lieu de l'ouvrir, pour un shell distant
`--no-skills`	N'installe aucun Skill pour agents, ni maintenant ni lors des exécutions suivantes
`--profile`	Nomme le profil créé

Les identifiants sont enregistrés dans ~/.config/wajub/config.json, accessible uniquement par vous. Vous pouvez le sauvegarder, mais traitez-le exactement comme un fichier de clés.

Le terminal affiche un code d'appairage et la page à ouvrir, et la page montre le même code : vérifiez qu'ils correspondent avant de continuer. La page démarre toujours sur Test, quoi que demande --environment, et c'est la personne qui approuve qui y choisit l'environnement. Production est proposé une fois le compte vérifié, et jamais à un Sandbox User. La personne qui approuve choisit aussi Accès complet, ou Restreint avec les permissions que reçoit la clé.

Approuver crée une clé d'API pour l'équipe, si bien que tous les membres ne le peuvent pas :

Le propriétaire, un Administrator ou un Developer approuve, et un Sandbox User le peut aussi, pour une clé sandbox. Tout autre membre voit « Un administrateur ou un développeur doit approuver cette demande », avec le code : envoyez l'adresse de la page à l'un d'eux.
Autoriser exige un code de vérification de sécurité récent (il vaut 30 minutes), comme l'affichage ou le renouvellement d'une clé. La page en demande un quand il le faut, depuis votre application d'authentification ou envoyé par SMS ou par e-mail.

Le propriétaire et chaque Administrator reçoivent un e-mail pour chaque clé créée par une connexion, qui indique qui l'a approuvée, l'environnement, le type de clé et son expiration, avec un lien vers la page des clés API. Une connexion que personne de votre équipe n'a lancée est une raison de supprimer cette clé.

La demande dure 15 minutes. Sans approbation dans ce délai, la CLI s'arrête et vous demande de relancer wajub login. Un refus se termine par Login was denied in the browser., et les deux cas sortent avec le statut 1.

La clé créée

Votre première connexion sandbox devient le profil par défaut, celui qu'utilise toute commande sans --profile. Une connexion suivante ne le déplace pas : une connexion live ne devient jamais le profil par défaut d'elle-même, si bien que la commande qui suit wajub login --environment live s'exécute toujours en sandbox. La CLI le signale quand le nouveau profil n'est pas celui par défaut ; wajub config use live en fait le profil par défaut, délibérément. Sans --profile, le profil porte le nom de l'environnement choisi à l'approbation, quoi que demande --environment.

La clé créée par wajub login expire toujours 90 jours plus tard : la page d'approbation ne propose aucune autre durée pour la CLI. La CLI affiche la date à la connexion, wajub doctor la montre sur la ligne Key expiry et échoue pendant les 7 derniers jours, où chaque commande vous prévient aussi. Relancez wajub login pour en obtenir une nouvelle.

Dans la CI, utilisez l'environnement

Un pipeline ne possède aucun navigateur. Définissez WAJUB_API_KEY pour que toutes les commandes l'utilisent sans qu'aucun profil n'existe.

Une étape de pipeline

# From your CI secret store, never from the job definition
export WAJUB_API_KEY=sk.xxxxxxxxxxxxxxxx…

wajub doctor --json
wajub payments list -f per_page=5 --json

Ne transmettez jamais une clé avec `--api-key`

Une clé passée dans la ligne de commande est écrite dans l'historique du shell et visible dans la liste des processus par tous les utilisateurs de la machine. Utilisez wajub login en local et WAJUB_API_KEY dans la CI.

Profils

Un profil est un ensemble d'identifiants nommé. La CLI utilise ce concept parce que les clés de la sandbox et du mode live ne doivent jamais être séparées par une simple faute de frappe.

Créer, examiner et changer de profil

# What do I have, and which one is default?
wajub config

# Register a key under a name, without calling the API to validate it.
# The CLI asks for the key through a hidden prompt.
wajub config set staging

# Make it the default
wajub config use staging

# Or override for a single command
wajub payments list --profile sandbox

wajub config affiche les clés masquées. --show-secrets les affiche entièrement, ce qui est presque toujours déconseillé sur un écran partagé.

Une variable WAJUB_API_KEY exportée l'emporte sur tous les profils, --profile compris : tant qu'elle est définie, wajub payments list --profile sandbox utilise toujours la clé exportée. WAJUB_PROFILE choisit le profil pour toutes les commandes du shell, comme --profile le fait pour une seule.

`config set` ne vérifie pas la clé

La commande enregistre le profil tel quel. Une faute de frappe n'est découverte que plus tard, lorsqu'une commande échoue avec 401. Exécutez wajub doctor après avoir créé manuellement un profil.

Vérifier toute la chaîne

wajub doctor

$ wajub doctor

Wajub CLI diagnostics

  ✓  Config  2 profile(s), default: sandbox
  ✓  Credentials  key=sk_test.…  env=sandbox  base=https://api.wajub.com  source=profile
  ✓  API reachability  https://api.wajub.com (HTTP 200)
  ✓  Auth  API key accepted, Boutique Akwa (sandbox)
  ✓  Key expiry  expires on 1/9/2027 (in 89 day(s))
  ✓  Node.js  v22.11.0 (≥ 22 required)
  ✓  Environment  wajub-cli v1.7.3  node v22.11.0  darwin/arm64
  ✓  Support  last request id: fbe6773e9ce64f158af89e5740fc5817

Everything looks good.

Le champ source de la ligne des identifiants est souvent ignoré. Il indique si la clé provient d'un profil, de WAJUB_API_KEY ou d'une option. Lorsqu'une commande semble appartenir à un autre compte, ce champ vous donne la réponse.

Déconnexion

wajub logout révoque la clé créée par wajub login, puis supprime le profil local. La révocation est importante. La simple suppression du fichier laisserait une clé live active chez Wajub. Une clé que vous avez placée vous-même dans un profil (--manual, wajub config set) reste active, et la CLI le signale : révoquez-la dans le Dashboard si elle doit cesser de fonctionner.

Se déconnecter proprement

wajub logout                    # the current profile
wajub logout --profile sandbox  # a named one
wajub logout --all              # every profile
wajub logout --keep-key         # forget it locally, leave the key active

Utilisez --keep-key uniquement lorsque la clé sert également ailleurs, par exemple sur un serveur configuré avec une copie provenant du Dashboard.

Pages associées