financy

Your Open-Finance / Financy banking data — connections, accounts, balances, transactions — in the terminal, with machine-first output for scripting, an embedded MCP server for agents, and agent skills in the box.

npx financy status

Install

npm install -g financy     # or just use npx financy <command>

Node 20+ is the only prerequisite.

Related MCP server: plaid-mcp

Requirements

The CLI talks to your Open-Finance data through the Financy API, which is a paid feature. To use it you must:

1. Register for a Financy account at open-finance.ai.

2. Subscribe to any paid plan (Starter, Pro, or Ultra) — the data API is not available on the free plan (every data command returns exit code 4).

3. Copy your clientId, clientSecret, and userId from the Financy app → Settings → API.

Setup

financy setup                 # interactive prompts (explains where to get the values)
financy setup --no-input      # read FINANCY_CLIENT_ID / _SECRET / _USER_ID from env (agents/CI)

setup validates the credentials against the live API before saving, so an unregistered/free account is caught immediately (exit 3 for bad credentials, 4 for an ineligible plan). Validation happens before anything is written — a failed setup saves nothing and says so.

Windows

The secret prompt echoes one * per accepted character, so you can see the value arriving. If you paste and no *s appear, your console did not paste: the legacy Windows console does not accept Ctrl+V at a prompt — use right-click or Ctrl+Shift+V. A silently dropped paste used to be submitted as a mangled secret and come back as a 401.

The config file lives at %USERPROFILE%\.config\financy\config.json. Windows does not enforce Unix file modes, so it is not restricted to your user the way it is on macOS/Linux — treat it as readable by anything running as you.

If you hand-edit that file, note that PowerShell 5.1's > and Out-File write UTF-16 and Set-Content writes a UTF-8 BOM. The CLI now reads all three, but financy config is the way to check: it reports the file as ok, missing, malformed, or unreadable rather than just showing blank credentials.

Commands

financy status                       Are my connections fresh? one-line-per-bank rollup
financy connections list|get <id>    Bank/card connections and their fetch state
financy accounts list|get <id>       Accounts with balances (securities embedded)
financy transactions list|get <id>   Transactions with --from/--to/--account/--type filters
financy categories                   The category taxonomy (English + Hebrew)
financy providers list|branches      Reference data: banks and branches
financy refresh                      Trigger an on-demand refresh of all connections (20 credits)
financy integrations list|get <id>   Connected business systems (invoicing: Invoice4U, Morning, SUMIT, iCount; clearing: Isracard Business)
financy receivables                  Who owes you what: open and overdue invoices, aged per customer
financy documents list|get           Invoices, receipts and credit notes in a business system
financy customers list|get           Customers in a business system
financy settlements list             Card payouts from a clearing integration (Isracard Business)
financy proposals list|get|create    Document drafts — issued only after you approve them in Financy
financy config                       Show resolved endpoints + credential sources (secret masked)
financy skills list|install          Agent skills bundled with the CLI
financy mcp                          Run the embedded MCP server (stdio)

Debugging tip: financy config shows which endpoints and credentials are in effect (and whether each came from env or the config file) without ever printing the secret. Set FINANCY_DEBUG=1 to have the raw API response bodies printed to stderr.

Every command takes --json for a stable machine-readable envelope ({data, count, nextPage} for lists, {data} for single resources; errors as {error:{code,message}} on stderr). List commands take --limit, --cursor, and --all (auto-paginate). Exit codes: 0 ok · 1 unexpected · 2 usage · 3 auth · 4 plan · 5 credits · 6 not-found · 7 api.

Connect bit (digital wallet) and ask about it

bit can now be connected to Financy as a digital wallet (ארנק דיגיטלי). The connection runs over regulated Open Banking and is read-only: Financy reads the wallet account, its balance, and its transactions. It cannot send or request payments, and there is no savings data.

1. Connect bit — from your phone

bit approves Open Banking consents only inside its mobile app, so start the connection on the phone that has bit installed:

1. Open the Financy app at financy.open-finance.ai in your phone's browser.

2. Connect account → the ארנקים (wallets) tab → bit.

3. Approve the consent in the bit app when it opens, then return to Financy.

