Overview
Install and authenticate the official factuarea CLI — drive the v1 REST API from your terminal with brew, npm or a curl installer. Agent-first, Stripe-inspired.
The official factuarea CLI drives the v1 REST API
from your terminal. It is agent-first — stable JSON output, semantic exit
codes and one-call discovery — and Stripe-inspired: the full command tree is
generated from the OpenAPI spec, so it never drifts from the live surface.
Prefer an AI agent to operate Factuarea directly? The CLI is built for it. See Agents & scripting for the JSON contract and exit codes, and the MCP server for the tool-based alternative.
Install
The packaged channels go live with the first published release. Until then, build from source.
macOS and Linux:
brew install --cask factuarea/tap/factuareaAny platform with Node 20 or newer:
npm i -g @factuarea/cli # or: npx @factuarea/cli <command>Installs a signed binary into ~/.local/bin:
curl -fsSL https://github.com/factuarea/factuarea-cli/releases/latest/download/install.sh | shBinaries are signed (cosign) and shipped with checksums.txt on
Releases.
Requires Go 1.26 or newer:
git clone https://github.com/factuarea/factuarea-cli && cd factuarea-cli
make build # builds ./factuareamacOS notarization and Windows Authenticode signing land in a later phase. For
now on macOS use brew or npm, or run xattr -d com.apple.quarantine ./factuarea
on a loose binary.
Authenticate
The CLI uses your Factuarea API key. The key prefix selects the environment — there is no separate flag:
fact_test_…→ the isolated sandbox: test data, no real effects (no AEAT transmission, no email, no webhook delivery).fact_live_…→ production: real data.
Log in
factuarea login # prompts for the key on a hidden promptThe key is read on a hidden prompt — never passed as a visible argument. It
is stored in the system keyring (falling back to ~/.config/factuarea/config.toml,
mode 600). Multiple profiles are supported with --profile.
Or set an environment variable
For non-interactive setups:
export FACTUAREA_API_KEY=fact_test_xxxxxxxxxxxxxxxxxxxxxxxxVerify
factuarea whoami # shows the account and the environment (TEST/LIVE)Start every integration with a fact_test_ key. The command surface is
identical to production — swap the prefix to fact_live_ only when your flow
works end-to-end. Production mutations (with a fact_live_ key) also require
the explicit --live flag as a safety net.
What's next
Usage
The generated command tree — list, show, create, domain actions, binary
downloads, the api escape hatch and commands --json.
Devloop
Test webhooks locally without deploying or ngrok: listen forwards events
to your machine, trigger produces real sandbox events.
Agents & scripting
The agent-first contract: stable JSON on stdout, structured errors on stderr, semantic exit codes, scope-check and typed confirmation.
Errors & rate limits
JSON-RPC error shapes mapped from the v1 contract, the full code table, and per-token / per-plan throttling with Retry-After.
Usage
The factuarea command tree — list, show, create, domain actions, binary downloads, multipart uploads, the generic api escape hatch and the commands --json manifest.