Fava 1.30.16 常用 CLI 命令与工具详解

目标：系统梳理 Beancount/Fava 工具链的全部命令行工具——fava 服务本体、bean-check 校验、bean-query 查询（BQL）、bean-format 格式化、bean-doctor 诊断、bean-example 示例生成——每个工具给出参数表与真实回显，并把 Beancount v3 相对 v2 的命令变化（bean-report 移除、BQL 语法收紧）沉淀为可照做的排障指引。全部命令与输出已在 Ubuntu 22.04 + Fava 1.30.16 + Beancount 3.2.3 环境实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS，Python 3.10.12
组件版本：fava 1.30.16、beancount 3.2.3、beanquery 0.2.0、beangulp 0.2.0
安装方式：venv（/opt/fava/venv/bin/，命令速查同 pipx 场景）
测试账本：/opt/ledger/example.beancount（个人复式记账示例账本，CNY 单币种，含 7 个账户、6 笔交易、1 条 pad + balance 断言）
工具定位：命令行工具处理账本数据，Fava 只负责 Web 展示——两者共用同一账本文件与同一查询引擎

二、工具概览

命令	来源包	职责	典型场景
`fava`	fava	启动 Web 界面服务	日常浏览、录入、导入
`bean-check`	beancount	全账本语法+复式平衡校验	保存后/提交 git 前/CI 中
`bean-query`	beanquery	BQL 查询账本（交互式或单次）	提取报表、对账、导出 CSV
`bean-format`	beancount	对齐美化账本文件（纯文本处理）	编辑后统一格式
`bean-doctor`	beancount	11 个诊断子命令	排障、看解析细节
`bean-example`	beancount	生成大型示例账本	学习、性能压测数据源
~~`bean-report`~~	—（v3 已移除）	v2 时代报表工具	用 bean-query 替代

💡 说明：pipx 安装时三个包的命令暴露关系——pipx install fava 只暴露 fava；pipx install beancount 暴露 bean-check/bean-doctor/bean-example/bean-format/treeify；pipx install beanquery 暴露 bean-query。venv 安装则一次全齐（实测 /opt/fava/venv/bin/ 下 bean-check bean-doctor bean-example bean-format bean-query fava 全部存在）。

三、前置条件

确认命令可用（venv 场景先 export PATH，或直接用绝对路径）：

export PATH=/opt/fava/venv/bin:$PATH
fava --version
bean-check --version
bean-query --version
bean-format --version
bean-doctor --version

实测输出：

fava, version 1.30.16
Beancount 3.2.3
beanquery 0.2.0, beancount 3.2.3
Beancount 3.2.3
Beancount 3.2.3

⚠️ 注意：bean-report --version 实测返回 bash: bean-report: command not found——Beancount 3 移除了 bean-report（连同 bean-web、bean-price 等旧工具的重组）。网上 v2 时代教程里的 bean-report 用法在 3.x 全部改走 bean-query。

四、各工具详解

4.1 fava —— Web 服务启动

fava --help 实测完整输出（参数默认值以此为准）：

Usage: fava [OPTIONS] [FILENAMES]...

  Start Fava for FILENAMES on http://<host>:<port>.

  If the `BEANCOUNT_FILE` environment variable is set, Fava will use the files
  (delimited by ';' on Windows and ':' on POSIX) given there in addition to
  FILENAMES.

  Note you can also specify command-line options via environment variables
  with the `FAVA_` prefix. For example, `--host=0.0.0.0` is equivalent to
  setting the environment variable `FAVA_HOST=0.0.0.0`.

Options:
  -p, --port <port>   The port to listen on.  [default: 5000]
  -H, --host <host>   The host to listen on.  [default: localhost]
  --prefix TEXT       Set an URL prefix.
  --incognito         Run in incognito mode and obscure all numbers.
  --read-only         Run in read-only mode, disable any change through Fava.
  -d, --debug         Turn on debugging.
  --profile           Turn on profiling. Implies --debug.
  --profile-dir PATH  Output directory for profiling data.
  --poll-watcher      Use old polling-based watcher.
  --version           Show the version and exit.
  --help              Show this message and exit.

常用启动形态实测：

# 标准启动（远程可访问）：监听地址必须显式 0.0.0.0
fava -H 0.0.0.0 -p 5000 /opt/ledger/example.beancount

实测启动日志：

Starting Fava on http://0.0.0.0:5000

