CLI

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:

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.

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.

facturadirecta login --device

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

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

Choosing a company#

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#

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 (in Spanish).

Output formats#

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:

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

Keeping it up to date#

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.