Orla

orla

从终端管理你的 Orla 账簿，并为无法使用 HTTP 通信的 MCP 客户端提供 stdio 桥接。

npx orla-cli login
npx orla-cli tx list --from 2026-08-01
npx orla-cli export --from 2026-01-01 > books.csv

无依赖、无需构建，也没有需要编译的原生模块。需要 Node 22 或更高版本。

软件包名是 orla-cli，安装的命令是 orla。两者名称不同，是因为 npm 认为裸名称与现有软件包（ora、ol、rlp、url）过于接近而拒绝了它；重命名命令会得不偿失：执行 npm i -g orla-cli 后，仍然可以运行 orla tx list。

这是什么

一个轻量客户端，连接到 Claude 使用的同一个 MCP 端点。每条命令都是一次工具调用，因此 CLI 不能执行个人连接无法执行的操作，这里也没有单独的授权机制。orla login 会按照标准 OAuth 授权码流程使用 S256 PKCE：浏览器会打开 Orla 自己的授权页面，你可以在其中勾选此设备可以访问的空间。

它不会转移资金。 个人连接只会读取和记录。支付、转账和银行卡详细信息属于为此目的连接的 Agent，并由其独立限额控制，这些设置位于应用的 Agents 页面中。此连接获得的工具列表中不包含转移资金的工具，即使按名称请求，端点也会拒绝。

这并非依赖于对这个客户端的信任：orla login 请求的是个人地址，该地址上不存在这些工具，因此无论在授权页面上勾选什么，这项承诺都不会改变。orla login --agent 请求的是另一个地址，在那里可以创建拥有独立预算的机器人。会话会记住签发令牌的入口并继续使用，因此更新不会更改现有连接所使用的入口。

命令

命令	功能
orla login [--api URL] [--agent]	连接此设备。打开浏览器。--agent 会请求可创建机器人的入口。
orla logout	清除已保存的会话。
orla whoami	查看此连接的身份以及它可访问的空间。
orla spaces	查看可访问的空间。
orla use <space-id>	将某个空间设为默认空间。
orla accounts	查看该空间中的账户。
orla tx list	查看交易。--from --to --search --account --limit。
orla tx add	记录一笔交易。--account --kind --amount --date [--payee --note]。
orla export	以 CSV 格式将相同的行输出到 stdout。
orla tools	查看此连接获得的工具。
orla mcp [--api URL]	stdio 桥接（见下文）。
orla version	查看当前版本。

适用于所有按空间操作的命令的 --space <id>，以及用于输出机器可读内容的 --json。

面向程序或 Agent

使用 --json 时，每条命令都会在 stdout 上返回一个信封：

{ "ok": true, "data": ... }
{ "ok": false, "error": { "code": "cli.not_connected", "message": "not connected: run `orla login` first" } }

读取 ok，然后根据 error.code 进行分支。以 cli. 开头的代码属于 CLI 自身；其他代码均属于 Orla，会原样传递，且与 REST API 和 MCP 端点使用的名称相同。退出状态表示故障类型，因此 shell 脚本无需解析任何内容即可进行分支处理：

退出状态	含义
0	完成
1	下方各行未描述的故障
2	命令行问题：未知命令、缺少标志
3	当前没有会话，或 Orla 已不再认可该会话
4	需要指定空间的命令没有可用空间，或有多个可用空间
5	无法连接 Orla
6	已连接 Orla，但 Orla 拒绝了请求，或返回了 CLI 无法读取的格式
7	登录已中止或返回了错误结果

教会 Agent 所有这些内容（包括付费功能的边界）的技能位于 skills/orla/SKILL.md。它随软件包一同提供，也可在 orla.finance/skill.md 获取；它还是下方 Claude Code 插件安装的五个技能之一。要将其用于其他 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

Claude Desktop 提供了一个安装包 orla-<version>.mcpb，随每个版本附上：双击即可安装。它会运行下方的 stdio 桥接程序，并自行登录。

CLI 读取的环境变量：

变量	作用
ORLA_NO_BROWSER=1	从不启动浏览器；登录 URL 会打印到 stderr
ORLA_NO_KEYCHAIN=1	将会话保存在 0600 文件中，而不是操作系统钥匙串中（用于测试、CI、无头设备）
XDG_CONFIG_HOME	指定该文件的位置（<dir>/orla/session.json）

作为 MCP 服务

Orla 的 MCP 服务位于远程，使用 Streamable HTTP，并提供两个地址：

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

支持远程 MCP 的客户端无需使用此软件包。将其指向某个地址，它就会自行找到授权页面。例如，Claude Code：

claude mcp add --transport http orla https://app.orla.finance/api/mcp/personal

这不只是名称上的区别。在 /mcp/personal 上，所有转移资金的工具都会从列表中移除；即使模型按名称请求这些工具，也会被拒绝，因此无论授权页面上告知了什么，这项承诺都会得到保障。在 /mcp 上，页面会提供两种连接方式；选择“connect an agent”会创建一个拥有独立预算的机器主体。除非你有意连接机器人，否则请使用个人地址。

只支持 stdio 服务的客户端可以将此 CLI 作为 stdio 服务运行。它会将 JSON-RPC 中继到 HTTP 端点并持有令牌，因此客户端本身无需支持 OAuth：

