CLI de Cord

Connectez-vous depuis le navigateur, configurez votre compte, intégrez votre projet et testez les webhooks sur votre localhost.

@flouviahq/cli est un outil de développement : il n’accepte que des clés de test (sk_test_ ou rk_test_), si bien que rien de ce que vous faites avec lui ne touche des données réelles. L’exception est cord setup, qui propose la configuration de votre compte réel et n’applique rien sans votre validation.

Installer

Utilisez-la sans l’installer :

npx @flouviahq/cli

Ou installez-la globalement pour disposer de la commande cord :

npm install -g @flouviahq/cli
cord --version

Les exemples de cette page utilisent cord ; avec npx, c’est la même chose en préfixant par npx @flouviahq/cli.

Commandes

Commande	Effet
`cord`	Sans commande et dans un terminal interactif, ouvre l’assistant. Hors d’un terminal, affiche l’aide.
`cord wizard`	Ouvre explicitement l’assistant.
`cord login`	Se connecte depuis le navigateur et enregistre une clé de test.
`cord whoami`	Affiche l’organisation, le mode, le droit et la clé utilisée.
`cord logout`	Supprime la clé enregistrée sur votre machine.
`cord setup`	Propose la configuration de votre compte avec l’IA ; vous la validez.
`cord init`	Détecte votre framework et prépare l’intégration.
`cord listen`	Retransmet les webhooks de test à votre serveur local.
`cord trigger`	Déclenche un webhook de test.
`cord simulate`	Force le résultat de la prochaine émission fiscale, ou simule le client ou le passage du temps.
`cord events tail`	Affiche les événements au fur et à mesure qu’ils se produisent.
`cord help`	L’aide. Également `--help` ou `-h`.

Options globales et variables

Option	Variable	Détail
`--api-key <clé>`	`CORD_API_KEY`	La clé de test à utiliser. Elle l’emporte sur la clé enregistrée.
`--base-url <url>`	`CORD_BASE_URL`	Origine de Cord. Par défaut `https://cordhq.app`.
`--version`, `-v`	—	Affiche la version.
`--help`, `-h`	—	Affiche l’aide.

La clé est recherchée dans cet ordre : --api-key, CORD_API_KEY, puis celle enregistrée par cord login dans ~/.config/cord/config.json (ou $XDG_CONFIG_HOME/cord/config.json), avec les permissions 0600. Une clé live (sk_live_, rk_live_) ou publiable (pk_) est rejetée avant tout appel à Cord.

Les options acceptent --option valeur comme --option=valeur.

L’assistant

npx @flouviahq/cli

Connectez votre terminal. S’il n’y a pas de session valide, il ouvre la connexion dans le navigateur. Si l’assistant doit intégrer votre projet, vous pouvez créer sur le même écran une clé secrète de test pour lui.
Choisissez quoi faire avec les flèches et la barre d’espace : configurer votre compte avec l’IA, intégrer Cord au projet et tester les webhooks sur votre localhost.
Chaque étape s’exécute comme sa commande autonome (setup, init, listen) et, à la fin, vous voyez un récapitulatif de ce qui est prêt et de l’étape suivante.

L’assistant a besoin d’un terminal interactif. Dans les scripts et en CI, utilisez les commandes autonomes.

`cord login`

cord login

Il ouvre votre navigateur avec un code de confirmation (par exemple WXYZ-2346). Vérifiez qu’il correspond à celui affiché dans le terminal et autorisez avec votre session Cord : le terminal reçoit la clé tout seul et vous ne copiez rien.

La clé est restreinte et de test : elle ne peut qu’utiliser les simulateurs (test_helpers, écriture), lire les événements (eventos, lecture) et proposer des configurations (setup, écriture).
Elle expire au bout de 90 jours et apparaît dans Développeurs › Clés API sous le nom CLI · <nom de votre machine>, où vous pouvez la révoquer. Reconnecter la même machine révoque la clé précédente.
Le code expire au bout de 10 minutes et la clé n’est remise qu’une seule fois.
La CLI n’ouvre dans le navigateur que des adresses de la même origine que --base-url.

Variante	Effet
`cord login --no-browser`	Affiche l’adresse pour l’ouvrir sur une autre machine (par exemple, un serveur en SSH).
`cord login --api-key`	Vous demande de coller une de vos clés de test et la vérifie avant de l’enregistrer.
`cord login --api-key sk_test_...`	Enregistre cette clé sans poser de question, après l’avoir vérifiée.

Une clé secrète de test ordinaire fonctionne aussi pour cord listen et cord init : placez-la dans CORD_API_KEY.

`cord whoami` et `cord logout`

cord whoami

Empresa  Aceros del Norte
Modo     prueba
Permiso  write
Llave    sk_test_…9f2a

L’interface de la CLI est en espagnol. cord logout supprime le fichier de configuration. Il ne révoque pas la clé dans Cord : pour cela, révoquez-la dans Développeurs › Clés API.

`cord setup`

cord setup --sitio materialesdelvalle.mx --descripcion "Building materials on 30-day credit" --archivo prices.xlsx

Option	Détail
`--sitio <url>`	Votre site web : nom, marque et coordonnées.
`--descripcion <texte>`	L’activité de l’entreprise, sa façon d’encaisser et les taxes qu’elle applique.
`--archivo <chemin>`	Liste de prix : `.csv`, `.xlsx`, `.pdf` ou photo, jusqu’à 3 Mo.

Sans options, il vous pose les mêmes questions étape par étape. Cord prépare la proposition, l’ouvre dans votre navigateur et attend votre validation (jusqu’à 30 minutes ; Entrée arrête l’attente). Rien n’est appliqué tant que vous ne l’avez pas validée. La proposition configure toujours votre compte réel, même avec une clé de test, et compte dans la limite de 6 propositions par jour. Détails dans Configuration assistée.

