CLI do Cord

Faça login pelo navegador, configure a sua conta, integre o seu projeto e teste webhooks no seu localhost.

@flouviahq/cli é uma ferramenta de desenvolvimento: só aceita chaves de teste (sk_test_ ou rk_test_), então nada do que você fizer com ela toca dados reais. A exceção é cord setup, que propõe a configuração da sua conta real e não aplica nada sem a sua aprovação.

Instalar

Use-a sem instalar:

npx @flouviahq/cli

Ou instale-a globalmente para ter o comando cord:

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

Os exemplos desta página usam cord; com npx é o mesmo, antepondo npx @flouviahq/cli.

Comandos

Comando	O que faz
`cord`	Sem comando e em um terminal interativo, abre o assistente. Fora de um terminal, imprime a ajuda.
`cord wizard`	Abre o assistente explicitamente.
`cord login`	Faz login pelo navegador e guarda uma chave de teste.
`cord whoami`	Mostra a organização, o modo, a permissão e a chave em uso.
`cord logout`	Apaga a chave guardada na sua máquina.
`cord setup`	Propõe a configuração da sua conta com IA; você a aprova.
`cord init`	Detecta o seu framework e deixa a integração pronta.
`cord listen`	Reencaminha os webhooks de teste para o seu servidor local.
`cord trigger`	Dispara um webhook de teste.
`cord simulate`	Força o resultado da próxima emissão fiscal, ou simula o cliente ou a passagem do tempo.
`cord events tail`	Mostra os eventos à medida que acontecem.
`cord help`	A ajuda. Também `--help` ou `-h`.

Opções globais e variáveis

Opção	Variável	Detalhe
`--api-key <chave>`	`CORD_API_KEY`	A chave de teste a usar. Prevalece sobre a guardada.
`--base-url <url>`	`CORD_BASE_URL`	Origem do Cord. Padrão: `https://cordhq.app`.
`--version`, `-v`	—	Imprime a versão.
`--help`, `-h`	—	Imprime a ajuda.

A chave é procurada nesta ordem: --api-key, CORD_API_KEY e a guardada por cord login em ~/.config/cord/config.json (ou $XDG_CONFIG_HOME/cord/config.json), com permissões 0600. Uma chave de produção (sk_live_, rk_live_) ou publicável (pk_) é rejeitada antes de chamar o Cord.

As opções aceitam --opcao valor e --opcao=valor.

O assistente

npx @flouviahq/cli

Conecte o seu terminal. Se não houver uma sessão válida, ele abre o login no navegador. Se o assistente for integrar o seu projeto, na mesma tela você pode criar uma Secret Key de teste para ele.
Escolha o que fazer com as setas e a barra de espaço: configurar a sua conta com IA, integrar o Cord ao projeto e testar webhooks no seu localhost.
Cada etapa roda como o seu comando avulso (setup, init, listen) e, no final, você vê um resumo do que ficou pronto e do próximo passo.

O assistente precisa de um terminal interativo. Em scripts e na CI, use os comandos avulsos.

`cord login`

cord login

Abre o seu navegador com um código de confirmação (por exemplo, WXYZ-2346). Confira se é o mesmo que você vê no terminal e autorize com a sua sessão do Cord: o terminal recebe uma chave sozinho e você não copia nada.

A chave é restrita e de teste: ela só pode usar os simuladores (test_helpers, escrita), ler eventos (eventos, leitura) e propor configurações (setup, escrita).
Ela expira em 90 dias e aparece em Desenvolvedores › Chaves como CLI · <nome da sua máquina>, onde você pode revogá-la. Conectar de novo a mesma máquina revoga a chave anterior.
O código expira em 10 minutos e a chave é entregue uma única vez.
A CLI só abre no navegador endereços da mesma origem que --base-url.

Variante	O que faz
`cord login --no-browser`	Imprime o endereço para você abri-lo em outra máquina (por exemplo, em um servidor via SSH).
`cord login --api-key`	Pede que você cole uma chave de teste sua e a verifica antes de guardá-la.
`cord login --api-key sk_test_...`	Guarda essa chave sem perguntar, depois de verificá-la.

Para cord listen e cord init, uma Secret Key de teste comum também serve: coloque-a em CORD_API_KEY.

`cord whoami` e `cord logout`

cord whoami

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

A interface da CLI está em espanhol. cord logout apaga o arquivo de configuração. Ele não revoga a chave no Cord: para isso, revogue-a em Desenvolvedores › Chaves.

`cord setup`

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

Opção	Detalhe
`--sitio <url>`	O seu site: nome, marca e contato.
`--descripcion <texto>`	O que o negócio faz, como recebe e quais impostos aplica.
`--archivo <caminho>`	Lista de preços: `.csv`, `.xlsx`, `.pdf` ou foto, até 3 MB.

