CLI & AI Agents

financy is an open-source command-line tool for the endpoints documented here.
It reads the same connections, accounts and transactions, with the same
credentials, and adds three things the raw API does not: a freshness rollup, a
stable machine-readable envelope with granular exit codes, and an embedded MCP
server so AI agents can query the data directly.

📘

The CLI is a client for this API, not a replacement for it. Everything it

returns is described under Connections, Accounts & Balances and
Transactions.

⚠️

The data API is available on the Starter and Pro plans only. On the

Free plan every data command exits with code 4.

Install

Node 20 or later is the only prerequisite.

npm install -g financy

Every command also works without installing, which is the usual choice for CI and
for one-off use:

npx financy status

Configure

The CLI needs the three values from the Financy app under Settings → API:
clientId, clientSecret and userId.

financy setup

setup prompts for each value, masks the client secret as it is typed, and
validates all three against the live API before saving — so a wrong value fails
here rather than on the first real command. On success it writes
~/.config/financy/config.json with owner-only permissions (600).

In CI and other non-interactive environments the CLI reads the credentials
straight from the environment, and no config file is needed.

financy setup --no-input reads those same variables and persists them for later
sessions.

If the secret is rotated in the Financy app (Settings → API → Rotate key),
every CLI, script, and local MCP server still holding the old value starts
getting 401. Re-run financy setup (or update FINANCY_CLIENT_SECRET) with
the new secret. See Authentication.

⚠️

Never pass the client secret on a command line. It is recorded in shell

history and visible to anything that can list processes. Let financy setup
prompt for it, or set the variable from a secret store.

financy config prints the resolved endpoints and marks each credential as coming
from the environment or the config file, with the secret masked.

Commands

Connections are created in the Financy UI, never through the API — the CLI reads
them and cannot add one.

Status

status is usually the first command to run. It marks each connection fresh,
stale or in error, so the data can be trusted before it is analysed.

financy status --json

{
  "data": [
    {
      "provider": "hapoalim",
      "status": "ACTIVE",
      "fresh": "2026-08-04",
      "expires": "2026-11-14",
      "accounts": 3
    }
  ],
  "staleThresholdDays": 2
}

fresh is the date the data runs through; compare it against today. A status
other than ACTIVE means the connection itself is broken and must be relinked in
the Financy UI — a refresh will not repair it.

💡

Read staleThresholdDays from the response rather than hard-coding 2.

Banks post with a lag, so a one-day-old feed is normal and a weekend gap is
expected.

Refresh

financy refresh

This is the same initiated refresh offered in the app's connections screen. It is
org-wide — it refreshes every connection, not a chosen one — and it is
asynchronous: the command returning does not mean the data has landed. Poll
status and watch fresh advance.

⚠️

Each call costs 20 credits, whatever the number of connections. A

response of already_running means a refresh was already in flight and is not
charged again.

JSON output and exit codes

Every command accepts --json and returns a stable envelope: {data, count, nextPage}
for lists, {data} for a single resource. Errors go to stderr as
{error: {code, message}}.

financy transactions list \
  --from 2026-07-01 --to 2026-07-31 \
  --all --json

List commands accept --limit, --cursor, and --all to paginate automatically.

Exit codes separate the kinds of failure, so a script can branch without reading
prose:

💡

3 and 4 are the two worth branching on. 3 means the credentials need

fixing. 4 means they are correct and the plan needs upgrading — retrying will
never help.

FINANCY_DEBUG=1 prints raw API response bodies to stderr.

MCP server

The same package ships a Model Context Protocol server, so an AI agent can query
the data without shell plumbing. Register it once:

claude mcp add financy -- npx financy mcp

It runs on stdio and exposes the command surface one-to-one as eleven verb_noun
tools — get_status, list_connections, list_accounts, list_transactions,
refresh_connections and the rest — returning the same envelopes as --json.
Credentials resolve exactly as they do for the CLI; until setup is complete every
tool returns a structured NOT_CONFIGURED error.

⚠️

refresh_connections costs 20 credits. Its tool description instructs the

agent to confirm with the user first.

Remote MCP connector

The local financy mcp server above is one MCP path: it runs on your
machine, authenticates with the same API key as the CLI, and can trigger a
refresh.

A second path is the Financy connector inside an AI client (ChatGPT, Claude,
and other MCP hosts that speak OAuth). That host obtains a token minted for the
MCP resource server and calls the Financy read endpoints directly — no API
key, no CLI, no clientSecret on the agent machine.

📘

For the step-by-step click-path to add the connector in ChatGPT and Claude,

see Connect ChatGPT and Claude.

The connector is fail-closed. Missing scope, a user with no Financy org, a
non-Financy org, or a free plan is a rejection with a body the model can show
the user — it is never treated as an anonymous caller. See Errors.

What the connector can call

These are the same GET routes documented under Connections, Accounts &
Balances, Transactions, and Providers & Branches:

Anything else — including POST /chat/chat/connections/refresh, payment
endpoints, and DELETE /v2/connections/{connectionId} — rejects the connector
token at the gateway (401).

Connection responses additionally drop scaOAuth, verifier, and
callbackInformation so bank-flow secrets and webhook credentials never enter
the model's context. First-party API-key callers still see those fields.

💡

https://mcp.open-finance.ai/ is the OAuth resource identifier (RFC

8707), not an API host. Data still comes from https://api.open-finance.ai.
If a connector token is missing mcp:read, reconnect the Financy connector
in the AI client to grant it.

Agent skills

Skills are instruction files that teach an agent the job rather than the tool.
They ship inside the package, so they cannot drift from the installed CLI version.

financy skills list
financy skills install --all

install copies each skill into the project's .claude/skills/ directory. Two
ship today:

The skills are plain Markdown and can be read before they are installed.

Permissions

The CLI works within the same permission as the underlying connection: reading
data. It cannot move money, make payments, or change anything in a bank account.
The only non-read action is the initiated refresh, which asks for fresher data.

The client secret is stored only on the machine that ran setup, with owner-only
file permissions, and is never printed by any command. The bundled skills instruct
agents never to request it or pass it in a command.

Source

The CLI is open source under Apache-2.0 at
https://github.com/open-finance-ai/financy. Every release is published from CI
with a provenance attestation, so the package on npm can be traced to the commit
and workflow run that built it — npm view financy shows the published metadata.