El CLI de Cord: tu integración lista desde la terminal

Qué hace el CLI de Cord 2.1: entras desde el navegador, integra tu proyecto, conecta tus apps, deja el MCP en tus agentes y prueba webhooks en localhost.

ARTÍCULO
EN ESTE ARTÍCULO9 SECCIONES

Integrar una plataforma de cobros suele empezar igual: buscar la sección de llaves en un panel, copiar una cadena larga a un .env, escribir la ruta que recibe los webhooks, verificar su firma, abrir un túnel para probarla en tu máquina y repetir todo cuando cambias de computadora. Queríamos que con Cord fuera un solo comando:

npx @flouviahq/cli

Anoche publicamos la versión 2.1 de @flouviahq/cli. Este artículo cuenta qué hace, pantalla por pantalla. Las imágenes son calcas del asistente real: los mismos textos, colores y pasos que vas a ver en tu terminal.

Al abrirse, el asistente ya sabe dónde está: la carpeta, el framework y las apps que tu proyecto usa.

Un asistente en pantalla completa

Sin comando, el CLI abre un asistente que ocupa la terminal. Antes de tocar nada lee tu proyecto: reconoce Next.js (App Router y Pages Router), Astro, Express, Laravel, Django, Flask y FastAPI, y te dice qué va a integrar. Desde el menú puedes cambiar de framework, ver la lista exacta de lo que va a hacer o abrir Privacidad y datos antes de continuar.

Necesita una terminal de al menos 80 por 28 caracteres; con --simple abre la versión en línea. Habla español, inglés, portugués, francés y alemán según tu sistema, o el idioma que fijes con CORD_LANG. Y todo lo que hace el asistente sigue disponible como comandos sueltos para scripts y CI, cada uno con --json.

Entras desde el navegador, sin copiar llaves

Para conectar tu cuenta, la terminal abre tu navegador en la página de autorizar. Ahí eliges la organización, ves que el asistente solo trabaja en modo de prueba y decides qué puede hacer la llave de tu proyecto: cinco recursos (productos, clientes, cotizaciones, webhooks y Elements), cada uno sin acceso, en lectura o en escritura. Lo sugerido es lo mínimo que usan los archivos que va a crear: leer tu catálogo y escribir cotizaciones y la configuración de Elements.

Pulsas Autorizar asistente, Cord confirma que eres tú y la terminal se conecta sola. No hay código que comparar ni llave que pegar.

La terminal espera; en el navegador eliges la organización y los permisos de la llave del proyecto.

Cómo funciona por dentro

El regreso a la terminal sigue el patrón de las apps nativas con OAuth (RFC 8252) más PKCE (RFC 7636). La terminal abre un puerto al azar en 127.0.0.1, genera un code_verifier que nunca sale de tu equipo y manda a Cord solo su huella S256, junto con un state. Al autorizar, Cord devuelve el navegador a 127.0.0.1/callback con un código de un solo uso, y la terminal lo canjea con el verificador.

Sin el verificador, el código del navegador no sirve: interceptarlo no alcanza para llevarse las llaves.

Algunas decisiones que no son obvias:

  • En la base solo viven huellas. Del device code y del código del navegador Cord guarda el sha256, nunca el valor.
  • El regreso solo acepta tu propia computadora. La dirección tiene que ser 127.0.0.1 o localhost con un puerto y la ruta /callback; cualquier otra se rechaza al pedir el inicio de sesión.
  • Las llaves se entregan una vez. Viven cifradas hasta que la terminal las reclama, y en ese momento se borran.
  • Dos llaves con trabajos distintos. La del CLI es restringida y de prueba, vence en 90 días y solo usa simuladores, eventos, propuestas de configuración y el asistente; no cuenta en el tope de llaves de tu plan. La del proyecto lleva los permisos que elegiste, cuenta como una llave de tu plan y se guarda en tu .env.local.

Por SSH, en CI, con --no-browser o con --json no hay navegador al que volver: ahí el CLI usa el código para comparar, el flujo de dispositivo que contamos en cord login sin copiar llaves.

El asistente trabaja a la vista

Mientras integra, la pantalla muestra cada tarea con su avance, la acción en curso y cuatro pestañas: Estado, Registro (cada archivo que lee o escribe y cada comando que corre), Novedades (lo último que salió en Cord) y Visualizador.

Las tareas se marcan conforme terminan; lo que no aplica a tu proyecto se omite y se dice.

En un proyecto de Next.js con App Router, el asistente:

  1. Instala @flouviahq/node y @flouviahq/elements con tu gestor de paquetes (npm, pnpm, yarn o bun, según tu archivo de bloqueo).
  2. Crea app/api/webhooks/cord/route.ts, que verifica la firma de cada webhook con el cuerpo crudo.
  3. Crea app/api/cord/[...path]/route.ts, el proxy por el que Cord Elements habla con Cord sin exponer tu llave.
  4. Guarda la llave del proyecto en .env.local.
  5. Si le diste tu sitio y a qué te dedicas, pide a Cord una propuesta de configuración (productos, impuestos y plantillas) que apruebas en el navegador.
  6. Escribe CORD-INTEGRACION.md con lo que cambió.

