Beancount CLI 快速入门

使用 bea（Beancount.io 的命令行工具）创建本地账本并记录你的第一笔消费。本地记账无需 Beancount.io 账户。

本教程从活期账户中有 1,000 美元开始。购买一杯 12.50 美元的咖啡后，你将验证余额为 987.50 美元。

1. 安装命令​

在 macOS 或 Linux 上使用 Homebrew：

brew install bex-co/tap/bea
bea --version

如果你不使用 Homebrew，请安装 uv 并使用 uv tool install beancount-io。该 Python 包需要 Python 3.12 或更高版本。

2. 创建你的账本​

选择一个新目录。此示例在 ~/my-books 中创建 main.bean：

bea --no-input init ~/my-books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd ~/my-books

模板会开设常见的活期、储蓄、现金、信用卡、收入和支出账户。期初余额与 Equity:OpeningBalances 相抵。

对于你自己的账簿，请选择你打算记录的最早日期。所有模板账户都在该日期开设。期初余额必须描述该日期的账户状态。信用卡债务使用负数金额。

init 永远不会覆盖现有账本。在 POSIX 系统上，新文件是私有的：只有所有者可以读写。要与你的本地用户组共享，请使用 chmod 640 main.bean 明确更改权限。

如需引导式设置，请在终端中运行 bea init ~/my-books。向导会询问你的货币、历史开始日期和活期余额。

3. 记录一笔消费​

bea add transaction --date 2026-08-02 --narration "Coffee" \
  --posting "Expenses:Dining 12.50" \
  --posting "Assets:Checking"

支出使用账户的美元货币。Beancount 会自动填入另一笔分录为 -12.50 USD。对于今天的消费，你可以省略 --date。

每次添加都会在文件被替换前对照完整账本进行检查。未知账户或不平衡的交易会产生带有指导信息的错误。

4. 检查结果​

bea check
bea list transaction --limit 10
bea report balance-sheet

交易列表首先显示最新条目及其分录金额。资产负债表显示活期账户中的 987.50 USD。

要直接验证该金额：

bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

查询表保留结果的精度。如需结构化输出，请在命令前放置全局 --json 标志：

bea --json list transaction --limit 10

5. 保持账簿良好状态​

手动编辑文件后运行 bea check。运行 bea format main.bean 对齐列。当脚本应在需要格式化时失败时，使用 bea format main.bean --check。

要从其他目录工作，请明确选择根文件：

bea --file ~/my-books/main.bean check

根文件通过 --file 选择，然后是 BEA_FILE，最后是工作目录中的 main.bean。全局选项放在命令之前。格式化接受单独的文件或目录参数。

继续记录你自己的账目​

• 导入银行导出 并带有预览和重复项审核。
• 查找命令和选项 了解账户、余额、投资、报表和自动化。
• 跨文件组织账本。使用 --into 在针对根文件验证的同时写入包含的文件。
• 使用浏览器界面 如果你更喜欢表单而不是终端命令。

使用 bea upgrade --check 检查更新。运行 bea upgrade 调用安装你的副本的包管理器。使用 bea --help 或 bea add transaction --help 查看已安装版本中可用的选项。