Beancount 命令行参考

使用此参考来查找 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 和 Equity:OpeningBalances。

期初余额对冲 Equity:OpeningBalances。债务为负数。货币输入会大写化。允许自定义符号；不是三个大写字母的符号会触发拼写错误警告。这不是 ISO 货币注册表检查。

现有文件永远不会被覆盖。新文件使用仅所有者权限，POSIX 上模式为 0600。后续的 add、import 和 format 写操作保留权限并尊重只读目标。

添加交易​

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。

货币兑换需要其实际交易汇率。例如，将 100 EUR @ 1.08 USD 过账到以 EUR 开设的账户，将 -108 USD 过账到支票账户。投资买入可以将 2 AAPL {100 USD} 过账到以 AAPL 开设的账户，将 -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-date 可以选择另一个更早的日期。两个账户都必须处于活动状态。独立的垫付需要稍后的余额来消费它。--allow-errors 可以暂存该中间状态，但无法绕过无效的垫付账户。

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 相同的对齐，这可能会重新对齐该目标中的现有列。

列出指令​

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

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

检查、格式化和查询​

bea check 验证根及其包含。它退出代码 1 表示账本错误，没有 --allow-errors 选项。查询、列表和报表也拒绝加载器错误，除非你明确传递其 --allow-errors 选项。

格式化接受 .bean/.beancount 文件或目录。目录被递归搜索。

每种模式按文件和行报告语法错误，跳过这些文件，并退出代码 1。递归正常运行仍可格式化有效文件。JSON 在失败时报告 scanned、formatted、skipped、dry_run 和 check，在 error.result 下。

bea query "BQL" 运行 Beancount 查询。省略 BQL 打开交互式 shell；exit 或 quit 关闭它。非交互模式下查询参数必需。BQL 的默认表每行一个过账。查询表保留精度。空结果在 stderr 上打印 (no rows)；JSON 返回空 data.rows 和 data.columns 中的列元数据。

财务报表​

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

时间筛选包括年、月、日、季度、周或范围，如 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 还标识期间、独占结束日期、截止日期、转换、账户筛选和账本验证状态。在比较总数前检查这些字段。

可选 AI 辅助​

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 字段。完整指令按需加载。

托管账本​

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

JSON 和退出代码​

全局 --json 将成功结果放在 stdout 上：

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

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

失败在 stderr 上写入 {"error":{"category":"validation","message":"…","exit_code":1}}。错误还可以包括 details、result、后端 request_id 和带 --debug 的 traceback。

在重试变更前检查 error.result。部分批次可以写入接受的行，递归格式化可以更改有效文件，创建并克隆可以在退出非零前创建托管账本。

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

输出异常：Ask 拒绝 JSON；云登录需要交互；成功的云注销和克隆不返回 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 检查你安装的版本。源仓库参考包含额外示例和精确指令模型定义。