# CLI

> Instala el CLI de FacturaDirecta para consultar y automatizar facturas, gastos, contactos y contabilidad desde la terminal, en scripts o con agentes de código como Claude Code y Codex.


El CLI de FacturaDirecta lleva toda la API pública a la terminal: un comando para cada operación, tablas legibles para personas y JSON para scripts y agentes. Funciona en macOS, Linux y Windows.

## Primeros pasos

El asistente de configuración te guía para iniciar sesión y elegir empresa:

```shell
facturadirecta setup
```

Si trabajas con un agente de código, `setup` también instala la skill `facturadirecta-cli` en Claude Code o Codex, para que el agente sepa usar el CLI por su cuenta.

## Iniciar sesión

Con tu usuario de FacturaDirecta: se abre el navegador para autenticarte. El modo de solo lectura es el predeterminado; pide acceso completo solo cuando necesites modificar datos.

```shell
facturadirecta login                  # Solo lectura
facturadirecta login --scope full     # Lectura y escritura
```

Sin navegador en esa máquina (SSH, contenedores, agentes sin escritorio), usa el inicio de sesión por dispositivo: el CLI muestra una URL y un código para autorizarlo desde cualquier otro dispositivo, incluido el móvil.

```shell
facturadirecta login --device
```

También puedes usar una API key de **Ajustes → API e integraciones**. Cada clave da acceso a una sola empresa:

```shell
facturadirecta login --api-key <tu-api-key> --company <companyId>
```

## Elegir empresa

```shell
facturadirecta whoami                          # Usuario, acceso y empresas disponibles
facturadirecta auth use-company <companyId>    # Empresa por defecto del perfil
```

Cada comando resuelve la empresa en este orden: `--company`, la variable de entorno `FACTURADIRECTA_COMPANY`, la empresa fijada en el perfil y, si solo tienes una, esa.

## Ejemplos

```shell
facturadirecta invoices list --state overdue --summary -q                  # Facturas vencidas con su saldo pendiente
facturadirecta accounting summary --min-date 2026-01-01 --group-by month   # Ingresos, gastos y resultado por mes
facturadirecta search "Acme"                                               # Busca contactos, productos y documentos
facturadirecta invoices list --ids-only | xargs -I{} facturadirecta invoices pdf {}   # PDFs en lote
```

Todos los comandos, con sus opciones, están en la [referencia de comandos](https://www.facturadirecta.com/desarrolladores/cli/comandos/).

## Formatos de salida

| Opción | Qué devuelve |
|---|---|
| *(ninguna)* | Tabla legible en la terminal |
| `--json`, `-j` | JSON completo |
| `--quiet`, `-q` | Solo los datos en JSON, sin metadatos |
| `--summary` | Resumen compacto por elemento: número, fecha, contacto, totales, estado, saldo pendiente y enlace |
| `--ids-only` | Solo los identificadores, uno por línea |
| `--count` | Solo el número de resultados |
| `--jq <filtro>` | Filtro jq integrado sobre el JSON |

## Uso desde agentes y scripts

Con `--agent` (o `-j`, `-q`, `--jq`) la salida es JSON y los errores van a stderr como una línea JSON con `code`, `message`, `status`, `detail` y `hint`. El código de salida indica la clase de error:

| Código | Significado |
|---|---|
| `0` | Correcto |
| `2` | Uso o entrada no válida |
| `3` | Sesión, solo lectura o permisos |
| `4` | No encontrado |
| `5` | Empresa sin indicar |
| `6` | Error de la API o de red |
| `1` | Cualquier otro error |

Los listados devuelven 25 resultados por defecto; usa `--limit` (hasta 500) y `--offset` para paginar.

## Mantenerlo al día

```shell
facturadirecta update
```

Las credenciales se guardan en un fichero local con permisos `0600` y puedes tener varios perfiles con `--profile`.

¿Prefieres hablar con tu asistente en lugar de escribir comandos? Usa el [servidor MCP](https://www.facturadirecta.com/desarrolladores/mcp/).