Usage

The command tree covers every resource in the API (factuarea <resource> [<sub-resource>] <action>), generated from the OpenAPI spec so it never drifts from the live surface.

Reading data

# List (with automatic cursor pagination)
factuarea invoices list --json
factuarea clients list --paginate --json

# Get one
factuarea invoices show <uuid> --json

--json emits the raw API body on stdout. --paginate walks every page for you, following next_cursor until has_more is false. See Pagination for the underlying cursor semantics.

Writing data

Pass the JSON body with -d (inline) or --data-file (a path). The API computes totals — do not pre-round them.

factuarea invoices create -d '{"client_id":"…","series_id":"…","lines":[…]}'

Every mutation gets an automatic Idempotency-Key so a retried request never double-creates a resource. See Idempotency.

Domain actions

State changes are discrete actions, not a generic status flag — mirroring the API's own design:

factuarea invoices send <uuid>
factuarea invoices mark-paid <uuid>

Time tracking (control-horario)

The control-horario add-on adds workforce resources — employees, work schedules, time entries, absences, presence, holidays, monthly closes and the gestoría summary. Each command is generated from the spec and gated by its fine-grained scope (employees:*, time_entries:*, absences:*, work_schedules:*, presence:read, holidays:read, payroll_exports:*).

# Clock an employee in and out — every entry is hash-chained (RD-ley 8/2019)
factuarea time-entries clock-in  -d '{"employee_id":"…","source":"web"}'
factuarea time-entries clock-out -d '{"employee_id":"…","source":"web"}'

# Request time off, then approve it
factuarea absence-requests create \
  -d '{"employee_id":"…","absence_type_id":"…","start_date":"2026-08-01","end_date":"2026-08-05"}'
factuarea absence-requests approve <uuid>

# Live team presence right now
factuarea presence live --json

# Close a month's immutable register, then export it (ITSS RD-ley 8/2019)
factuarea monthly-time-record-closes create -d '{"year":2026,"month":7}'
factuarea monthly-time-record-closes export <uuid> --format rdley_8_2019 --json

Binary downloads and uploads

PDF, ZIP and XML endpoints stream a binary you save with -o. Multipart uploads take the file with a --file-<field> flag:

# Download a PDF
factuarea invoices pdf <uuid> -o invoice.pdf

# Upload a certificate (multipart)
factuarea verifactu certificates upload \
  -d '{"certificate_password":"…"}' --file-certificate_file cert.p12

The api escape hatch

Any endpoint is reachable directly with factuarea api <method> <path>, even ones without a dedicated command yet:

factuarea api get /v1/account --json
factuarea api post /v1/invoices -d '{…}'

The command manifest

factuarea commands --json dumps the full manifest of commands in one call — path, args, flags, whether each mutates, whether it is binary or paginated, its required scope, whether it is irreversible, and an example. An agent discovers the entire surface in a single call:

factuarea commands --json

See Agents & scripting for the manifest fields and the JSON contract.

Embedded API reference

A quick API reference travels with the binary — searches stay on your machine:

factuarea docs search invoice

docs search reads the OpenAPI spec embedded in the binary and answers "which command do I call?". It returns operations — command, summary, method and path — and never touches the network.

Searching the published docs

docs list, docs grep and docs get read the published documentation — the llms-full corpus of docs.factuarea.com — and answer "what do the docs say about this?". They return pages and sections, from the guides, the API reference and the error catalog:

factuarea docs list                    # every page: <path> — <title>
factuarea docs list /guides            # only the ones under that prefix
factuarea docs grep "idempotency-key"  # documentation sections that match
factuarea docs get /guides/idempotency # the whole page, as Markdown

The corpus is downloaded whole and once, stored in the system cache directory (~/Library/Caches/factuarea/docs/ on macOS, ~/.cache/factuarea/docs/ on Linux) and filtered locally. While the copy is younger than 15 minutes no network request happens at all, so a session that chains list, grep and get downloads once.

If the download fails and a cached copy exists — even an expired one — that copy is used, a warning goes to stderr so the JSON on stdout stays parseable, and the exit code is 0. With no copy at all, the exit code is 10 (network). Set FACTUAREA_DOCS_URL to fetch the corpus from another origin.