Usage

The factuarea command tree — list, show, create, domain actions, binary downloads, multipart uploads, the generic api escape hatch and the commands --json manifest.

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>

Some actions are irreversible (deletes, void, conversions, fiscal emission). The CLI asks you to confirm them before the call — see Irreversible operations and the scopes & irreversibility guide.

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