Beancount CLIリファレンス

このリファレンスを使用して、beaコマンドとその動作を調べてください。最初の台帳については、CLIクイックスタートに従ってください。銀行ファイルについては、インポートウォークスルーを使用してください。

コマンド一覧​

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

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

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に対して相殺されます。負債は負の値です。通貨入力は大文字に変換されます。カスタムシンボルは許可されています; 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つのpostingは金額を省略できます。番号付きpostingは、勘定科目に許可された通貨が1つある場合、または台帳に互換性のある運用通貨が1つある場合に、通貨を省略できます。それ以外の場合は、シンボルを指定します。

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

通貨交換には実際の取引レートが必要です。たとえば、EURで開設された勘定科目に100 EUR @ 1.08 USDをpostし、当座預金に-108 USDをpostします。投資購入では、AAPLで開設された勘定科目に2 AAPL {100 USD}をpostし、当座預金に-200 USDをpostできます。レポートで市場評価が必要な場合は、日付付きのpriceクォートを追加します。

メタデータは--meta 'receipt:IMG_42.jpg'などの裸の文字列を受け入れます。ネイティブの数値、ブール値、日付、および金額は型を保持します。例には--meta 'reviewed:TRUE'、--meta 'received:2026-08-03'、および--meta 'fee:2.50 USD'が含まれます。内部の引用符は文字列を強制します: --meta 'code:"1234"'。キーは一意である必要があります; filenameとlinenoは予約されています。

単一追加、一括追加、およびインポートは、payee、narration、および文字列メタデータの改行をスペースに置き換えます。引用符とバックスラッシュはその内容を保持します。

他のディレクティブを追加する​

これらすべてのコマンドには--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です。

postingはamountまたはunitsのいずれかを使用します。例: {"number":"45.00","currency":"USD"}。バランスpostingの場合は両方を省略します。postingフィールドには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で結果を説明します; そこでの行インデックスはゼロベースです。人間が読む行番号は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と同じ整列を使用し、その宛先の既存の列を再整列する場合があります。

ディレクティブを一覧表示する​

bea list TYPEは11のタイプをサポートします: transaction、open、close、balance、pad、note、event、price、commodity、document、およびcustom。

他のディレクティブタイプは時系列順を保持します。勘定科目でフィルタリングされた取引テーブルは、その金額列をMATCHING POSTING AMOUNTSとラベル付けします。詳細とJSONには、選択された各取引のすべてのpostingが含まれます。詳細はロードされたエントリをレンダリングし、推論された金額も含みます; これらは生のソース抜粋ではありません。

チェック、フォーマット、およびクエリ​

bea checkはルートとインクルードを検証します。台帳エラーの場合は終了コード1で終了し、--allow-errorsオプションはありません。クエリ、リスト、およびレポートも、明示的に--allow-errorsオプションを渡さない限り、ローダーエラーを拒否します。

フォーマットは.bean/.beancountファイルまたはディレクトリを受け取ります。ディレクトリは再帰的に検索されます。

すべてのモードはファイルと行ごとに構文エラーを報告し、それらのファイルをスキップして終了コード1で終了します。再帰的な通常実行は、有効なファイルをフォーマットできます。JSONは失敗時にerror.resultの下でscanned、formatted、skipped、dry_run、およびcheckを報告します。

bea query "BQL"はBeancountクエリを実行します。BQLを省略すると対話型シェルが開きます; exitまたはquitで閉じます。無人実行ではクエリ引数が必要です。BQLのデフォルトテーブルはpostingごとに1行です。クエリテーブルは精度を保持します。空の結果は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などのオフセットが含まれます。勘定科目フィルターは、一致する取引のすべてのpostingを保持します。

変換はデフォルトで台帳の唯一の運用通貨になります。それ以外の場合は、商品を分離したまま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は1回だけ回答して終了します。それ以外の場合、ターミナルセッションは対話型であり、オプションの質問がその入力を事前入力します。非対話型の使用には質問が必要です。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も識別します。10進数の金額と日付は文字列を使用します。制限付きリストには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は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を使用します。ソースリポジトリリファレンスには、追加の例と正確なディレクティブモデル定義が含まれています。