Beancount CLI 参考

用这份参考来查阅 bea 命令及其行为。如果你是第一次使用账本，请先阅读 CLI 快速上手。要端到端地完成一个完整月份的结账，请按 用 bea 度过你的第一个月 操作。处理银行文件时，请使用 导入操作指引。

命令一览​

全局选项和路径​

全局选项要放在命令之前：

bea --file ~/my-books/main.bean check
bea --json list transaction --limit 100

init 会创建自己的目录/文件目标并忽略 BEA_FILE。它接受全局 --file，而不接受目录参数。format 使用自己的位置目标。请提供文件名或目录。全局 --file 不会选择格式化目标。

创建账本​

bea init [DIRECTORY] 默认使用当前目录。传入目录会创建 main.bean；传入 .bean 或 .beancount 路径则会直接命名新文件。

模板会创建 Assets:Checking、Assets:Savings、Assets:Cash、Liabilities:CreditCard、Income:Salary、Income:Interest、Expenses:Groceries、Expenses:Dining、Expenses:Rent、Expenses:Transport、Expenses:Utilities、Expenses:Fees、Expenses:Uncategorized 和 Equity:OpeningBalances。

期初余额会与 Equity:OpeningBalances 对冲。债务为负数。输入的货币会自动转为大写。允许自定义符号；如果某个符号不是三个大写字母，会触发拼写错误警告。这并不是 ISO 货币注册表校验。

现有文件绝不会被覆盖。新文件使用仅所有者权限，在 POSIX 上为 0600 模式。后续的添加和导入写入会保留权限，并尊重只读目标。原地格式化使用原生格式化器，并报告其自身的文件系统错误。

添加交易​

bea add transaction -n "Groceries" --payee "Corner Market" \
  -p "Expenses:Groceries 30" -p "Assets:Checking" \
  --flag '!' --tag household --link receipt-42 --meta 'receipt:IMG_42.jpg'

一条分录可以省略其金额。编号分录在账户只有一个允许货币，或账本只有一个兼容的本位币时，可以省略货币。否则请提供货币符号。

原生分录语法支持诸如 84/2 EUR 的算术、诸如 {100 USD} 的成本、总成本 {{1000 USD}}，以及价格 @ 或 @@。请使用 1000 这样的十进制金额，而不是 1e3 这样的指数记法。

货币兑换需要其实际交易汇率。例如，向一个以 EUR 开立的账户分录 100 EUR @ 1.08 USD，并向支票账户分录 -108 USD。投资购买可以向一个以 AAPL 开立的账户分录 2 AAPL {100 USD}，并向支票账户分录 -200 USD。当报表需要市场估值时，请添加带日期的 price 报价。

元数据接受诸如 --meta 'receipt:IMG_42.jpg' 的裸字符串。原生数字、布尔值、日期和金额会保留其类型。示例包括 --meta 'reviewed:TRUE'、--meta 'received:2026-08-03' 和 --meta 'fee:2.50 USD'。内部引号会强制为字符串：--meta 'code:"1234"'。键必须各不相同；filename 和 lineno 是保留键。

单条添加、批量添加和导入会将交易对方、摘要和字符串元数据中的换行替换为空格。引号和反斜杠会保留其内容。

添加其他指令​

所有这些命令都要求 --date YYYY-MM-DD。它们也接受 --into FILE 和 --allow-errors。

账户名称有一个大写的根，以及以冒号分隔的层级。每个子账户以大写字母或数字开头。Beancount 支持 Unicode 字母和配置的根名称。

余额检查该账户在其日期开始时的状态。支持容差语法，例如 --amount "1538 ~ 1 EUR"。容差必须非负。

使用 add balance --pad-from Equity:OpeningBalances 可以同时写入一个 pad 及其余额断言。pad 默认是前一天；--pad-date 可以选择另一个更早的日期。两个账户都必须处于活跃状态。单独的 pad 需要后续的余额来消耗它。--allow-errors 可以暂存这种中间状态，但不能绕过无效的 pad 账户。

add price 会在根账本及其包含文件中跳过完全相同的日期/商品/价格重复项。它会以 0 退出并指出已有位置。不同的日期或价格则是新增项。

文档路径会在包含该指令的文件旁边解析。使用 --into years/2026.bean 时，--filename receipt.pdf 表示 years/receipt.pdf，而不是你 shell 工作目录旁边的文件。

