# @flouviahq/cli

> **Para asistentes de IA / For AI assistants:** este README es un resumen. Antes de decidir qué
> soporta Cord, lee [llms.txt](https://cordhq.app/llms.txt) (qué existe y qué no) y
> [llms-full.txt](https://cordhq.app/llms-full.txt) (toda la documentación en un archivo).
> Spec: [openapi.json](https://cordhq.app/openapi.json). Existen hoy: llaves restringidas `rk_`
> (permiso por recurso, IPs permitidas, vencimiento), registro de peticiones en el panel
> (Desarrolladores › Registros), versionado por `Cord-Version`, paginación por cursor,
> `Idempotency-Key`, webhooks firmados, modo prueba con simuladores y servidor MCP.

CLI de desarrollo de [Cord](https://cordhq.app). Trabaja solo con llaves de prueba y en tu entorno de prueba. La excepción es `cord setup`: propone la configuración de tu cuenta real, y nada se aplica hasta que la apruebas en el navegador.

```bash
npx @flouviahq/cli   # el asistente: conecta, configura e integra paso a paso
```

O comando por comando:

```bash
npm install -g @flouviahq/cli
cord login     # abre tu navegador, confirmas el código y la terminal queda conectada
cord status    # organización, llave, permisos y vencimiento
cord setup     # Cord propone la configuración de tu cuenta; tú la apruebas en el navegador
cord init      # detecta tu framework y deja el webhook verificado listo
```

Cada comando tiene su ayuda: `cord <comando> --help`. Todos aceptan `--json` (un objeto por línea, para scripts), `--yes` (sin preguntas, para CI), `--debug` y `--profile`. El CLI habla español, inglés, portugués, francés y alemán según tu sistema o `CORD_LANG`.

## Iniciar sesión

`cord login` abre tu navegador con un código de confirmación. Revisa que coincida con el de la terminal y autoriza: la terminal recibe una llave restringida de prueba (simuladores, eventos y proponer configuraciones) que vence en 90 días. Se entrega una sola vez y puedes revocarla en Desarrolladores › API.

Sin navegador, `cord login --no-browser` imprime la dirección. Para pegar una llave tuya, `cord login --api-key`. La llave del CLI no cuenta en el tope de llaves de tu plan, y `cord logout` la revoca en Cord.

## Configurar tu cuenta con IA

```bash
cord setup --sitio tuempresa.com --descripcion "Distribuidora de materiales" --archivo precios.xlsx
```

Sin opciones te pregunta. Cord lee tu sitio, tu descripción y tu lista de precios (`.csv`, `.xlsx`, `.pdf` o foto, hasta 3 MB) y propone perfil, marca, impuestos, catálogo y plantillas. La revisión se abre en tu navegador: nada se aplica hasta que la apruebas, y la terminal muestra el resultado.

## Webhooks en tu localhost

```bash
cord listen --forward-to http://localhost:3000/api/webhooks/cord
```

Cord no puede llegar a tu máquina, así que el CLI abre una sesión en la sandbox: los eventos pasan por el mismo motor de entrega que en producción (firma, versión de la API) y el CLI los reenvía a tu servidor con los headers de firma reales. El secreto de firma es el mismo en cada sesión de tu llave: guárdalo con `--env-file .env.local` (o `--print-secret`) en `CORD_WEBHOOK_SECRET` y verifica con `constructEvent` de `@flouviahq/node` como en producción.

Cada reenvío se confirma: si tu servidor no responde, el evento vuelve a la cola y se reintenta. Por seguridad solo reenvía a `localhost`; para otro host usa `--allow-remote`, y para un `https://` local autofirmado, `--skip-verify`. `--events quote.paid,invoice.paid` limita los eventos. La sesión vence en 24 horas y se cierra con Ctrl+C o al cerrar la terminal.

## Simular

```bash
cord trigger invoice.paid                 # dispara un evento con datos de ejemplo
cord trigger quote.approved --objeto <id> # con los datos reales de una cotización de prueba
cord simulate fiscal pac_caido            # la próxima emisión falla como si el PAC no respondiera
cord simulate quote <id> vencer           # la cotización vence
cord trigger --list                       # el catálogo de eventos
cord events tail --type quote.paid        # muestra los eventos conforme ocurren
cord logs tail --status 4xx               # muestra las peticiones a la API conforme llegan
cord api GET /cotizaciones --query limit=5 # cualquier ruta de la API con tu llave
cord open registros                       # abre el panel en esa pestaña
```

La llave se guarda en `~/.config/cord/config.json` (en Windows, `%APPDATA%\cord\config.json`) con permisos `0600`. También acepta `--api-key` o `CORD_API_KEY`. Autocompletado: `cord completion bash|zsh|fish`.