Cord CLI

@flouviahq/cli is a development tool: it only accepts test keys (sk_test_ or rk_test_), so nothing you do with it touches real data. The exception is cord setup, which proposes the setup of your real account and applies nothing without your approval.

Install

Use it without installing:

npx @flouviahq/cli

Or install it globally to get the cord command:

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

The examples on this page use cord; with npx it’s the same, prefixed with npx @flouviahq/cli.

Commands

Command	What it does
`cord`	With no command and in an interactive terminal, opens the wizard. Outside a terminal it prints the help.
`cord wizard`	Opens the wizard explicitly.
`cord login`	Signs in from the browser and stores a test key.
`cord whoami`	Shows the organization, mode, permission and key in use.
`cord logout`	Deletes the key stored on your machine.
`cord setup`	Proposes your account’s setup with AI; you approve it.
`cord init`	Detects your framework and leaves the integration ready.
`cord listen`	Forwards test webhooks to your local server.
`cord trigger`	Triggers a test webhook.
`cord simulate`	Forces the outcome of the next tax issuance, or simulates the client or time passing.
`cord events tail`	Shows events as they happen.
`cord help`	The help. Also `--help` or `-h`.

Global options and variables

Option	Variable	Detail
`--api-key <key>`	`CORD_API_KEY`	The test key to use. Takes precedence over the stored one.
`--base-url <url>`	`CORD_BASE_URL`	Cord’s origin. Default `https://cordhq.app`.
`--version`, `-v`	—	Prints the version.
`--help`, `-h`	—	Prints the help.

The key is looked up in this order: --api-key, CORD_API_KEY, and the one stored by cord login in ~/.config/cord/config.json (or $XDG_CONFIG_HOME/cord/config.json), with 0600 permissions. A live key (sk_live_, rk_live_) or a publishable one (pk_) is rejected before calling Cord.

Options accept both --option value and --option=value.

The wizard

npx @flouviahq/cli

Connect your terminal. If there’s no valid session, it opens the browser sign-in. If the wizard is going to integrate your project, on the same screen you can create a test Secret Key for it.
Choose what to do with the arrows and the space bar: set up your account with AI, integrate Cord into the project and test webhooks on your localhost.
Each step runs like its standalone command (setup, init, listen), and at the end you see a summary of what’s ready and the next step.

The wizard needs an interactive terminal. In scripts and CI, use the standalone commands.

`cord login`

cord login

It opens your browser with a confirmation code (for example WXYZ-2346). Check it matches the one in your terminal and authorize with your Cord session: the terminal receives a key on its own and you copy nothing.

The key is restricted and for testing: it can only use the simulators (test_helpers, write), read events (eventos, read) and propose setups (setup, write).
It expires in 90 days and shows up in Developers › API keys as CLI · <your machine's name>, where you can revoke it. Reconnecting the same machine revokes the previous key.
The code expires in 10 minutes and the key is handed out only once.
The CLI only opens browser addresses on the same origin as --base-url.

Variant	What it does
`cord login --no-browser`	Prints the address so you can open it on another machine (for example, a server over SSH).
`cord login --api-key`	Asks you to paste a test key of yours and verifies it before storing it.
`cord login --api-key sk_test_...`	Stores that key without asking, after verifying it.

A regular test Secret Key also works for cord listen and cord init: put it in CORD_API_KEY.

`cord whoami` and `cord logout`

cord whoami

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

The CLI’s interface is in Spanish. cord logout deletes the configuration file. It doesn’t revoke the key in Cord: for that, revoke it in Developers › API keys.

`cord setup`

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

Option	Detail
`--sitio <url>`	Your website: name, branding and contact details.
`--descripcion <text>`	What the business does, how it gets paid and which taxes it handles.
`--archivo <path>`	Price list: `.csv`, `.xlsx`, `.pdf` or a photo, up to 3 MB.

Without options, it asks the same things step by step. Cord builds the proposal, opens it in your browser and waits for your approval (up to 30 minutes; Enter stops waiting). Nothing is applied until you approve it. The proposal always configures your real account, even with a test key, and counts toward the limit of 6 proposals per day. Details in Assisted setup.

