CLI overview

The official factuarea CLI operates the REST API from your terminal, with JSON output, semantic exit codes and a discoverable command catalog generated from the spec bundled with each release.

The current stable release is v0.2.0.

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

macOS and Linux:

brew install --cask factuarea/tap/factuarea

Any 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 | sh

Binaries 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 ./factuarea

macOS 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 prompt

The 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_xxxxxxxxxxxxxxxxxxxxxxxx

Verify

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.

REST fallback

The CLI’s command catalog comes from its bundled spec. In the September 2026 baseline, release v0.2.0 is available and the main-branch spec contains 414 entries, with 38 REST endpoints absent from generated commands. Inspect factuarea commands --json for your installed version. Use the raw HTTP command for a supported REST endpoint missing from that catalog:

factuarea api get /v1/stores