Tres reglas que nunca rompe: no sobrescribe un archivo que ya existe, solo escribe llaves en un archivo de entorno que git ignora y no toca las demás líneas de tu .env.

La IA que integra, y sus límites

La 2.1 trae un agente que lee tu proyecto y adapta la integración a él: ubica las rutas en tu estructura, monta el cotizador en tu página y después corre tu build y tus pruebas. Razona en Cord, pero sus herramientas corren en tu equipo y están encerradas en la carpeta del proyecto:

  • Nunca abre un .env*, tu carpeta .git ni node_modules. Una ruta que sale del proyecto, también por un enlace simbólico, falla.
  • Solo corre comandos de una lista: instalar paquetes @flouviahq/* con npm, pnpm, yarn o bun, tus scripts de build, lint, typecheck y pruebas, y npx tsc --noEmit. Cualquier otro, o uno con caracteres de shell, se rechaza y queda en el registro.

Hoy Cord todavía no lo enciende: el servidor responde que el asistente no está disponible y el CLI sigue con plantillas, sin que tengas que hacer nada. Lo vamos a encender cuando nuestra Divulgación sobre inteligencia artificial cubra que la IA lea el código de quien integra. Entonces el asistente te preguntará si integra con IA o con plantillas, y todo lo que cambie quedará en CORD-INTEGRACION.md.

Antes de empezar, Privacidad y datos dice qué sale de tu equipo y qué no sale nunca.

Conecta las apps que ya usas

El asistente busca en tus dependencias (package.json, composer.json o las de Python) los SDK de las apps que Cord conecta: @hubspot/api-client es HubSpot, @shopify/shopify-api o Hydrogen es Shopify, @slack/bolt o @slack/web-api es Slack. También reconoce QuickBooks Online, Xero, Google Sheets y Microsoft Teams.

Si encuentra alguna, te ofrece conectarla con Cord. Pulsas o, se abre la página de esa integración en tu navegador y, cuando terminas, la pantalla se marca sola. Para saberlo, Cord solo responde el estado de cada conexión, nunca un dato de ella.

HubSpot quedó conectada desde el navegador; Shopify y Slack esperan su turno.

El MCP de Cord en tus agentes

Al terminar, el asistente ofrece dejar el servidor MCP de Cord en Claude Code (.mcp.json), Cursor (.cursor/mcp.json) y VS Code (.vscode/mcp.json). Solo escribe la dirección del servidor, sin tocar los demás que ya tengas: la primera vez, tu agente te pide autorizar en Cord con OAuth, así que ningún archivo lleva una llave.

Marcas los agentes con espacio y el asistente escribe su archivo.

Con el MCP, tu agente consulta cotizaciones, clientes y cobros y prepara borradores. Lo que envía, cobra o cambia un cliente lo apruebas tú en Cord. Lo mismo está como comandos: cord mcp add, cord mcp remove y cord mcp tutorial, que explica cómo agregarlo como conector personalizado en Claude y ChatGPT. El detalle está en la guía del MCP.

Webhooks firmados en tu localhost

cord listen abre una sesión de prueba y reenvía cada evento a tu servidor con la misma firma que usaría producción. Con --env-file guarda el secreto de firma en tu .env.local, y es el mismo en cada sesión de tu llave: reiniciar no te obliga a cambiarlo.

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

Cada reenvío se confirma: si tu servidor no responde, el evento vuelve a la cola y se reintenta a los 5, 15, 30 y 60 segundos. En otra terminal, cord trigger dispara cualquier evento del catálogo; con --objeto y el id de una cotización o factura de prueba, el evento lleva sus datos reales.

Dispara un evento en una terminal y míralo llegar a tu ruta, firmado, en la otra.

Hay más comandos para el día a día: cord events tail y cord logs tail muestran eventos y peticiones conforme llegan, cord api llama a cualquier ruta con tu llave y cord simulate fuerza el resultado de la próxima emisión fiscal o vence una cotización. La guía del CLI tiene la lista completa.

Al final, un resumen

El asistente termina con lo que hizo, lo que falta y los webhooks ya escuchando en tu servidor local. Lo que cambió queda en CORD-INTEGRACION.md, sin ningún valor de tu .env.

El resumen dice qué quedó listo y qué falta, con el enlace para terminarlo.

Pruébalo

Necesitas Node 22 o posterior y una cuenta de Cord.

npx create-next-app@latest mi-tienda --ts --app
cd mi-tienda
npx @flouviahq/cli

Cuando termine, deja npm run dev en una terminal y corre npx @flouviahq/cli trigger quote.approved en otra: el evento llega a tu ruta, firmado, y el asistente te muestra el 200.

FIN DEL ARTÍCULO

De la propuesta al pago. Todo en un solo link.

Envía una cotización que tu cliente aprueba y paga desde un solo link, sin crear cuenta, y factúrala en un clic. En 12 países, con plan gratis y sin tarjeta.

Crear cuenta gratisVer precios
COMPARTIR
Twitter/XLinkedIn