Starting from a desktop browser will not work — the approval step has to land in the bit app.

2. Ask about it from the CLI

bit is a connection like any bank or card, with provider id bit. There are no wallet-specific commands; filter by its connection id:

financy connections list          # bit appears with PROVIDER "bit" — copy its ID
financy status                    # is the bit data current?
financy accounts list --connection <bit-connection-id>     # the wallet and its balance
financy transactions list --connection <bit-connection-id> --from 2026-09-01 --all
financy transactions list --connection <bit-connection-id> --from 2026-09-01 --all --json

Leave out --connection and you get every source at once — bit next to your banks (e.g. Bank Hapoalim, provider hapoalim) and cards (e.g. Isracard, provider isracard):

financy accounts list                                  # bit, bank, and card balances together
financy transactions list --from 2026-09-01 --all      # this month, every source
financy providers list                                 # resolve any PROVIDER value to its name

3. Ask about it from Claude or ChatGPT

Through the MCP server the same data is available as tools: list_connections and get_status to find bit and check freshness, list_accounts and list_transactions (both take a connection argument, and list_transactions takes from/to) to read it, and list_providers to resolve provider ids.

• Claude Code, with the local server: claude mcp add financy -- npx financy mcp (see MCP server).

• Claude or ChatGPT, with no CLI: add the hosted Financy connector, https://mcp.open-finance.ai/mcp, as a custom connector and sign in with your Financy account.

Then ask in plain language. The assistant pulls bit, bank, and card transactions and combines them. Questions like "who hasn't paid yet" work by comparing this period's incoming bit transfers with earlier ones — give the assistant the list of who you expect to pay if you have one.

Prompts for business owners

Invoices (Invoice4U, Morning, SUMIT, iCount)

Connect your invoicing system to Financy and the CLI reads it next to your bank data: who owes you what, every invoice and receipt, your customers — and it can draft documents for you to approve. Supported systems are Invoice4U, Morning (formerly Green Invoice), SUMIT and iCount. Drafts work with Invoice4U and Morning; SUMIT and iCount are read-only for now. Invoicing needs a paid plan (Starter and above), and a free account gets exit 4 with the code UPGRADE_REQUIRED.

Connect your system in the Financy app, under Connections → Business systems; the CLI reads connections, it does not create them. Then:

financy integrations list                     # copy the integration ID (intg_…)
financy receivables                           # open and overdue totals, per customer
financy receivables --detailed --json         # …with each customer's open invoices
financy documents list <integrationId> --status open --from 2026-09-01
financy documents list <integrationId> --receivable-only --all --json
financy documents get <integrationId> <documentId>
financy customers list <integrationId> --search "סטודיו"

$ financy receivables
Receivables as of 2026-10-11
  ILS: ₪2,340.00 open, ₪2,340.00 overdue across 1 documents

CUSTOMER   OPEN       OVERDUE    DOCS  MAX DAYS LATE  CUSTOMER ID
סטודיו גל  ₪2,340.00  ₪2,340.00  1     10             icus_…

Tables show amounts in shekels; under --json every amount is an integer in minor units (…Minor, agorot for ILS) exactly as the API returns it, and record lists carry a freshness object saying how recent the synced data is. Record lists page with --limit, --cursor and --all; proposals list takes only --limit (max 50).

Card payouts (Isracard Business)