# 多账本：一个实例挂多本账，页面右上角切换
fava -H 0.0.0.0 -p 5000 /opt/ledger/family.beancount /opt/ledger/company.beancount
# 等价环境变量形态（POSIX 用冒号分隔）
BEANCOUNT_FILE=/opt/ledger/example.beancount fava -H 0.0.0.0 -p 5004

第二个形态实测：服务正常启动（日志 Starting Fava on http://0.0.0.0:5004）且 curl 根路径返回 302 到账本首页——BEANCOUNT_FILE 与命令行文件参数等价。其余参数（--prefix/--incognito/--read-only）的逐项实测见配置参数详解篇 5.3 节。

4.2 bean-check —— 账本校验

bean-check --help 实测输出：

Usage: bean-check [OPTIONS] FILENAME

  Parse, check and realize a beancount ledger.

  This also measures the time it takes to run all these steps.

Options:
  -v, --verbose          Print timings.
  -C, --no-cache         Disable the cache.
  --cache-filename PATH  Override the cache filename.
  -a, --auto             Implicitly enable auto-plugins.
  --json                 Output errors as JSON.
  --version              Show the version and exit.
  --help                 Show this message and exit.

校验通过形态（无输出即成功）：

bean-check /opt/ledger/example.beancount
echo "bean-check exit=$?"

实测输出：

bean-check exit=0

校验失败形态（复式不平衡示例）：构造一笔借贷差 1 元的账本后实测：

/tmp/broken.beancount:4: Transaction does not balance: (199.00 CNY)

   2026-03-01 * "不平衡交易"
     Expenses:Test  100.00 CNY
     Assets:Test     99.00 CNY

exit=1，报错格式为 文件:行号: 错误说明 并附出错条目原文。--json 输出机器可读错误（CI 集成用），实测：

{"errors": [{"message": "Transaction does not balance: (199.00 CNY)", "filename": "/tmp/broken.beancount", "lineno": 4}]}

-v 性能计时，实测节选（首尾）：

INFO    : Operation: 'beancount.parser.parser.parse_file'             Time:                  1 ms
INFO    : Operation: 'booking'                                        Time:                  1 ms
INFO    : Operation: 'beancount.ops.balance'                          Time:                  0 ms
INFO    : Operation: 'run_transformations'                            Time:            1 ms

💡 说明：beancount 有解析缓存，重复校验大账本很快；账本文件变化时缓存自动失效。怀疑缓存导致"改了没生效"时用 -C 禁用缓存复测。

4.3 bean-query —— BQL 查询

bean-query --help 实测输出：

Usage: bean-query [OPTIONS] FILENAME [QUERY]...

  An interactive interpreter for the Beancount Query Language.

  Load Beancount ledger FILENAME and run Beancount Query Language QUERY on it,
  if specified, or drop into the interactive shell. If not explicitly set with
  the dedicated option, the output format is inferred from the output file
  name, if specified.

Options:
  -o, --output FILENAME           Output filename.
  -f, --format [beancount|csv|text]
                                  Output format.
  -m, --numberify                 Numberify the output, removing the
                                  currencies.
  -q, --no-errors                 Do not report ledger validation errors on
                                  load.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

单次查询（推荐日常用法，查询语句作参数）：

bean-query /opt/ledger/example.beancount "SELECT date, narration, position WHERE account ~ \"Expenses\""

实测输出：

   date     narra    position
----------  -----  ------------
2026-01-12  周末采购     386.50 CNY
2026-01-15  通勤充值     100.00 CNY
2026-02-01  2 月房租   3500.00 CNY
2026-02-05  同事聚餐     158.00 CNY

按账户聚合：

bean-query /opt/ledger/example.beancount "SELECT account, sum(position) WHERE account ~ \"Expenses\" ORDER BY account"

