CLI

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:

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.

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.

facturadirecta login --device

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

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

Elegir empresa#

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#

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.

Formatos de salida#

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:

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

Mantenerlo al día#

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.