A CLI do Cord: sua integração pronta direto do terminal

O que faz a CLI do Cord 2.1: você entra pelo navegador, ela integra seu projeto, conecta seus apps, deixa o MCP nos seus agentes e testa webhooks no localhost.

ARTIGO
NESTE ARTIGO9 SEÇÕES

Integrar uma plataforma de pagamentos costuma começar do mesmo jeito: procurar a seção de chaves em um painel, copiar uma sequência longa para um .env, escrever a rota que recebe os webhooks, verificar a assinatura deles, abrir um túnel para testá-la na sua máquina e repetir tudo quando você troca de computador. Queríamos que, com o Cord, bastasse um comando:

npx @flouviahq/cli

Ontem à noite publicamos a versão 2.1 do @flouviahq/cli. Este artigo conta o que ela faz, tela por tela. As imagens são réplicas fiéis do assistente real: os mesmos textos, cores e etapas que você vai ver no seu terminal.

Ao abrir, o assistente já sabe onde está: a pasta, o framework e os apps que o seu projeto usa.

Um assistente em tela cheia

Sem comando, a CLI abre um assistente que ocupa o terminal. Antes de mexer em qualquer coisa, ele lê o seu projeto: reconhece Next.js (App Router e Pages Router), Astro, Express, Laravel, Django, Flask e FastAPI, e diz o que vai integrar. No menu, você pode trocar o framework, ver a lista exata do que ele vai fazer ou abrir Privacidade e dados antes de continuar.

Ele precisa de um terminal de pelo menos 80 por 28 caracteres; com --simple, abre a versão em linha. Fala espanhol, inglês, português, francês e alemão conforme o seu sistema, ou o idioma que você definir com CORD_LANG. E tudo o que o assistente faz continua disponível como comandos avulsos para scripts e CI, cada um com --json.

Você entra pelo navegador, sem copiar chaves

Para conectar a sua conta, o terminal abre o seu navegador na página de autorização. Lá você escolhe a organização, vê que o assistente só trabalha no modo de teste e decide o que a chave do seu projeto pode fazer: cinco recursos (produtos, clientes, orçamentos, webhooks e Elements), cada um sem acesso, com leitura ou com escrita. O sugerido é o mínimo que os arquivos que ele vai criar usam: ler o seu catálogo e escrever orçamentos e a configuração do Elements.

Você clica em Autorizar assistente, o Cord confirma que é você e o terminal se conecta sozinho. Não há código para comparar nem chave para colar.

O terminal espera; no navegador, você escolhe a organização e as permissões da chave do projeto.

Como funciona por dentro

O retorno ao terminal segue o padrão dos apps nativos com OAuth (RFC 8252) mais PKCE (RFC 7636). O terminal abre uma porta aleatória em 127.0.0.1, gera um code_verifier que nunca sai do seu computador e manda ao Cord só o hash S256 dele, junto com um state. Quando você autoriza, o Cord devolve o navegador para 127.0.0.1/callback com um código de uso único, e o terminal o troca usando o verificador.

Sem o verificador, o código do navegador não serve para nada: interceptá-lo não basta para levar as chaves.

Algumas decisões que não são óbvias:

  • No banco de dados só ficam hashes. Do device code e do código do navegador, o Cord guarda o sha256, nunca o valor.
  • O retorno só aceita o seu próprio computador. O endereço tem de ser 127.0.0.1 ou localhost com uma porta e o caminho /callback; qualquer outro é rejeitado já no pedido de login.
  • As chaves são entregues uma única vez. Ficam criptografadas até que o terminal as reivindique e, nesse momento, são apagadas.
  • Duas chaves com trabalhos diferentes. A da CLI é restrita e de teste, expira em 90 dias e só usa simuladores, eventos, propostas de configuração e o assistente com IA; não conta no limite de chaves do seu plano. A do projeto leva as permissões que você escolheu, conta como uma chave do seu plano e é salva no seu .env.local.

Por SSH, na CI, com --no-browser ou com --json não há navegador para onde voltar: aí a CLI usa o código para comparar, o fluxo de dispositivo que contamos em cord login sem copiar chaves.

O assistente trabalha à vista

Enquanto integra, a tela mostra cada tarefa com o seu progresso, a ação em andamento e quatro abas: Status, Registro (cada arquivo que ele lê ou escreve e cada comando que executa), Novidades (o mais recente que saiu no Cord) e Visualizador.

As tarefas são marcadas conforme terminam; o que não se aplica ao seu projeto é pulado, e o assistente avisa.

Em um projeto Next.js com App Router, o assistente:

  1. Instala @flouviahq/node e @flouviahq/elements com o seu gerenciador de pacotes (npm, pnpm, yarn ou bun, conforme o seu lockfile).
  2. Cria app/api/webhooks/cord/route.ts, que verifica a assinatura de cada webhook com o corpo bruto.
  3. Cria app/api/cord/[...path]/route.ts, o proxy pelo qual o Cord Elements fala com o Cord sem expor a sua chave.
  4. Salva a chave do projeto em .env.local.
  5. Se você informou o seu site e o que faz, pede ao Cord uma proposta de configuração (produtos, impostos e modelos) que você aprova no navegador.
  6. Escreve CORD-INTEGRACION.md com o que mudou.

