Your Orla books from the terminal, and a stdio MCP bridge for clients that cannot speak HTTP.
Your Orla books from a terminal, and a stdio bridge for MCP clients that cannot speak HTTP.
npx orla-cli login
npx orla-cli tx list --from 2026-08-01
npx orla-cli export --from 2026-01-01 > books.csv
No dependencies, no build step, no native module to compile. Node 22 or newer.
The package is orla-cli and the command it installs is orla. They differ
because npm refused the bare name as too close to packages that already exist
(ora, ol, rlp, url), and renaming the command would have been the worse
half of that trade: npm i -g orla-cli still gives you orla tx list.
A thin client over the same MCP endpoint Claude connects to. Every command is a
tool call, so the CLI cannot do anything a personal connection cannot do, and
nothing here has its own idea of authorization. orla login walks the ordinary
OAuth code flow with S256 PKCE: the browser lands on Orla's own consent page,
where you tick the spaces this machine may reach.
It does not move money. A personal connection reads and records. Payments, transfers and card details belong to an agent connected for that purpose, with its own limits, set in the app under Agents. The tools that move money are not in the list this connection is given, and are refused at the endpoint if asked for by name.
| Command | What it does |
|---|---|
orla login [--api URL] | Connect this machine. Opens a browser. |
orla logout | Forget the stored session. |
orla whoami | Which connection this is and which spaces it reaches. |
orla spaces | The spaces in reach. |
orla use <space-id> | Remember one as the default. |
orla accounts | Accounts in the space. |
orla tx list | Transactions. --from --to --search --account --limit. |
orla tx add | Record one. --account --kind --amount --date [--payee --note]. |
orla export | The same rows as CSV on stdout. |
orla tools | Which tools this connection was given. |
orla mcp [--api URL] | stdio bridge (below). |
orla version | Which version this is. |
--space <id> on anything space-scoped, --json for machine-readable output.
With --json, every command answers with one envelope on stdout:
{ "ok": true, "data": ... }
{ "ok": false, "error": { "code": "cli.not_connected", "message": "not connected: run `orla login` first" } }
Read ok, then branch on error.code. Codes that begin cli. are the CLI's
own; any other code is Orla's, passed through unchanged, the same name the
REST API and the MCP endpoint use. The exit status says which kind of failure
it was, so a shell script can branch without parsing anything:
| Exit | Meaning |
|---|---|
| 0 | done |
| 1 | a failure none of the rows below describes |
| 2 | the command line: unknown command, missing flag |
| 3 | no session here, or one Orla no longer honours |
| 4 | a space-scoped command with no space to work in, or several |
| 5 | Orla could not be reached |
| 6 | Orla was reached and said no, or answered in a shape the CLI cannot read |
| 7 | signing in was abandoned or came back wrong |
The skill that teaches an agent all of this, including where paying stops, is
skills/orla/SKILL.md. It ships in the package and at
orla.finance/skill.md, and it is one of the
five skills the Claude Code plugin below installs. Into any other agent:
npx skills add cheetah-trade/orla-cli --skill orla # any agent the skills CLI knows
curl -fsSL https://orla.finance/skill.md # or just read it
For Claude Desktop there is a bundle, orla-<version>.mcpb, attached to
each release: double-click it to install. It runs the stdio bridge below, and
the bridge signs in by itself.
Environment variables the CLI reads:
| Variable | Effect |
|---|---|
ORLA_NO_BROWSER=1 | never launch a browser; the sign-in URL is printed on stderr instead |
ORLA_NO_KEYCHAIN=1 | keep the session in a 0600 file instead of the OS keychain (tests, CI, headless boxes) |
XDG_CONFIG_HOME | where that file lives (<dir>/orla/session.json) |
Orla's MCP server is remote and speaks Streamable HTTP, and it answers at two addresses:
https://app.orla.finance/api/mcp/personal your own books, and nothing that pays
https://app.orla.finance/api/mcp the same door plus the agent shape
A client that supports remote MCP needs nothing from this package. Point it at an address and it will find the consent page by itself. Claude Code, for example:
claude mcp add --transport http orla https://app.orla.finance/api/mcp/personal
The difference is not a label. At /mcp/personal every tool that moves money is
withheld from the list and refused if a model asks for one by name, so the
promise holds whatever the consent page was told. At /mcp the page offers both
shapes, and picking "connect an agent" mints a machine principal with a budget
of its own. Use the personal address unless you are deliberately connecting a
bot.
Clients that only support stdio servers can run this CLI as one. It relays JSON-RPC to the HTTP endpoint and holds the token, so the client needs no OAuth support of its own:
{
"mcpServers": {
"orla": { "command": "npx", "args": ["-y", "orla-cli", "mcp"] }
}
}
The bridge uses the session orla login stored and refreshes it. With no
session it signs in by itself, since a client that spawned it has no terminal
to type into: it opens the browser on the consent page, stays a well-formed
server meanwhile (initialize and ping answered, tools/list empty, a tool
call refused with cli.sign_in_in_progress), and tells the client
tools/list_changed when the person is done.
The server is listed in the official MCP registry as finance.orla/orla,
which is the name a client or a directory should resolve it by. The entry
carries both doors: the remote endpoint above and this package for stdio.
Setup for individual clients is written up at
orla.finance/en/mcp. That is the personal
connection, which reads your books and cannot pay. /en/ai-agents is a
different door, where an agent gets a budget and a card of its own.
This repository is also a plugin marketplace. Installing it brings five skills, four for keeping the books and one for the CLI itself, and the personal MCP connection they run on:
/plugin marketplace add cheetah-trade/orla-cli
/plugin install orla@orla
The first tool call opens the ordinary consent page in a browser, where you pick
the spaces this machine may reach. /mcp shows the connection and starts that
flow by hand.
| Skill | What it does |
|---|---|
orla-categorize | Sorts uncategorized rows into categories, in batches you confirm first. |
orla-month-close | Closes a month: spend, budgets that broke, what is unsorted, what the space is worth, what waits for a signature. Reads only. |
orla-settle-up | Balances and the settle-up plan in a shared space, and records shared expenses from your own account of a trip. |
orla-counterparty-check | What a business space knows about a counterparty or address before money goes out. |
orla | The CLI from a terminal: the exact commands, the JSON envelope and exit codes, and where paying stops. |
The plugin points at https://app.orla.finance/api/mcp/personal, which is the
door that holds no tool that moves money. The skills say so, and the address is
what makes it true rather than a promise: payments, transfers and card details
are withheld there and refused if asked for by name.
Two things the skills lean on, worth knowing before you read them. A connection approved without "show full details" receives payees and addresses masked, which limits how much of a bank import can be categorized from four characters. And the tool list stops at 200 rows per call, with the true count beside it, so a busy month is read month by month rather than in one gulp.
contracts/mcp-personal-tools.json is the committed shape of that door, and
test/skills.test.js checks every tool and argument the skills name against it.
The OS keychain: security on macOS, secret-tool on Linux. Where neither
exists it falls back to a 0600 file under your config directory and says so
on stderr, because a refresh token quietly landing on disk is not something to
discover later.
orla logout clears both.
npm install
npm run check # types
npm run build # dist/
The server this talks to is not in this repository. --api points the CLI at a
different deployment, and the session records which one minted it, so a token
from one environment is never replayed against another.
Contributions are welcome. See CONTRIBUTING.md.
MIT. See LICENSE.
FAQs
Your Orla books from the terminal, and a stdio MCP bridge for clients that cannot speak HTTP.
The npm package orla-cli receives a total of 72 weekly downloads. As such, orla-cli popularity was classified as not popular.
We found that orla-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.