# CLI

> Instal·la la CLI de FacturaDirecta per consultar i automatitzar factures, despeses, contactes i comptabilitat des del terminal, en scripts o amb agents de codi com Claude Code i Codex.


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:

```shell
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.

```shell
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.

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

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

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

## Triar empresa

```shell
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

```shell
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](https://www.facturadirecta.com/desarrolladores/cli/comandos/) (en castellà).

## Formats de sortida

| Opció | Què retorna |
|---|---|
| *(cap)* | Taula llegible al terminal |
| `--json`, `-j` | JSON complet |
| `--quiet`, `-q` | Només les dades en JSON, sense metadades |
| `--summary` | Resum compacte per element: número, data, contacte, totals, estat, saldo pendent i enllaç |
| `--ids-only` | Només els identificadors, un per línia |
| `--count` | Només el nombre de resultats |
| `--jq <filtre>` | Filtre jq integrat sobre el JSON |

## Ú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:

| Codi | Significat |
|---|---|
| `0` | Correcte |
| `2` | Ús o entrada no vàlida |
| `3` | Sessió, només lectura o permisos |
| `4` | No trobat |
| `5` | Empresa sense indicar |
| `6` | Error de l'API o de xarxa |
| `1` | Qualsevol altre error |

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

## Mantenir-la al dia

```shell
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](https://www.facturadirecta.com/ca/desarrolladores/mcp/).