orla
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.
What it is
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.
That is not a matter of trust in this client: orla login asks for the personal
address, where those tools do not exist, so the promise survives whatever gets
ticked on the consent page. orla login --agent asks for the other address, the
one where a bot with its own budget can be minted. A session remembers which
door issued its tokens and keeps using it, so an existing connection is not
re-pointed by an update.
Commands
| Command | What it does |
|---|
orla login [--api URL] [--agent] | Connect this machine. Opens a browser. --agent asks for the door where a bot can be minted. |
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.
For a program, or an agent
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) |
As an MCP server
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, refreshes it, and posts to the
door that session was minted at. 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.
As a Claude Code plugin
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.
Where the token lives
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.
Development
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.
Evals
test/skills.test.js checks that the skill agrees with the CLI. It cannot check
the thing the skill exists for: whether an agent reading it stops guessing. That
is what evals/ is for. Each case runs twice, once with this plugin and once
without it, so the difference is what the skill itself changed.
| Case | What it checks |
|---|
space-default | orla use takes the space id as a positional argument, and not as a --space flag |
payment-approved | approved means a person signed it, not that the money left; only executed carries a reference |
cli-cannot-pay | no command here moves money, and the answer says so instead of inventing one |
claude plugin eval . # both arms, three runs per case
claude plugin eval . --case space-default --runs 1
The MCP server stays down while they run: under the default --mocks record a
server with no mock is not started, so the cases need no live door, no OAuth and
no account.
What the last run measured
2026-09-18, plugin 0.2.1, Claude Code 2.1.270, three runs per case in each arm,
model not pinned (the CLI's default, and the default judge). Whole suite: 294
seconds, $1.53.
| Case | With the skill | Without it | Δ |
|---|
space-default | 1.00 | 0.33 | +0.67 |
cli-cannot-pay | 1.00 | 0.67 | +0.33 |
payment-approved | 1.00 | 0.83 | +0.17 |
Read it honestly. The skill earns most of its keep on the command surface:
without it the model got orla use wrong in three runs out of three, because
guessing a CLI's argument shape is exactly what it cannot do. On the money
questions the base model is already careful most of the time, and the skill
turns "most of the time" into every run, which is the part that matters when
the answer is whether somebody was paid.
Worth knowing about the baseline arm: without the skill the model usually did
not invent a command, it declined and asked to see --help first. That is the
better failure, and it is still a failure for an agent expected to act.
These numbers are one run on one day, not a benchmark. Re-run the command above
and you will get your own.
License
MIT. See LICENSE.