Sem opções, ela pergunta o mesmo passo a passo. O Cord monta a proposta, abre-a no seu navegador e aguarda a sua aprovação (até 30 minutos; Enter para de aguardar). Nada é aplicado até você aprovar. A proposta sempre configura a sua conta real, mesmo que a chave seja de teste, e conta no limite de 6 propostas por dia. Detalhes em Configuração assistida.

`cord init`

cord init

Detecta o framework da pasta atual, diz exatamente o que vai fazer e, se você aceitar, faz. Nunca sobrescreve um arquivo existente.

Framework	Instala	Cria ou sugere	Arquivo de ambiente
Next.js (App Router)	`@flouviahq/node` e `@flouviahq/elements`	`app/api/webhooks/cord/route.ts` e o proxy `app/api/cord/[...path]/route.ts` (em `src/` se existir `src/app`)	`.env.local`
Astro	`@flouviahq/node` e `@flouviahq/elements`	`src/pages/api/webhooks/cord.ts`	`.env.local`
Next.js (Pages Router), Express	`@flouviahq/node` e `@flouviahq/elements`	Mostra a rota de webhooks para você colar	`.env`
Laravel, Django, Flask, FastAPI	Nada: os SDKs de PHP e Python ainda não foram publicados	Mostra uma rota que verifica a assinatura sem dependências	`.env`

Instala com o gerenciador do seu projeto conforme o lockfile: pnpm, yarn, bun ou npm.
Escreve CORD_SECRET_KEY apenas em um arquivo de ambiente que o seu .gitignore ignora. Se não houver um, não escreve chaves e avisa você.
A rota gerada verifica a assinatura com CORD_WEBHOOK_SECRET.

`cord listen`

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

Opção	Detalhe
`--forward-to <url>`	Obrigatória. URL `http://` ou `https://` do seu servidor local.
`--events <lista>`	Somente esses eventos, separados por vírgula: `--events quote.paid,invoice.paid`. Sem ela, todos.
`--env-file <arquivo>`	Guarda ali o segredo da sessão como `CORD_WEBHOOK_SECRET`, sem mexer nas demais linhas.
`--allow-remote`	Permite reencaminhar para um host que não é a sua máquina.

O Cord não consegue fazer requisições à sua máquina, então a CLI abre uma sessão de escuta no seu ambiente de teste e a consulta a cada segundo e meio. Os eventos passam pelo mesmo mecanismo de produção (assinatura, versão da API, histórico) e a CLI os reencaminha com os headers de assinatura reais. Verifique com constructEvent e o segredo da sessão, assim como em produção.

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

Por padrão, só reencaminha para localhost, 127.0.0.1, ::1 e hosts *.localhost. A URL não pode levar usuário nem senha, e um redirecionamento do seu servidor não é seguido.
A sessão expira em 24 horas e Ctrl+C a encerra. Você pode ter até 3 sessões abertas por chave.
O segredo da sessão muda a cada vez e só serve para essa sessão.
Um evento é considerado entregue quando a CLI o recolhe. Se o seu servidor não responder, a CLI mostra isso e não tenta de novo: dispare-o outra vez com cord trigger.

`cord trigger`

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

Dispara qualquer um dos 41 eventos do catálogo para os seus endpoints de teste e para as suas sessões de cord listen. Sem --objeto, com dados de exemplo; com o UUID de um orçamento ou de uma fatura de teste, com os dados reais deles. A entrega passa pelo mecanismo real: assinatura, novas tentativas e histórico no 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

Forma	Efeito
`simulate fiscal <resultado>`	A próxima emissão fiscal de teste resulta em `exito`, `pac_caido`, `receptor_invalido`, `certificado_vencido` ou `timbre_duplicado`.
`simulate quote <id> vista`	O cliente abre o link: emite `quote.viewed`.
`simulate quote <id> vencer`	O orçamento expira: emite `quote.expired`. Somente com um orçamento enviado ou visualizado.

São os mesmos simuladores da API.

`cord events tail`

cord events tail --type quote.paid

Consulta o histórico de eventos a cada 2 segundos e mostra os novos à medida que acontecem, a partir do momento em que você o inicia. --type filtra por um tipo. Ctrl+C para sair.

Erros comuns

As mensagens da CLI estão em espanhol.

Mensagem	O que fazer
`No hay sesión. Corre cord login…`	Não há chave em `--api-key`, em `CORD_API_KEY` nem na configuração.
`Esa es una llave en vivo…`	A CLI só usa chaves de teste. Crie uma `sk_test_` ou use `cord login`.
`Falta --forward-to…`	`cord listen` precisa da URL do seu servidor.
`--forward-to apunta a <host>…`	Para reencaminhar para fora da sua máquina, adicione `--allow-remote`.
`Ya hay 3 sesiones de escucha abiertas con esta llave…`	Feche alguma com Ctrl+C ou aguarde que ela expire.

Os erros da API incluem o request_id entre parênteses: procure-o em Desenvolvedores › Logs.

Instalar

Comandos

Opções globais e variáveis

O assistente

cord login

cord whoami e cord logout

cord setup

cord init

cord listen

cord trigger

cord simulate

cord events tail