Agents & scripting
The factuarea CLI agent-first contract — stable JSON on stdout, structured errors on stderr, semantic exit codes, the commands --json manifest, local scope-check and typed confirmation for irreversible operations.
The CLI is agent-first: an AI assistant or a script can discover the whole surface in one call, get stable machine-readable output, and branch on semantic exit codes instead of parsing prose.
Discover the surface in one call
factuarea commands --jsonThis dumps the full command manifest. Each entry carries:
| Field | Meaning |
|---|---|
path | The command path, e.g. invoices create. |
args | Positional arguments (path params). |
flags | Available flags. |
mutating | Whether the command writes (needs --live in production). |
binary | Whether it returns a binary (PDF/ZIP/XML) instead of JSON. |
paginated | Whether the command supports cursor pagination. |
required_scope | The scope the API key must hold, e.g. invoices:read. |
irreversible | Whether the operation cannot be undone. |
example | A ready-to-adapt example invocation. |
required_scope and irreversible come straight from the OpenAPI spec's
x-required-scope and x-irreversible extensions, so the CLI and the
API reference agree by
construction.
Output contract
--jsonemits the raw API body on stdout.- Errors go to stderr as structured JSON — the same
error envelope as the API:
error.{type,code,message,request_id,doc_url}. - Keep stdout for data and stderr for diagnostics: pipe stdout to
jq, log stderr.
Exit codes
Branch on the exit code, never on the message:
| Code | Meaning |
|---|---|
0 | OK |
2 | Local usage / guard error |
3 | Authentication failed |
4 | Permission / missing scope |
5 | Validation error |
6 | Not found |
7 | Rate limit |
8 | Conflict / idempotency |
9 | Server error |
10 | Network / timeout |
Local scope-check
Before a call, the CLI checks that your key holds the operation's
required_scope. If it doesn't, the command fails locally with exit 4 and
a clear message — no wasted round trip that the API would reject with 403
anyway.
- The check only runs when the operation declares a scope and resolves the key's
scopes lazily (one
GET /v1/accountper invocation at most, memoized). - A
*scope on the key covers any operation. --skip-scope-checkdowngrades the block to a warning and continues — useful if your cached scopes are stale. The API's real403is still the last line of defense.
Irreversible operations
Operations the spec marks x-irreversible (deletes, void, terminal
conversions, fiscal emission, certificate rotation, GDPR forget…) ask for a
typed confirmation before the call:
factuarea invoices delete <uuid> --confirm <uuid>- Pass
--confirm <id>with the resource id to proceed. - In a non-interactive context (
--no-inputor no TTY) without--confirm, the command refuses with exit2rather than guessing.
See the scopes & irreversibility guide for the full list of which operations carry each scope and which are irreversible.
Want the agent to operate Factuarea through tools instead of CLI commands? Connect it to the MCP server — the same surface exposed as tools, with OAuth and API-key auth.