Beancount 常用 CLI 工具速查
裝好 beancount 之後（pip install beancount），會多出一組 bean- 開頭的命令列工具。這篇整理日常記帳會用到的四個。 bean-check — 驗證帳本 最常用、也最重要的工具。會把你的 .beancount 檔讀進去，檢查有沒有語法錯誤、帳戶是否都有 open、複式記帳是否平衡。 bean-check main.beancount順利的話，不會有任何錯誤訊息顯示。 出錯時會把檔案路徑、行號、原因一條一條列出來，可以根據那一個交易來進行確認錯誤原因。 我自己的節奏是寫完一小段就 bean-check 一下，剛改的內容還在腦袋裡，看到報錯比較好對應到剛才動了什麼。等到累積二三十筆再一次驗，常常會卡在「到底是哪一邊的錯」，常常會找半天。 bean-query — 用 SQL 查帳本 beancount 內建一個類 SQL 的查詢介面，叫 BQL（Beancount Query Language）。可以互動式進入： bean-query main.beancount或一次性執行單一查詢： bean-query main.beancount "SELECT account, sum(position) WHERE account ~ 'Expenses:Food' GROUP BY account"常用情境：看某類別的總支出 篩選特定商家（例如所有「全聯」的消費）的所有交易 依月份統計收支進到互動模式後輸入 help 可以看可用語法。完整文件：Beancount Query Language。 bean-format — 對齊欄位 手寫帳本時數字與貨幣很容易亂跑，看起來沒有對齊。bean-format 會把每一行的金額靠右對齊： bean-format main.beancount > main.formatted.beancount或直接覆蓋原檔（先 commit 過再做）： bean-format -o main.beancount main.beancount很多編輯器（VS Code、Vim、Emacs）都有 beancount plugin，存檔時自動跑 format，不一定要手動。 fava — 網頁介面 fava 是另外裝的套件，提供網頁介面總覽資產的相關資訊： pip install fava fava main.beancount預設開在 http://localhost:5000，提供：收支報表、淨值變化圖 餘額試算表（Trial Balance）、損益表（Income Statement）、資產負債表（Balance Sheet） 各帳戶的明細與圖表 互動式 BQL 查詢介面整理工具 用途 何時用bean-check 驗證 每次寫完一段bean-query SQL 查詢 寫客製化報表bean-format 對齊欄位 整理格式fava 網頁報表 看圖、明細
Beancount 的 open 與 close — 帳戶開立與關閉
要在 beancount 裡記任何一筆交易之前，每個帳戶都必須先用 open 宣告。這篇整理 open / close 的語法與常見錯誤。 範例都用台幣 TWD，先不討論多幣別。 基本語法 2024-01-01 open Assets:Bank:Cathay TWD 2024-01-01 open Liabilities:CreditCard:Citi TWD 2024-01-01 open Income:Salary TWD 2024-01-01 open Expenses:Food TWD格式是 {日期} open {帳戶名} {貨幣}。 帳戶名的第一段必須是五大根帳戶之一：Assets、Liabilities、Income、Expenses、Equity。後面用冒號 : 分階層，想開幾層都可以，例如 Expenses:Food:Eatout 就是「外食」分類。 最後的 TWD 是這個帳戶允許出現的貨幣。寫上去之後，如果某天交易把別的幣別塞進來，bean-check 會發出 warning，防止不同幣別混用的問題。 Close 帳戶 2024-12-31 close Assets:Bank:OldAccount關閉前帳戶餘額必須是 0，否則 bean-check 會擋。實務流程是先轉移餘額到新帳戶，下一行再 close： 2024-12-30 * "Migrate balance to new account" Assets:Bank:OldAccount -12345.00 TWD Assets:Bank:NewAccount 12345.00 TWD2024-12-31 close Assets:Bank:OldAccount關閉之後不能再有任何 transaction 動到這個帳戶。 規則整理一個帳戶只能 open 一次、close 一次 open 的日期必須早於該帳戶任何 transaction 沒 open 就用，bean-check 會報錯 close 之前餘額必須歸零常見錯誤open 日期太晚：你 1 月就在用的悠遊卡帳戶卻寫成 6 月 open，等於跟 beancount 說「這個帳戶 6 月才開」。bean-check 執行時，1 到 5 月每一筆儲值與扣款都會被當成「動到一個還沒存在的帳戶」因此報錯。