{
  "mcpServers": {
    "orla": { "command": "npx", "args": ["-y", "orla-cli", "mcp"] }
  }
}

该桥接程序使用 orla login 保存的会话，刷新会话，并向创建该会话时使用的入口发送请求。没有会话时，它会自行登录，因为启动它的客户端没有可供输入的终端：它会在授权页面打开浏览器，同时保持为格式有效的服务（initialize 和 ping 会得到响应，tools/list 返回空列表，工具调用会被拒绝并返回 cli.sign_in_in_progress），并在用户完成操作后通知客户端 tools/list_changed。

该服务已列入官方 MCP 注册表，名称为 finance.orla/orla；客户端或目录应通过此名称解析它。该条目包含两个入口：上方的远程端点，以及用于 stdio 的此软件包。

各客户端的设置说明见 orla.finance/en/mcp。这是个人连接，可读取你的账目，但不能付款。/en/ai-agents 则是另一个入口，Agent 在那里会获得自己的预算和银行卡。

作为 Claude Code 插件

此仓库同时也是一个插件市场。安装后会带来五个技能，其中四个用于记账，一个用于 CLI 本身，以及它们所依赖的个人 MCP 连接：

/plugin marketplace add cheetah-trade/orla-cli
/plugin install orla@orla

首次调用工具时，会在浏览器中打开常规授权页面，你可以在其中选择这台设备可访问的空间。/mcp 会显示连接，并可手动启动此流程。

技能	功能
orla-categorize	将未分类的条目分到各个类别，并分批处理；每批都需先由你确认。
orla-month-close	结算一个月：支出、超支的预算、未分类的条目、空间的价值，以及待签署的事项。仅读取。
orla-settle-up	查看共享空间中的余额和结算计划，并从你自己的账户记录旅行的共享支出。
orla-counterparty-check	查看企业空间在款项转出前掌握的交易对手或地址信息。
orla	从终端使用的 CLI：准确的命令、JSON 封装和退出代码，以及付款功能止步之处。

该插件指向 https://app.orla.finance/api/mcp/personal，这是一个不包含任何可转移资金工具的入口。技能对此有明确说明，而这个地址让它成为事实，而非承诺：付款、转账和卡片详情在此处均不可用，若按名称请求也会遭到拒绝。

阅读这些技能前，值得了解它们依赖的两点。未勾选“显示完整详情”就批准的连接会对收款人和地址进行遮蔽，因此仅凭四个字符，能从银行导入记录中分类的信息有限。此外，每次工具调用最多返回 200 行，并同时提供实际总数，因此繁忙月份需要逐月读取，而不能一口气读完。

contracts/mcp-personal-tools.json 是此入口已提交的结构，test/skills.test.js 会检查技能中提到的每个工具和参数是否与之匹配。

令牌的存储位置

操作系统钥匙串：macOS 上使用 security，Linux 上使用 secret-tool。如果两者都不存在，则会回退到配置目录下权限为 0600 的文件，并在标准错误输出中说明这一点，因为刷新令牌悄悄落到磁盘上，不该等到日后才发现。

orla logout 会清除两者。

开发

npm install
npm run check   # types
npm run build   # dist/

此 CLI 所连接的服务不在此仓库中。--api 可将 CLI 指向其他部署，且会话会记录签发令牌的部署，因此一个环境的令牌绝不会被用于另一个环境。

欢迎贡献。请参阅 CONTRIBUTING.md。

评测

test/skills.test.js 会检查技能是否与 CLI 一致。但它无法检查技能存在的目的：阅读技能的 Agent 是否会因此停止猜测。这正是 evals/ 的用途。每个案例都会运行两次，一次使用此插件，一次不使用，以此体现技能本身带来的差异。

案例	检查内容
space-default	orla use 将空间 ID 作为位置参数，而不是 --space 标志
payment-approved	approved 表示某人已签署，而非款项已转出；只有 executed 才会附带参考编号
cli-cannot-pay	此处没有任何命令可以转移资金，回答会明确说明这一点，而不是凭空编造命令

claude plugin eval .                              # both arms, three runs per case
claude plugin eval . --case space-default --runs 1

运行期间 MCP 服务会保持关闭：在默认的 --mocks record 模式下，没有模拟数据的服务不会启动，因此这些案例不需要实际入口、OAuth 或账户。

最近一次运行的测量结果

2026-09-18，插件 0.2.1，Claude Code 2.1.270，每种情况在每组中运行三次， 未固定模型（使用 CLI 的默认模型和默认评判器）。整个测试套件耗时 294 秒，费用为 1.53 美元。

情况	使用技能	不使用技能	Δ
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

请如实看待这些结果。技能的主要价值体现在命令操作上： 不使用技能时，模型三次运行都把 orla use 用错了，因为它确实无法猜出 CLI 的参数格式。在资金相关问题上，基础模型大多数时候已经足够谨慎，而技能让“大多数时候”变成了每次都如此；当答案关乎某人是否已收到付款时，这一点至关重要。

关于基线组，有一点值得了解：不使用技能时，模型通常不会凭空编造命令，而是选择拒绝操作，并要求先查看 --help。这是更好的失败方式，但对于预期能够采取行动的 Agent 来说，这仍然是失败。

这些数字来自某一天的一次运行，并非基准测试。重新运行上面的命令，你会得到自己的结果。

许可证

MIT。请参阅 LICENSE。