CLI

La CLI de FacturaDirecta porta tota l’API pública al terminal: una ordre per a cada operació, taules llegibles per a persones i JSON per a scripts i agents. Funciona a macOS, Linux i Windows.

Primers passos#

L’assistent de configuració et guia per iniciar sessió i triar empresa:

facturadirecta setup

Si treballes amb un agent de codi, setup també instal·la la skill facturadirecta-cli a Claude Code o Codex, perquè l’agent sàpiga fer servir la CLI pel seu compte.

Iniciar sessió#

Amb el teu usuari de FacturaDirecta: s’obre el navegador per autenticar-te. El mode de només lectura és el predeterminat; demana accés complet només quan necessitis modificar dades.

facturadirecta login                  # Només lectura
facturadirecta login --scope full     # Lectura i escriptura

Sense navegador en aquella màquina (SSH, contenidors, agents sense escriptori), fes servir l’inici de sessió per dispositiu: la CLI mostra una URL i un codi per autoritzar-la des de qualsevol altre dispositiu, inclòs el mòbil.

facturadirecta login --device

També pots fer servir una API key de Configuració → API i integracions. Cada clau dona accés a una sola empresa:

facturadirecta login --api-key <la-teva-api-key> --company <companyId>

Triar empresa#

facturadirecta whoami                          # Usuari, accés i empreses disponibles
facturadirecta auth use-company <companyId>    # Empresa per defecte del perfil

Cada ordre resol l’empresa en aquest ordre: --company, la variable d’entorn FACTURADIRECTA_COMPANY, l’empresa fixada al perfil i, si només en tens una, aquesta.

Exemples#

facturadirecta invoices list --state overdue --summary -q                  # Factures vençudes amb el saldo pendent
facturadirecta accounting summary --min-date 2026-01-01 --group-by month   # Ingressos, despeses i resultat per mes
facturadirecta search "Acme"                                               # Cerca contactes, productes i documents
facturadirecta invoices list --ids-only | xargs -I{} facturadirecta invoices pdf {}   # PDF en lot

Totes les ordres, amb les seves opcions, són a la referència d’ordres (en castellà).

Formats de sortida#

Ús des d’agents i scripts#

Amb --agent (o -j, -q, --jq) la sortida és JSON i els errors van a stderr com una línia JSON amb code, message, status, detail i hint. El codi de sortida indica la classe d’error:

Els llistats retornen 25 resultats per defecte; fes servir --limit (fins a 500) i --offset per paginar.

Mantenir-la al dia#

facturadirecta update

Les credencials es guarden en un fitxer local amb permisos 0600 i pots tenir diversos perfils amb --profile.

Prefereixes parlar amb el teu assistent en lloc d’escriure ordres? Fes servir el servidor MCP.