Três regras que ele nunca quebra: não sobrescreve um arquivo que já existe, só grava chaves em um arquivo de ambiente que o git ignora e não mexe nas outras linhas do seu .env.

A IA que integra, e os seus limites

A 2.1 traz um agente que lê o seu projeto e adapta a integração a ele: posiciona as rotas na sua estrutura, monta o gerador de orçamentos na sua página e depois executa o seu build e os seus testes. Ele raciocina no Cord, mas as ferramentas dele rodam no seu computador e ficam restritas à pasta do projeto:

  • Nunca abre um .env*, a sua pasta .git nem node_modules. Um caminho que sai do projeto, inclusive por um link simbólico, falha.
  • Só executa comandos de uma lista: instalar pacotes @flouviahq/* com npm, pnpm, yarn ou bun, os seus scripts de build, lint, typecheck e testes, e npx tsc --noEmit. Qualquer outro, ou um com caracteres de shell, é rejeitado e fica no registro.

Hoje o Cord ainda não o liga: o servidor responde que o assistente não está disponível e a CLI segue com modelos, sem que você precise fazer nada. Vamos ligá-lo quando a nossa divulgação sobre inteligência artificial cobrir que a IA leia o código de quem integra. Então o assistente vai perguntar se você quer integrar com IA ou com modelos, e tudo o que ele mudar ficará em CORD-INTEGRACION.md.

Antes de começar, Privacidade e dados diz o que sai do seu computador e o que nunca sai.

Conecte os apps que você já usa

O assistente procura nas suas dependências (package.json, composer.json ou as do Python) os SDKs dos apps que o Cord conecta: @hubspot/api-client é HubSpot, @shopify/shopify-api ou Hydrogen é Shopify, @slack/bolt ou @slack/web-api é Slack. Também reconhece QuickBooks Online, Xero, Google Sheets e Microsoft Teams.

Se encontrar algum, ele oferece conectá-lo ao Cord. Você pressiona o, a página dessa integração abre no seu navegador e, quando você termina, a tela se marca sozinha. Para saber disso, o Cord só responde o status de cada conexão, nunca um dado dela.

O HubSpot foi conectado pelo navegador; Shopify e Slack esperam a vez deles.

O MCP do Cord nos seus agentes

Ao terminar, o assistente oferece deixar o servidor MCP do Cord no Claude Code (.mcp.json), no Cursor (.cursor/mcp.json) e no VS Code (.vscode/mcp.json). Ele só escreve o endereço do servidor, sem mexer nos outros que você já tenha: na primeira vez, o seu agente pede que você autorize no Cord com OAuth, então nenhum arquivo leva uma chave.

Você marca os agentes com a barra de espaço e o assistente escreve o arquivo de cada um.

Com o MCP, o seu agente consulta orçamentos, clientes e pagamentos e prepara rascunhos. O que envia, cobra ou altera um cliente, você aprova no Cord. O mesmo existe como comandos: cord mcp add, cord mcp remove e cord mcp tutorial, que explica como adicioná-lo como conector personalizado no Claude e no ChatGPT. Os detalhes estão no guia do MCP.

Webhooks assinados no seu localhost

cord listen abre uma sessão de teste e reencaminha cada evento para o seu servidor com a mesma assinatura que a produção usaria. Com --env-file, ele salva o segredo de assinatura no seu .env.local, e esse segredo é o mesmo em todas as sessões da sua chave: reiniciar não obriga você a trocá-lo.

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

Cada reencaminhamento é confirmado: se o seu servidor não responder, o evento volta para a fila e é reenviado após 5, 15, 30 e 60 segundos. Em outro terminal, cord trigger dispara qualquer evento do catálogo; com --objeto e o id de um orçamento ou de uma fatura de teste, o evento leva os dados reais deles.

Dispare um evento em um terminal e veja-o chegar à sua rota, assinado, no outro.

Há mais comandos para o dia a dia: cord events tail e cord logs tail mostram eventos e requisições à medida que chegam, cord api chama qualquer rota com a sua chave e cord simulate força o resultado da próxima emissão fiscal ou faz um orçamento expirar. O guia da CLI tem a lista completa.

No final, um resumo

O assistente termina com o que fez, o que falta e os webhooks já escutando no seu servidor local. O que mudou fica em CORD-INTEGRACION.md, sem nenhum valor do seu .env.

O resumo diz o que ficou pronto e o que falta, com o link para concluir.

Experimente

Você precisa do Node 22 ou posterior e de uma conta do Cord.

npx create-next-app@latest minha-loja --ts --app
cd minha-loja
npx @flouviahq/cli

Quando terminar, deixe npm run dev rodando em um terminal e execute npx @flouviahq/cli trigger quote.approved em outro: o evento chega à sua rota, assinado, e o assistente mostra o 200.

FIM DO ARTIGO

Da proposta ao pagamento. Tudo em um só link.

Envie um orçamento que seu cliente aprova e paga em um só link, sem criar conta, e fature com um clique. Em 12 países, com plano gratuito e sem cartão.

Criar conta grátisVer preços
COMPARTILHAR
Twitter/XLinkedIn