If the business clears cards with Isracard, connect Isracard Business in the Financy app (Pro and above). It is a clearing integration: no invoices, just the payouts Isracard makes to the business — expected (a future credit, not yet in the bank) and settled (already paid into the account ending in TO ACCOUNT, so already part of that account's balance and transactions; never add it on top).

financy integrations list                         # the clearing one has CATEGORY clearing
financy settlements list <integrationId> --status expected
financy settlements list <integrationId> --from 2026-10-01 --to 2026-10-31 --all --json

The table shows gross and net (after commission, VAT and fees) in shekels, latest payment date first; --json keeps every deduction in minor units.

Drafting a document

financy proposals create sends a draft request and creates a draft — nothing is issued. The document is created in your invoicing system (Invoice4U or Morning) only after you open the returned approval link and approve it in Financy:

cat > draft.json <<'JSON'
{
  "action": "create_tax_invoice",
  "items": [{
    "counterpartyId": "icus_…",
    "lines": [{ "description": "עיצוב לוגו", "quantity": 1, "unitPriceMinor": 234000 }],
    "pricesIncludeVat": true
  }]
}
JSON
financy proposals create <integrationId> --file draft.json
financy proposals get <proposalId>            # status: pending_approval → completed

action is one of create_tax_invoice, create_invoice_receipt, create_receipt, create_credit_note or create_customer. Each request carries an Idempotency-Key (a fresh UUID unless you pass --idempotency-key), so retrying with the same key returns the first draft instead of a second one. The CLI cannot approve or cancel a draft — that is always your step in Financy.

Integration errors keep the API's code (UPGRADE_REQUIRED, NOT_FOUND, VALIDATION_FAILED, PROPOSAL_INVALID, RATE_LIMITED, …) and exit by class: 4 plan or permission, 6 not found, 2 invalid request, 1 conflict or expired cursor, 7 rate-limited or unavailable. Under --json the error also carries retryable, userActionRequired and, where the API gives one, an action. INSUFFICIENT_SCOPE means the token predates the key's integration access: the CLI mints a fresh one and retries once, and if that is refused too, the key has no integration access: a key set to read-only ("מידע בלבד" in Financy → Settings → API access) cannot reach integrations or payments, so turn that off; otherwise check the plan is Starter or above and rotate the key there. The integrations API lives at https://api.open-finance.ai/integrations; override it with FINANCY_INTEGRATIONS_URL (it otherwise follows FINANCY_API_URL's host).

Agent skills

Skills ship inside this package, so they can never drift from the CLI version they drive. Install them into a project's .claude/skills/ directory:

financy skills list             # what's in the box
financy skills install --all    # install every skill here
financy skills install freshness-check --dir ~/work/analysis

Skills are plain SKILL.md files — read them under skills/ before you install them.

MCP server (for AI agents)

financy mcp runs a stdio Model Context Protocol server exposing the command surface 1:1 as verb_noun tools (list_connections, get_status, refresh_connections, …) with the same {data, …} envelopes. Add it to Claude Code:

claude mcp add financy -- npx financy mcp

Credentials resolve exactly as the CLI does (config file or FINANCY_* env vars); an unconfigured server returns a structured NOT_CONFIGURED error from every tool. refresh_connections costs 20 credits — its tool description tells agents to confirm with the user first.

The local server also serves the invoicing tools — list_integrations, get_integration, get_receivables, list_invoicing_documents, get_invoicing_document, list_invoicing_customers, get_invoicing_customer, list_clearing_settlements, list_proposals, get_proposal, and the draft tools draft_invoice, draft_invoice_receipt, draft_receipt and draft_credit_note. A draft tool only creates a draft: its description tells the agent to show the user the approval link, and nothing is issued until the user approves it in Financy. These tools are not in the importable TOOLS table, because hosts that import it (such as the hosted Financy connector) serve their own invoicing tools under the same names.

Updating

financy update

Detects how it was installed and does the right thing: a global install runs npm install -g financy@latest; under npx it reminds you that npx always runs the latest; as a project dependency it defers to your project's package manager.

Releasing

1. Update CHANGELOG.md (move items out of Unreleased into the new version).

2. npm version <patch|minor|major> — bumps package.json and creates a vX.Y.Z tag.

3. git push --follow-tags.

4. The Release workflow (.github/workflows/release.yml) runs on the tag: it re-runs lint/typecheck/test/build, verifies the tag matches package.json, and publishes to npm with --provenance (via the NPM_TOKEN secret and id-token trusted publishing). The published version shows its provenance attestation on npm.

Before tagging, run the manual staging smoke test (not part of CI) with a real paid-org credential:

npm run build
FINANCY_CLIENT_ID=… FINANCY_CLIENT_SECRET=… FINANCY_USER_ID=… \
FINANCY_AUTH_URL=… FINANCY_API_URL=… FINANCY_CHAT_URL=… FINANCY_AUDIENCE=… \
npm run smoke

License

Apache-2.0