自定义值的种类有 text、number、amount、account、bool 和 date。例如，预算可以使用 --value "text:travel" --value "amount:500 USD"。

批量 JSON 输入​

bea add transactions --from transactions.json 接受一个 JSON 数组：

[
  {
    "date": "2026-08-04",
    "narration": "Groceries",
    "postings": [
      { "account": "Expenses:Groceries", "amount": "45.00 USD" },
      { "account": "Assets:Checking" }
    ],
    "meta": { "receipt": "R-43", "reviewed": true }
  }
]

每笔交易都要求 date 和 postings。可选字段有 flag、payee、narration、tags、links 和 meta。

一条分录使用 amount 或 units，例如 {"number":"45.00","currency":"USD"}。平衡分录则两者都省略。分录字段还包括 cost、price、flag 和 meta。成本包含 number 和 currency，以及可选的 date 和 label。价格包含 number 和 currency。

小数请使用字符串。元数据使用普通字符串和布尔值，或带标签的值，例如 {"kind":"number","value":"1.125"}、{"kind":"date","value":"2026-08-04"} 和 {"kind":"amount","number":"2.50","currency":"USD"}。可选的交易 source 位置绝不会写入为元数据。

默认是原子批处理：任何被拒绝的行都会让账本保持不变，并以 1 退出。--partial 会写入有效子集，但只要有任何行被拒绝，仍以 1 退出。JSON 错误会在 error.result 中描述结果；其中的行索引从零开始。人类可读的行号从一开始。

批量添加接受 --into 和 --allow-errors。它不会去重。银行导出复核请使用 bea import。

拆分分类账和写入安全​

让 --file 始终指向根账本。添加 --into 来选择已有的被包含文件：

bea --file ~/my-books/main.bean add transaction --into 2026.bean \
  --date 2026-08-02 -n "Groceries" \
  -p "Expenses:Groceries 30" -p "Assets:Checking"

目标路径相对于根目录。它必须已经被包含；指定一个不相关的文件会被拒绝。添加命令、导入和交互式 AI 写入都支持这种分离。

写入会校验完整的候选账本，包括插件和成本批次簿记。对根账本或其包含图的并发更改会以 4 退出。只读目标会以 3 退出。成功添加只会对齐新行。现有字节保持不变。当你想重新对齐整个文件时，请使用 bea format -i PATH。

列出指令​

bea list TYPE 支持十一种类型：transaction、open、close、balance、pad、note、event、price、commodity、document 和 custom。

其他指令类型保持时间顺序。按账户筛选的交易表会将其金额列标记为 MATCHING POSTING AMOUNTS。详情和 JSON 仍会包含每笔所选交易的所有分录。详情渲染的是已加载的条目，包括推断出的金额；它们不是原始源片段。

检查、格式化与查询​

bea check 会校验根账本及其包含文件。成功时静默以 0 退出，账本错误时以 1 退出。全局 --json 会返回校验信封。check 没有 --allow-errors 选项。

在交互式终端中，查询、列表和报表会发出警告并返回部分结果。全局 --strict、--json、--no-input、真值 CI，或非终端 stdin 会让读取变为严格模式。它们的 --allow-errors 选项明确允许部分结果。

格式化接受文件，或递归搜索一个目录。在已发布的 0.2.0 包中，尽管帮助中显示默认为 stdin，路径仍是必需的。全局 --file 不会选择格式化目标。

格式化只对齐文本；它不会校验账本语法或会计。请单独运行 bea check。使用全局 --json 时，请选择 -i、-o FILE、--check 或 --dry-run，以便 stdout 承载信封。不要用 stdout 重定向覆盖输入文件：请使用 -i 重写它。

bea query "BQL" 运行 Beancount 查询。省略 BQL 时会从 stdin 读取查询，或在 stdin 为终端时打开 shell。使用 .exit、exit 或 quit 关闭 shell。BQL 的默认表每条分录一行。查询表保留精度。

请在命令之前选择账本，例如 bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account"。全局 --json 使用带 data.rows 和 data.columns 的产品信封；它与 CSV 渲染不同。在已发布的 0.2.0 版本中，请使用 shell 重定向来保存 JSON，例如 bea --json query "SELECT account, sum(position) GROUP BY account" > result.json：在该版本中，查询的 -o 和 -m 不适用于 JSON。

