# CLI

> Install the FacturaDirecta CLI to query and automate invoices, expenses, contacts and accounting from the terminal, in scripts or with coding agents such as Claude Code and Codex.


The FacturaDirecta CLI brings the whole public API to the terminal: one command per operation, readable tables for people and JSON for scripts and agents. It runs on macOS, Linux and Windows.

## Getting started

The setup assistant guides you through signing in and choosing a company:

```shell
facturadirecta setup
```

If you work with a coding agent, `setup` also installs the `facturadirecta-cli` skill in Claude Code or Codex, so the agent knows how to use the CLI on its own.

## Signing in

With your FacturaDirecta user: the browser opens so you can authenticate. Read-only mode is the default; ask for full access only when you need to change data.

```shell
facturadirecta login                  # Read only
facturadirecta login --scope full     # Read and write
```

With no browser on that machine (SSH, containers, headless agents), use device login: the CLI shows a URL and a code to authorise it from any other device, including your phone.

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

You can also use an API key from **Settings → API and integrations**. Each key gives access to a single company:

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

## Choosing a company

```shell
facturadirecta whoami                          # User, access and available companies
facturadirecta auth use-company <companyId>    # Default company for the profile
```

Each command resolves the company in this order: `--company`, the `FACTURADIRECTA_COMPANY` environment variable, the company set in the profile and, if you only have one, that one.

## Examples

```shell
facturadirecta invoices list --state overdue --summary -q                  # Overdue invoices with their outstanding balance
facturadirecta accounting summary --min-date 2026-01-01 --group-by month   # Income, expenses and result by month
facturadirecta search "Acme"                                               # Search contacts, products and documents
facturadirecta invoices list --ids-only | xargs -I{} facturadirecta invoices pdf {}   # Batch PDFs
```

Every command and its flags are in the [command reference](https://www.facturadirecta.com/desarrolladores/cli/comandos/) (in Spanish).

## Output formats

| Flag | What it returns |
|---|---|
| *(none)* | Readable table in the terminal |
| `--json`, `-j` | Full JSON |
| `--quiet`, `-q` | Only the data as JSON, without metadata |
| `--summary` | Compact summary per item: number, date, contact, totals, state, outstanding balance and link |
| `--ids-only` | Only the IDs, one per line |
| `--count` | Only the number of results |
| `--jq <filter>` | Built-in jq filter on the JSON |

## Use from agents and scripts

With `--agent` (or `-j`, `-q`, `--jq`) the output is JSON and errors go to stderr as a JSON line with `code`, `message`, `status`, `detail` and `hint`. The exit code tells you the class of error:

| Code | Meaning |
|---|---|
| `0` | Success |
| `2` | Invalid usage or input |
| `3` | Session, read-only mode or permissions |
| `4` | Not found |
| `5` | Company not specified |
| `6` | API or network error |
| `1` | Any other error |

List commands return 25 results by default; use `--limit` (up to 500) and `--offset` to paginate.

## Keeping it up to date

```shell
facturadirecta update
```

Credentials are stored in a local file with `0600` permissions, and you can have several profiles with `--profile`.

Would you rather talk to your assistant than type commands? Use the [MCP server](https://www.facturadirecta.com/en/desarrolladores/mcp/).