实测输出：

     account        sum(position
------------------  ------------
Expenses:Food         544.50 CNY
Expenses:Rent        3500.00 CNY
Expenses:Transport    100.00 CNY

资产余额（正则锚定资产根账户）：

bean-query /opt/ledger/example.beancount "SELECT account, sum(position) WHERE account ~ \"^Assets\""

实测输出：

    account       sum(position)
----------------  -------------
Assets:Bank:Card   15513.50 CNY
Assets:Cash          342.00 CNY

CSV 导出（-f csv，可直接进表格软件）：

bean-query -f csv /opt/ledger/example.beancount "SELECT date, narration, account, position WHERE account ~ \"Expenses\""

实测输出：

date,narration,account,position
2026-01-12,周末采购,Expenses:Food,  386.50 CNY
2026-01-15,通勤充值,Expenses:Transport,  100.00 CNY
2026-02-01,2 月房租,Expenses:Rent, 3500.00 CNY
2026-02-05,同事聚餐,Expenses:Food,  158.00 CNY

-o 报表.csv 等价于 -f csv + 输出文件；-m 去掉币种只留数字（进计算器/表格时用）。

⚠️ 排障实录（v2 → v3 语法差异，实测踩坑）：

① Beancount v2 的余额速查语法 BALANCES AT 2026-02-05 在 beanquery（1.30 起的查询引擎）下实测报 beanquery.parser.ParseError: syntax error——该速查已移除，改用 SELECT account, sum(position) WHERE account ~ "^Assets" 形态。

② CLOSE ON 修饰符同样实测 ParseError: syntax error，v3 下过滤截止日期直接在 WHERE 里写 date <= 2026-02-05。

③ GROUP BY balance 实测报 CompilationError: GROUP-BY a non-hashable type is not supported: "Column(name='balance')"——balance 列不可聚合，按账户聚合统一用 sum(position)。

4.4 bean-format —— 账本格式化

bean-format --help 实测输出：

Usage: bean-format [OPTIONS] [FILENAMES]...

  Automatically format a Beancount ledger.

  This reformats a beancount or ledger input file so that the amounts in the
  postings are all aligned to the same column.

  If the alignment is not specified with the --currency-column option, it is
  determined automatically from the maximum length of the account names and of
  the numerical part of the transaction amounts in the input file. The
  automatically determined widths can be overridden with the --prefix-width
  and --num-width options respectively.

  Note: this tool does not parse the Beancount ledger. It simply uses regular
  expressions and text manipulations to do its work.

Options:
  -o, --output FILENAME          Output file.
  -w, --prefix-width INTEGER     Force fixed prefix width.
  -W, --num-width INTEGER        Force fixed numbers width.
  -c, --currency-column INTEGER  Align currencies to this column.
  -i, --in-place                 Edit files in place.

对齐效果实测（前 → 后）：

2026-03-01 * "格式测试" "演示"
  Expenses:Food  1234.5 CNY
  Assets:Bank:Card  -1234.50 CNY

2026-03-01 * "格式测试" "演示"
  Expenses:Food       1234.5 CNY
  Assets:Bank:Card  -1234.50 CNY

常用形态：bean-format -i /opt/ledger/example.beancount 就地格式化（git 管理下建议提交前统一跑一次，diff 干净）。注意它不解析账本（正则文本处理），校验仍要靠 bean-check。

4.5 bean-doctor —— 诊断工具箱

bean-doctor --help 实测输出：

Usage: bean-doctor [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  context          Describe transaction context.
  directories      Validate a directory hierarchy against the ledger's...
  display-context  Print the precision inferred from the parsed numbers...
  lex              Dump the lexer output for a Beancount syntax file.
  linked           List related transactions.
  list-options     List available options.
  missing-open     Print Open directives missing in FILENAME.
  parse            Parse a ledger in debug mode.
  print-options    List options parsed from a ledger.
  region           Print out a list of transactions within REGION and...
  roundtrip        Round-trip test on arbitrary ledger.

高频子命令实测：

list-options——列出全部 29 个 Beancount option 及官方释义（实测首尾节选）：

option "title" "Joe Smith's Personal Ledger"
  The title of this ledger / input file. This shows up at the top of
  every page.

option "name_assets" "Assets"
option "name_liabilities" "Liabilities"
option "name_equity" "Equity"
option "name_income" "Income"
option "name_expenses" "Expenses"
  ...

print-options——输出某账本解析后的实际选项值：

bean-doctor print-options /opt/ledger/example.beancount | head -6

实测输出：

account_current_conversions: Conversions:Current
account_current_earnings: Earnings:Current
account_previous_balances: Opening-Balances
account_previous_conversions: Conversions:Previous
account_previous_earnings: Earnings:Previous
account_rounding: None

missing-open——找出漏写 open 声明的账户（账本演进期最常见错误）：

bean-doctor missing-open /tmp/noopen.beancount

实测输出：

2026-03-01 open Expenses:Ghost

直接给出应补写的 open 指令原文，复制进账本即可。

display-context——显示从账本推断的数字精度（余额断言容差排查用）：

CNY             : sign=1   integer_max=5   fractional_common=2   fractional_max=2   "-00000.00" "-00000.00"
__default__     : sign=1   integer_max=1   fractional_common=_   fractional_max=_   "-0.*" "-0.*"

lex——词法分析器输出（语法报错定位到 token 级别时用），实测节选：

DATE              1 b'2026-01-12'
ASTERISK          1 b'*'
STRING            1 b'"\xe8\xb6\x85\xe5\xb8\x82"'
ACCOUNT           2 b'Expenses:Food'
NUMBER            2 b'386.50'

4.6 bean-example —— 示例账本生成

bean-example --help 实测输出（节选）：

Usage: bean-example [OPTIONS]

  Generate a decently-sized example history, based on some rules.

Options:
  --date-begin DATE      Beginning date.
  --date-end DATE        End date.
  --date-birth DATE      Fictional date of birth.
  -s, --seed INTEGER     Random seed.
  --no-reformat          Do not reformat the output.
  -o, --output FILENAME  Output filename.
  -v, --verbose BOOLEAN  Produce logging output.

生成一个季度数据实测：

bean-example --date-begin 2025-01-01 --date-end 2025-03-31 -o /opt/ledger/big-example.beancount
wc -l /opt/ledger/big-example.beancount
bean-check /opt/ledger/big-example.beancount && echo "BIG-CHECK-OK"
head -8 /opt/ledger/big-example.beancount

实测输出：

762 /opt/ledger/big-example.beancount
BIG-CHECK-OK
;; -*- mode: org; mode: beancount; -*-
;; Birth: 1980-05-12
;; Dates: 2025-01-01 - 2025-03-31
;; THIS FILE HAS BEEN AUTO-GENERATED.
* Options

option "title" "Example Beancount file"
option "operating_currency" "USD"

三个月生成 762 行且直接通过 bean-check——扩大 --date-end 区间即可得到训练 Fava 报表/测试 BQL 性能的成规模数据。-s 固定随机种子可复现同一份账本。

五、注意事项

命令行工具与 Fava 独立运行：bean-check/bean-query 不需要 Fava 进程在跑；Fava 重载账本时也不会调用它们（引擎内置）。CI 流水线只装 beancount 即可校验。
~ 与相对路径：工具链一律以当前 shell 的工作目录解析相对路径，systemd/cron 场景写绝对路径（本文所有示例均为绝对路径）。
中文账本：账本内容 UTF-8 编码即可（本例收款方/描述全中文实测通过）；终端显示对不齐是 CJK 字符宽度问题，不影响数据与 Fava 网页展示。
版本对照：--version 三种输出（fava/Beancount/beanquery）在提 issue 与排障时一并提供，能省一轮追问。

六、常见问题（FAQ）

Q1：bean-report 找不到了？ Beancount 3 移除。报表需求两路替代：命令行 bean-query（本文 4.3 节），或 Fava 网页的三大报表与 Query 页。

Q2：BALANCES AT 这类 v2 资料里的查询都报 syntax error？ 查询引擎自 1.30 起换为 beanquery 包，速查语法与部分列有差异。以 SELECT account, sum(position) 形态重写（本文 4.3 排障实录有三种典型报错与替代写法）。

Q3：校验说交易不平衡，但两边金额明明相等？ 常见原因：币种不同（100.00 CNY ≠ 100.00 USD）、精度不一致（引擎按账本推断的容差处理，bean-doctor display-context 查看推断精度）、或账户大小写/层级拼写不同导致一边解析为非账户名。

Q4：bean-format 跑完 bean-check 反而报错了？ bean-format 是纯文本对齐不解析语法，若账本本身有语法错误，它可能按自己的规则重排产生意外结果。先 bean-check 修干净账本，再格式化。

Q5：pipx 装完 fava 后敲 bean-check 提示找不到命令？ pipx 只暴露主 app。补装：pipx install beancount（暴露 bean-check/doctor/format/example）与 pipx install beanquery（暴露 bean-query），见本文第二节实测清单。

七、参考链接

Fava 官方文档：https://beancount.github.io/fava/
Beancount 官方文档与教程：https://beancount.github.io/docs/
beanquery（BQL）文档：https://pypi.org/project/beanquery/
Fava Releases：https://github.com/beancount/fava/releases/
本专栏配置详解篇：《Fava 1.30.16 配置参数详解》