`cord init`

cord init

Il détecte le framework du dossier courant, vous indique exactement ce qu’il va faire et, si vous acceptez, le fait. Il n’écrase jamais un fichier existant.

Framework	Installe	Crée ou suggère	Fichier d’environnement
Next.js (App Router)	`@flouviahq/node` et `@flouviahq/elements`	`app/api/webhooks/cord/route.ts` et le proxy `app/api/cord/[...path]/route.ts` (sous `src/` si `src/app` existe)	`.env.local`
Astro	`@flouviahq/node` et `@flouviahq/elements`	`src/pages/api/webhooks/cord.ts`	`.env.local`
Next.js (Pages Router), Express	`@flouviahq/node` et `@flouviahq/elements`	Vous montre la route de webhooks à coller	`.env`
Laravel, Django, Flask, FastAPI	Rien : les SDK PHP et Python ne sont pas encore publiés	Vous montre une route qui vérifie la signature sans dépendances	`.env`

Il installe avec le gestionnaire de paquets de votre projet selon le fichier de verrouillage : pnpm, yarn, bun ou npm.
Il n’écrit CORD_SECRET_KEY que dans un fichier d’environnement ignoré par votre .gitignore. S’il n’y en a pas, il n’écrit aucune clé et vous le signale.
La route générée vérifie la signature avec CORD_WEBHOOK_SECRET.

`cord listen`

cord listen --forward-to http://localhost:3000/api/webhooks/cord --env-file .env.local

Option	Détail
`--forward-to <url>`	Obligatoire. URL `http://` ou `https://` de votre serveur local.
`--events <liste>`	Uniquement ces événements, séparés par des virgules : `--events quote.paid,invoice.paid`. Sans elle, tous.
`--env-file <fichier>`	Y enregistre le secret de la session sous `CORD_WEBHOOK_SECRET`, sans toucher aux autres lignes.
`--allow-remote`	Autorise la retransmission vers un hôte qui n’est pas votre machine.

Cord ne peut pas envoyer de requêtes à votre machine : la CLI ouvre donc une session d’écoute dans votre environnement de test et l’interroge toutes les secondes et demie. Les événements passent par le même moteur qu’en production (signature, version de l’API, historique) et la CLI les retransmet avec les vrais en-têtes de signature. Vérifiez avec constructEvent et le secret de la session, exactement comme en production.

│  17:04:12  200  quote.sent                 evt_9d2a6c4e1f8b3a5d7c0e2f4a6b8d1c3e  41 ms

Par défaut, il ne retransmet qu’à localhost, 127.0.0.1, ::1 et aux hôtes *.localhost. L’URL ne peut contenir ni nom d’utilisateur ni mot de passe, et une redirection de votre serveur n’est pas suivie.
La session expire au bout de 24 heures et Ctrl+C la ferme. Vous pouvez avoir jusqu’à 3 sessions ouvertes par clé.
Le secret de la session change à chaque fois et ne sert que pour cette session.
Un événement est considéré comme envoyé dès que la CLI le récupère. Si votre serveur ne répond pas, la CLI l’affiche et ne réessaie pas : déclenchez-le de nouveau avec cord trigger.

`cord trigger`

cord trigger invoice.paid
cord trigger quote.approved --objeto 8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10

Il déclenche n’importe lequel des 41 événements du catalogue vers vos endpoints de test et vos sessions cord listen. Sans --objeto, avec des données d’exemple ; avec l’UUID d’un devis ou d’une facture de test, avec ses données réelles. L’envoi passe par le moteur réel : signature, nouvelles tentatives et historique dans le Workbench.

`cord simulate`

cord simulate fiscal pac_caido
cord simulate quote 8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10 vista
cord simulate quote 8b0c6f0e-2d55-4c1e-9a43-6a2f1c7d9e10 vencer

Forme	Effet
`simulate fiscal <résultat>`	La prochaine émission fiscale de test aboutit à `exito`, `pac_caido`, `receptor_invalido`, `certificado_vencido` ou `timbre_duplicado`.
`simulate quote <id> vista`	Le client ouvre le lien : émet `quote.viewed`.
`simulate quote <id> vencer`	Le devis expire : émet `quote.expired`. Uniquement pour un devis envoyé ou consulté.

Ce sont les mêmes simulateurs que ceux de l’API.

`cord events tail`

cord events tail --type quote.paid

Il interroge l’historique des événements toutes les 2 secondes et affiche les nouveaux événements au fur et à mesure, à partir du moment où vous le lancez. --type filtre sur un type. Ctrl+C pour quitter.

Erreurs courantes

Les messages de la CLI sont en espagnol.

Message	Que faire
`No hay sesión. Corre cord login…`	Aucune clé dans `--api-key`, `CORD_API_KEY` ni dans la configuration.
`Esa es una llave en vivo…`	La CLI n’utilise que des clés de test. Créez une clé `sk_test_` ou utilisez `cord login`.
`Falta --forward-to…`	`cord listen` a besoin de l’URL de votre serveur.
`--forward-to apunta a <host>…`	Pour retransmettre hors de votre machine, ajoutez `--allow-remote`.
`Ya hay 3 sesiones de escucha abiertas con esta llave…`	Fermez-en une avec Ctrl+C ou attendez qu’elle expire.

Les erreurs de l’API incluent le request_id entre parenthèses : recherchez-le dans Développeurs › Journaux.

Installer

Commandes

Options globales et variables

L’assistant

cord login

cord whoami et cord logout

cord setup

cord init

cord listen

cord trigger

cord simulate

cord events tail