本机工具和可选功能​

bea doctor context main.bean 42 显示第 42 行处的交易上下文。bea doctor --help 列出其他诊断命令。bea example -o example.bean 创建一份示例历史。bea treeify accounts.txt 从文本文件渲染层级名称；省略文件则读取 stdin。这些命令会转发原生参数。以上示例明确写明了这些参数。

使用 bea engine enable beanprice 启用报价获取，或使用 bea engine enable beangulp 启用导入器工作流，即可一次性启用可选工具。启用需要网络访问；Beangulp 还需要系统 libmagic 库。使用 bea engine status 检查可用性。bea price --help 和 bea ingest --help 描述了它们的接口。bea import --csv 和 bea add price 不需要这两个可选功能中的任何一个。

托管价格包含​

实时价格 是一种单独的托管包含工作流。托管账本会解析支持的报价 URL；兼容的 bea 版本也支持托管包含和本地价格导出。如果你安装的版本无法识别这些命令，请查看特定版本的托管价格指南。

CLI 会在不发送凭据的情况下解析允许列表中的托管 URL，并拒绝重定向。因此，重定向到托管登录页的数据源无法被全新的本地获取使用；登录网站并不会让 CLI 价格请求通过认证。请检查 price status 中的来源错误。请在适当情况下使用缓存数据、可访问的支持数据源，或本地带日期价格。

price export 会将数据源文件写入 prices/ 下，并将包含重写为本地相对路径。上游 Beancount、Fava 和 Beanquery 可以加载该导出副本。不可用的来源会拒绝导出，除非使用 --allow-errors，这可能让其来源标记没有价格。

你自己的带日期价格会覆盖同一日期和货币对的托管价格。数据源条目是只读的。失败的刷新会保留先前已验证的修订，而该修订可能已过期。bea price 的其他参数仍会转发给 Beanprice；如果某个报价任务文件名为 status，请传入 ./status 以区别于该子命令。

Homebrew 会同时安装 CLI 及其托管引擎。使用 PyPI 时，第一个由引擎支持的命令会下载固定版本的依赖；请将 uv 保留在 PATH 中，并允许该首次运行访问网络。之后的本地命令会离线复用该引擎。客户只需安装 beancount-io，无需管理单独的 Beancount 包或原生控制台脚本。

财务报告​

所有报表都接受 --conversion / -x、--time / -t、--account / -a 和 --allow-errors。除试算表外，其他所有报表还接受 --interval / -i：默认 monthly，或 quarterly、yearly、weekly 或 daily。

bea balance [ACCOUNT...] 会打印匹配不区分大小写子串的账户余额子树；如果你不指定任何账户，则打印整个账本。它接受 --conversion / -x、--time / -t 和 --allow-errors，不接受区间或账户选项。

时间筛选包括年、月、日期、季度、周或范围，例如 2026、2026-08、2026-08-31、2026-Q3、2026-W32 或 "2026-01 - 2026-08"。相对期间包括 year、quarter、month、week、day，以及诸如 month-1 的偏移。账户筛选会保留匹配交易的所有分录。

转换默认使用账本唯一的本位币。否则默认使用 units，将各商品分开保留。at_cost 使用取得成本。at_value 使用市场价值，并在缺失时回退到成本。

显式货币转换需要在每个估值日期（包括区间日期）当天或之前有价格。缺少价格的错误会指出实际缺口，例如 No EUR → USD price on or before 2026-01-31。较晚的报价无法填补较早的缺口。请添加历史适当的价格，使用 --conversion units，或选择 --allow-errors 来检查部分数值。

部分报表会保留来源货币，并将合并总计标记为不可用。JSON 会包含 valuation: "partial"、missing_prices 和 missing_price_dates。受影响的净利润/净资产总计在请求的货币中为 null。

收入、负债和权益通常使用 Beancount 的负号表示。净利润为 -(income + expenses)，盈利时为正。损益表期间行也适用相同约定。资产负债表对账是为报表派生的；它不会写入任何指令。equity_reconciled 表明是否有完整的对账可用。

报表 JSON 还会标明期间、排他结束日期、截至日期、转换、账户筛选，以及账本校验状态。在比较总计之前请检查这些字段。