`cord init`

cord init

It detects the framework in the current folder, tells you exactly what it’s going to do and, if you accept, does it. It never overwrites an existing file.

Framework	Installs	Creates or suggests	Env file
Next.js (App Router)	`@flouviahq/node` and `@flouviahq/elements`	`app/api/webhooks/cord/route.ts` and the proxy `app/api/cord/[...path]/route.ts` (under `src/` if `src/app` exists)	`.env.local`
Astro	`@flouviahq/node` and `@flouviahq/elements`	`src/pages/api/webhooks/cord.ts`	`.env.local`
Next.js (Pages Router), Express	`@flouviahq/node` and `@flouviahq/elements`	Shows you the webhook route to paste	`.env`
Laravel, Django, Flask, FastAPI	Nothing: the PHP and Python SDKs aren’t published yet	Shows you a route that verifies the signature with no dependencies	`.env`

It installs with your project’s package manager based on the lockfile: pnpm, yarn, bun or npm.
It writes CORD_SECRET_KEY only to an env file your .gitignore ignores. If there isn’t one, it doesn’t write keys and tells you so.
The generated route verifies the signature with CORD_WEBHOOK_SECRET.

`cord listen`

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

Option	Detail
`--forward-to <url>`	Required. `http://` or `https://` URL of your local server.
`--events <list>`	Only those events, comma-separated: `--events quote.paid,invoice.paid`. Without it, all of them.
`--env-file <file>`	Stores the session secret there as `CORD_WEBHOOK_SECRET`, without touching the other lines.
`--allow-remote`	Allows forwarding to a host that isn’t your machine.

Cord can’t make requests to your machine, so the CLI opens a listening session in your test environment and polls it every second and a half. Events go through the same engine as production (signature, API version, history) and the CLI forwards them with the real signature headers. Verify with constructEvent and the session secret, just like in production.

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

By default it only forwards to localhost, 127.0.0.1, ::1 and *.localhost hosts. The URL can’t carry a username or password, and a redirect from your server isn’t followed.
The session expires in 24 hours and Ctrl+C closes it. You can have up to 3 open sessions per key.
The session secret changes every time and only works for that session.
An event counts as delivered when the CLI picks it up. If your server doesn’t respond, the CLI shows it and doesn’t retry: trigger it again with cord trigger.

`cord trigger`

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

It triggers any of the 41 catalog events to your test endpoints and your cord listen sessions. Without --objeto, with sample data; with the UUID of a test quote or invoice, with its real data. Delivery goes through the real engine: signature, retries and history in the 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

Form	Effect
`simulate fiscal <outcome>`	The next test tax issuance results in `exito`, `pac_caido`, `receptor_invalido`, `certificado_vencido` or `timbre_duplicado`.
`simulate quote <id> vista`	The client opens the link: emits `quote.viewed`.
`simulate quote <id> vencer`	The quote expires: emits `quote.expired`. Only for a sent or viewed quote.

They’re the same API simulators.

`cord events tail`

cord events tail --type quote.paid

It polls the event history every 2 seconds and shows new events as they happen, from the moment you start it. --type filters by one type. Ctrl+C to exit.

Common errors

The CLI’s messages are in Spanish.

Message	What to do
`No hay sesión. Corre cord login…`	There’s no key in `--api-key`, `CORD_API_KEY` or the configuration.
`Esa es una llave en vivo…`	The CLI only uses test keys. Create an `sk_test_` key or use `cord login`.
`Falta --forward-to…`	`cord listen` needs your server’s URL.
`--forward-to apunta a <host>…`	To forward outside your machine, add `--allow-remote`.
`Ya hay 3 sesiones de escucha abiertas con esta llave…`	Close one with Ctrl+C or wait for it to expire.

API errors include the request_id in parentheses: look it up in Developers › Logs.

Install

Commands

Global options and variables

The wizard

cord login

cord whoami and cord logout

cord setup

cord init

cord listen

cord trigger

cord simulate

cord events tail