For agents

The BankSync CLI is a first-class tool for AI agents, not only for humans. A shell tool plus an API key gives an agent everything it needs to read financial data, manage feeds, and trigger syncs, with a contract stable enough to build on. In practice, a well-designed CLI is often a better agent surface than a bespoke API integration: the output is structured, the errors are machine-readable, and the whole command surface is discoverable at runtime.

Give your agent the CLI and a key#

The contract an agent can rely on#

The JSON envelope#

Ask for JSON with --json (any pipe also triggers it). Every read has the same top-level shape regardless of the command:

{  "data": [    {      "id": "txn_1",      "date": "2026-03-01",      "description": "UBER",      "amount": -24.5,      "currency": "USD"    }  ],  "meta": {    "count": 1,    "cursor": "eyJvIjoxMDB9",    "has_more": true,    "schema_version": "1",    "api_version": "v1"  }}

• data holds raw entity fields (ISO dates, unformatted numbers), never humanized strings.
• meta.cursor and meta.has_more drive pagination; when they are null the endpoint does not paginate.
• meta.schema_version is the output-contract version. It is also emitted by commands --json, so an agent can assert the contract it was built against.

Errors and exit codes#

In JSON mode, an error is a single object on stderr while stdout stays empty:

{  "error": {    "code": "rate_limited",    "message": "Too many requests.",    "status": 429,    "hint": "Rate limited. Retrying automatically; slow down or pass --no-retry.",    "retry_after": 60  }}

The process exit code classifies the failure so an agent can react programmatically:

An agent that gets exit code 3 knows to check the credential; a 5 on a sync means it should retry with --force; a 7 means back off.

Discover the whole surface at runtime#

An agent does not need to read documentation to act. Two commands expose everything, and neither emits telemetry.

Command catalog#

banksync commands --json returns the entire command tree, plus the exit-code map and the output-contract version:

banksync commands --json

{  "cli": "banksync",  "output_contract_version": "1",  "api_version": "v1",  "exit_codes": {    "0": "Success",    "3": "Unauthenticated or forbidden (401/403)",    "5": "Conflict (409)"  },  "commands": [    {      "id": "transactions list",      "summary": "List transactions for a bank or a single account, resolving names or partial ids.",      "aliases": ["tx"],      "args": [{ "name": "bid", "required": false, "description": "Bank id or name." }],      "flags": [        {          "name": "from",          "type": "option",          "required": false,          "description": "Start date YYYY-MM-DD."        },        {          "name": "all",          "type": "boolean",          "required": false,          "description": "Fetch all pages (follows the cursor)."        }      ]    }  ]}

The agent enumerates command ids, required args, flag names, types, and enum options directly from this output, then constructs a call.

Entity schema#

banksync schema --json lists the entities, and banksync schema <entity> --json returns the default columns (the selectable dot-paths for --fields):

banksync schema --jsonbanksync schema transaction --json

{  "data": {    "entity": "transaction",    "default_columns": ["date", "description", "amount", "currency", "category", "pending"]  },  "meta": { "count": 1 }}

Known entities include bank, account, balance, transaction, trade, holding, order, loan, feed, job, enrichment, integration, and institution.

Stream large reads with NDJSON#

For a large pull, -o ndjson emits one raw entity per line, which an agent can consume incrementally without buffering the whole response:

banksync tx list --bank amex --all -o ndjson

Each line is a complete JSON object, ideal for streaming into a processing loop.

The raw API escape hatch#

Any endpoint that does not yet have a dedicated command is reachable through banksync api, which reuses the same auth, retries, and output path. It takes an HTTP method and path, an optional body (inline JSON, @file, or - for stdin), and repeatable --query params:

banksync api GET /v1/banksbanksync api GET /v1/feeds --query dataType=transactionsecho '{"name":"My rule"}' | banksync api POST /v1/enrichments --data -

In a machine format, the raw response body is echoed verbatim, so an agent sees exactly what the API returned. This future-proofs the surface: an agent is never blocked by a missing command.

Non-interactive guarantees#

A worked example#

An agent asked to summarize spending would typically:

# 1. Confirm the credential and workspacebanksync whoami --json
# 2. Find the bank by namebanksync banks list --json | jq -r '.data[] | select(.name|test("Amex";"i")) | .id'
# 3. Pull the quarter's transactions as a streambanksync tx list --bank amex --from 2026-01-01 --to 2026-03-31 --all -o ndjson
# 4. On exit code 3, stop and report an auth problem; on 7, back off and retry

Each step is structured input and structured output, with a clear exit code, so the agent can chain steps and recover from failure on its own.

Next steps#

• Scripting and CI: the same guarantees for shell automation.
• Output formats: the envelope, NDJSON, and TOON.
• Telemetry: what usage data is collected and how to disable it.
• MCP server guide: the same data exposed to agents over the Model Context Protocol.