@economico/cli

Agent-facing command line interface for Economico — the agent-native general ledger. Every command emits JSON on stdout (or a compact summary with --human), errors go to stderr with a non-zero exit, and request shapes mirror the OpenAPI spec at https://economi.co/openapi.json.

Pair this CLI with the canonical agent guide at https://economi.co/skill.md for the complete reference, the money model, idempotency rules, and the OAuth 2.1 flow for MCP agents.

Install

Persistent install (recommended for long-lived agents):

npm install -g @economico/cli
economico --version

Ephemeral via npx (good for sandboxed agents and CI):

npx -y @economico/cli@latest <command>

Requires Node 20+. Works on Linux, macOS, and Windows.

Sign up

Every business is owned by an email. Sign up once; on subsequent hosts, log in to mint a fresh API key.

# 1. Start signup. Mails a 6-digit OTP to the email.
economico signup --email [email protected] --name "Acme Inc"
# → {"verification_id":"…","email":"…","expires_in_seconds":900}

# 2. Read the code from the email and complete signup.
economico signup verify --id <verification_id> --code 123456
# → {"business":{…},"api_key":"eco_…"}

The API key is written to ~/.config/economico/config.json (mode 0600) and used for every subsequent call. It is shown ONCE in the response — agents should never echo it back to the user unprompted.

To re-key an existing business on a new host:

economico login --email [email protected]
economico login verify --id <verification_id> --code 123456

Configure

| Variable | Default | What it does | | ---------------------- | ---------------------- | ------------------------------------------- | | ECONOMICO_API_URL | https://economi.co | Point at a different deployment. | | ECONOMICO_API_KEY | (from config file) | Bypass the config file entirely. | | XDG_CONFIG_HOME | ~/.config | Base path for the config file. |

Commands

| Command | What it does | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | economico signup / signup verify / login / login verify | Onboard a new business, or mint a fresh API key for an existing one. | | economico parties create / list / get / update | Manage customers and vendors (CRM). | | economico invoices create / list / get / send / void / pay | Full invoice lifecycle: draft, send, void with reversing journal, record payment. | | economico revenue summary --from <date> --to <date> | Per-currency invoiced / paid / outstanding / recognized for the period. | | economico accounts list / get / create / update / archive | Chart-of-accounts management. A starter chart is seeded automatically at signup. | | economico balances | Current balances for all postable accounts. | | economico reports balance-sheet / income-statement | Period-end financial reports. | | economico oauth clients create / list / revoke | Register OAuth 2.1 clients for MCP agents that prefer RFC 7523 private_key_jwt. |

Every command accepts --human for a compact summary instead of raw JSON.

Output

Default JSON, pretty-printed:

economico parties list
# [
#   {
#     "id": "…",
#     "type": "customer",
#     "iri": "did:web:acme.com",
#     "name": "Acme",
#     "url": "https://acme.com",
#     ...
#   }
# ]

Human mode (flatter, no JSON parens):

economico balances --human
#   USD:Cash: 12500
#   USD:AR: 3200
#   ...

Errors go to stderr as a structured envelope and exit non-zero:

{
  "error": "party not found",
  "status": 404,
  "body": { "detail": "party not found" }
}

Money model

• Amount: always an integer in minor units (cents for USD). Never floats.
• Currency: ISO 4217 (USD, EUR), stablecoin shorthand (USDC, USDT, PYUSD), or full CAIP-19 (eip155:8453/erc20:0x833…).
• Idempotency: payment recording is safe to retry. On-chain payments dedupe on (chain_id, tx_hash, log_index, currency, settlement_address, amount); off-chain on (invoice_id, idempotency_key).

Examples

Draft a $2000 invoice for 10 hours of consulting and send it by email:

PARTY_ID=$(economico parties create --type customer --name "Acme" --url https://acme.com | jq -r .id)

economico invoices create \
  --party-id "$PARTY_ID" \
  --amount 200000 \
  --currency USD \
  --due 2026-06-01 \
  --memo "March consulting" \
  --lines '[{"description":"Consulting","quantity_micros":10000000,"unit_price_minor":20000}]'

economico invoices send <invoice_id> --channel email

Record an on-chain stablecoin payment:

economico invoices pay <invoice_id> \
  --amount 200000 \
  --currency USDC \
  --tx-hash 0xdeadbeef… \
  --chain-id eip155:8453 \
  --log-index 0

Read more

• Agent guide (canonical): https://economi.co/skill.md
• OpenAPI 3.1 spec: https://economi.co/openapi.json
• MCP endpoint (alternative to the CLI for native MCP clients): https://economi.co/mcp

License

MIT