可选的人工智能辅助​

bea ask 既需要 ask 附加组件，也需要来自 bea cloud login 或 BEA_TOKEN 的 Beancount.io 凭据。默认的 Homebrew 安装不包含 AI 依赖。Homebrew 用户可以运行：

bea cloud login
uvx --from 'beancount-io[ask]' bea ask "What did I spend last month?" --print

对于 uv 安装，请安装 beancount-io[ask] 并直接运行 bea ask。--print / -p 回答一次并退出。否则，终端会话是交互式的，可选的问题会预填其输入。非交互式使用必须提供问题。不支持 JSON 模式。

查询在本地运行。问题、技能上下文和工具结果会发送到托管的 Beancount.io AI 服务。交互式写入会先预览、确认、校验，然后原子地写入。它们接受 --into。全局 --yes 不会授予 AI 写入权限。单次回答模式不会应用提议的写入。

Ask 会从工作目录下的 .agents/skills/ 中，以及用户配置目录下的 skills/ 中读取 NAME/SKILL.md。项目定义按名称优先。每个文件都需要 YAML 的 name 和 description 字段。完整说明会按需加载。有关文件布局和完整示例，请参阅用技能扩展 bea ask。

托管账本​

使用全局 --json 时，bea cloud status、bea cloud ledger list、bea cloud ledger show、bea cloud ledger create 和 bea cloud ledger delete 会输出标准信封。登录需要交互；成功注销和克隆不会返回 JSON 成功对象。

创建还接受 --clone 和 --dir。克隆需要 Git 和 SSH 访问。如果创建后克隆失败，托管账本仍然存在。本地命令不会自动上传你的账本。没有全局 --ledger 选项。

JSON 和退出代码​

全局 --json 会把成功结果放到 stdout：

{
  "bea": "0.2.0",
  "target": { "file": "/home/alice/my-books/main.bean" },
  "data": [],
  "truncated": false,
  "limit": 50
}

bea 是已安装的版本；data 取决于命令。目标会标识一个文件、目录、服务器，或没有目标。被包含的写入还会标识 into。十进制金额和日期使用字符串。有限列表会包含 limit 和 truncated。

失败会把 {"error":{"category":"validation","message":"…","exit_code":1}} 写入 stderr。错误还可以包含 details、result、后端 request_id，以及在使用 --debug 时的 traceback。

在重试变更之前请检查 error.result。部分批次可能写入已接受的行，递归格式化可能更改有效文件，创建并克隆可能先创建托管账本再以非零退出。有关用 jq 读取此信封并根据这些代码分支的脚本，请参阅用 bea 自动化簿记。

CLI 提示会被 --no-input、JSON 模式、非终端 stdin 或真值 CI 禁用。云删除仍需要显式 --yes。当匹配项需要复核时，导入需要明确的重复处理决定。

输出例外：doctor、example、treeify、转发给 Beanprice 的 price 调用，以及 ingest 会保留原生输出和退出状态，即使使用全局 --json 也一样；上面的信封和退出类别并不描述这些转发结果。Ask 拒绝 JSON；cloud login 需要交互；成功的 cloud logout 和 clone 不返回 JSON 成功对象。帮助、版本和补全会保留文本输出。upgrade 可以将其包管理器的输出流式写入 stderr，在 JSON 模式下也是如此。

设置、更新和存储状态​

真值为 1、true、yes 和 on，忽略大小写和周围空白。配置状态包括凭据、Ask 提示历史、用户技能、已记住的导入器路径，以及更新检查缓存。写入锁位于缓存目录的 locks/ 下，在你的账本目录之外。

bea upgrade --check 会报告版本和安装方式，而不进行升级。bea upgrade 会调用 brew upgrade bea、uv tool upgrade beancount-io 或 pipx upgrade beancount-io。可编辑安装会收到手动更新指引。在已安装的交互式副本中，被动检查每天最多运行一次；即使被动通知器被禁用，显式的 upgrade --check 仍会运行。

请使用匹配的管理器卸载：brew uninstall bea、uv tool uninstall beancount-io 或 pipx uninstall beancount-io。你的账本文件和用户配置会保留。

常见修复​

使用 bea COMMAND --help 检查你安装的版本。源码仓库参考 包含更多示例和精确的指令模型定义。