Beancount CLI リファレンス

このリファレンスは、bea コマンドとその動作を調べるために使用します。最初の元帳については、CLI クイックスタートに従ってください。1か月の月末処理を最初から最後まで完了するには、bea での最初の1か月を進めてください。銀行ファイルについては、インポートのウォークスルーを使用してください。

コマンド一覧​

グローバルオプションとパス​

グローバルオプションはコマンドの前に置きます:

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 と相殺されます。負債は負の値です。通貨入力は大文字に変換されます。カスタムシンボルも許可されますが、3つの大文字でないシンボルはタイプミス警告をトリガーします。これは 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'

1つのポスティングはその金額を省略できます。番号付きポスティングは、勘定科目が許可する通貨を1つ持つか、元帳が互換性のある運用通貨を1つ持つ場合、通貨を省略できます。それ以外の場合はシンボルを指定してください。

ネイティブポスティング構文は 84/2 EUR などの算術、{100 USD} などのコスト、合計コスト {{1000 USD}}、および価格 @ または @@ をサポートします。1e3 などの指数表記ではなく、1000 などの10進数金額を使用してください。

通貨交換には実際のトランザクションレートが必要です。たとえば、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-date で別の早い日を選択できます。両方の勘定科目がアクティブでなければなりません。スタンドアロンのパッドを消費するには、後の残高が必要です。--allow-errors はその中間状態をステージングできますが、無効なパッド勘定科目をバイパスすることはできません。

add price はルートとそのインクルード全体で、完全に同じ日付/商品/価格の重複をスキップします。終了コード 0 で終了し、既存の場所を識別します。異なる日付または価格は新規追加です。

ドキュメントパスは、ディレクティブを含むファイルの隣で解決されます。--into years/2026.bean と --filename receipt.pdf を指定すると、years/receipt.pdf を意味し、シェルの作業ディレクトリの隣のファイルではありません。

カスタム値の種類は 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 に記述します。そこでの行インデックスは0から始まります。人間が読む行番号は1から始まります。

バルク追加は --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 は11種類のタイプをサポートします: 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 を使用する場合、stdout がエンベロープを運ぶことができるように -i、-o FILE、--check、または --dry-run を選択してください。入力ファイルに stdout をリダイレクトしないでください。書き換えるには -i を使用してください。

bea query "BQL" は Beancount クエリを実行します。BQL を省略すると、stdin からクエリを読み取るか、stdin がターミナルの場合はシェルを開きます。シェルを閉じるには .exit、exit、または quit を使用します。BQL のデフォルトテーブルはポスティングごとに1行です。クエリテーブルは精度を保持します。

コマンドの前に元帳を選択します（例: 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 リリースでは、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 はどちらのオプション機能も必要としません。

管理対象価格インクルード​

Live Prices は別の管理対象インクルードワークフローです。ホスト型元帳はサポートされている価格 URL を解決します。互換性のある bea バージョンも管理対象インクルードとローカル価格エクスポートをサポートします。インストール済みバージョンがこれらのコマンドを認識しない場合は、バージョン固有の管理対象価格ガイドを確認してください。

CLI は資格情報を送信せずに許可リストに載った管理対象 URL を解決し、リダイレクトを拒否します。ホスト型ログインにリダイレクトするフィードは、新しいローカルフェッチでは利用できません。Web サイトにサインインしても、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 を受け付けます。trial balance を除くすべては --interval / -i も受け付けます: デフォルトは monthly、または quarterly、yearly、weekly、または daily。

bea balance [ACCOUNT...] は大文字小文字を区別しない部分文字列に一致する勘定科目の残高サブツリーを出力します。何も指定しない場合は元帳全体を出力します。--conversion / -x、--time / -t、および --allow-errors を受け付け、interval または account オプションは取りません。

時間フィルタには年、月、日付、四半期、週、または範囲が含まれます（例: 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) で、利益の場合は正です。同じ規則が income-statement の期間行にも適用されます。貸借対照表の調整はレポート用に派生され、ディレクティブは書き込みません。equity_reconciled は完全な調整が利用可能かどうかを識別します。

レポート JSON は、期間、排他的終了日、基準日、変換、勘定科目フィルタ、および元帳検証ステータスも識別します。合計を比較する前にそれらのフィールドを確認してください。

オプションのAI支援​

bea ask は ask extra と、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 も識別します。10進数の金額と日付は文字列を使用します。制限付きリストには limit と truncated が含まれます。

失敗は {"error":{"category":"validation","message":"…","exit_code":1}} を stderr に書き込みます。エラーには details、result、バックエンドの request_id、および --debug 付きの traceback も含まれる場合があります。

ミューテーションを再試行する前に error.result を確認してください。部分的なバッチは受け入れられた行を書き込む可能性があり、再帰的フォーマットは有効なファイルを変更する可能性があり、create-and-clone は非ゼロで終了する前にホスト型元帳を作成する可能性があります。このエンベロープを 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 は JSON モードを含め、パッケージマネージャーの出力を stderr にストリーミングできます。

設定、更新、および保存された状態​

真値は 1、true、yes、および on で、大文字小文字と周囲の空白を無視します。設定状態には、資格情報、Ask プロンプト履歴、ユーザースキル、記憶されたインポーターパス、および更新チェックキャッシュが含まれます。書き込みロックは、元帳ディレクトリの外のキャッシュディレクトリの locks/ の下にあります。

bea upgrade --check はアップグレードせずにバージョンとインストール方法を報告します。bea upgrade は brew upgrade bea、uv tool upgrade beancount-io、または pipx upgrade beancount-io を呼び出します。編集可能インストールは手動更新ガイダンスを受け取ります。パッシブチェックは、対話型のインストール済みコピーで1日に最大1回実行されます。パッシブ通知が無効になっていても、明示的な upgrade --check は依然として実行されます。

一致するマネージャーでアンインストールします: brew uninstall bea、uv tool uninstall beancount-io、または pipx uninstall beancount-io。元帳ファイルとユーザー設定は残ります。

一般的な修正​

インストール済みバージョンを検査するには bea COMMAND --help を使用します。ソースリポジトリリファレンスには、追加の例と正確なディレクティブモデル定義が含まれています。