--json 出力リファレンス¶
このページは alpha-forge CLI の --json 出力の 契約（スキーマ）リファレンスです。エージェントや MCP・パイプから出力をパースする際の安定した参照点として、主要コマンドのトップレベルフィールド・型・envelope 規約と、schema_version / forge_version の意味および増分ルールを定めます。
stdout 純度・envelope・終了コードの規約そのものは エージェントから見た CLI 規約 を参照してください。本ページはそこに「実際に出るフィールドの一覧」を補完します。
実行時カタログ
全コマンドの 機械可読カタログ（どのコマンドが --json を持つか・各オプションの型）は alpha-forge system describe --json で取得できます。本ページが「--json が返すフィールドの意味」、system describe --json が「どのコマンドに --json があるか」という役割分担です。
envelope の 3 系統¶
出力形状はコマンドの性質ごとに 3 系統に分かれます。
- 一覧系（
list/scan-all等）:{"<複数形>": [...], "count": n}の envelope。データ不在でも空配列 + 終了コード0。 - 単一実行系（
backtest run/optimize walk-forward/backtest monte-carlo等）: envelope を持たない 生のオブジェクト（トップレベルに指標やメタフィールドが並ぶ）。 - エラー:
{"error": ..., "code": ..., "id": ...}の 3 キー固定（本ページ下部の「エラー出力」を参照）。
パーセント表記のフィールド（*_pct）は 既にパーセント単位の数値です（例: 17.39 は +17.39%）。追加で 100 倍しないこと。
schema_version / forge_version¶
backtest run --json の出力には次の 2 つのメタフィールドが含まれます。
| フィールド | 型 | 意味 |
|---|---|---|
schema_version |
int | CLI 出力 JSON のスキーマ世代。現在 1。下記の増分ルールに従って bump する |
forge_version |
string | この出力を生成した alpha-forge のバージョン（例 "0.15.0"） |
戦略 JSON 側の schema_version とは別物
ここでの schema_version は CLI 出力 JSON の契約世代であり、戦略 JSON ファイル側の schema_version（strategy show --json で見える戦略定義のスキーマ世代）とは別概念です。
増分ルール（いつ bump するか）¶
schema_version は 互換性を壊す変更を入れたときにのみ +1 します。
| 変更内容 | bump するか |
|---|---|
| 既存フィールドの 削除 / 改名 | する |
| 既存フィールドの 型変更 / 意味変更 | する |
| 新規フィールドの追加（既存は不変） | しない（追加は後方互換） |
| envelope 形状の変更 | する |
| 表示整形のみ（compact ↔ indent・キー順） | しない |
原則は 「追加は互換・削除/改名/型変更/意味変更は非互換」。forge_version は毎リリースで自然に進むため、「いつ変わったか」の追跡は forge_version、「消費側コードを直す必要があるか」の判断は schema_version で行えます。
backtest run --json¶
envelope なしの生オブジェクトで、メトリクスがトップレベルに並びます（実測で 60+ フィールド）。ここでは契約に関わる主要フィールドのみを示します。
| フィールド | 型 | 出力条件 | 意味 |
|---|---|---|---|
schema_version |
int | 常に | CLI 出力スキーマ世代 |
forge_version |
string | 常に | 生成元バージョン |
warnings |
array | 常に | 実行時の注意（少トレード等） |
freemium_limit_notices |
array | 常に | Trial 制限通知（code を含む） |
run_id |
string | 実 run があるとき | run の識別子 |
result_id |
string | 結果保存があるとき | 保存済み結果の識別子 |
pre_filter_pass |
bool | pre-filter 評価時 | 事前フィルタを通過したか |
pre_filter |
object | pre-filter 評価時 | 適用閾値（sharpe_min / max_dd_max / monthly_volume_usd_min / min_trades / goal） |
criteria_check |
object | 合否基準があるとき | 合否 verdict（本体にマージ） |
next_step |
array | 次アクション提示時 | 次コマンド候補（文字列配列） |
carry_adjusted_metrics |
object | --carry でキャリー計上できたとき |
FX キャリー（金利差近似）込みの参考メトリクス。キー有無がキャリー計上有無の契約（未指定・計上不能時はキー自体が無い）。--split 併用時は IS 区間ベース |
carry_adjusted_note |
string | carry_adjusted_metrics があるとき |
近似方法と限界の注記 |
--split を付けると IS/OOS 比較メタが追加されます: out_of_sample_metrics（OOS メトリクス）・overfitting_score・overfitting_risk・walk_forward_summary（is_sharpe / oos_sharpe / is_return_pct / oos_return_pct / overfitting_score / overfitting_risk）。
--summary を付けると per-trade / per-bar 等の重い配列を除外した軽量 JSON になります（メタフィールドの契約は不変）。
optimize walk-forward --json¶
envelope なしの生オブジェクト。
| フィールド | 型 | 意味 |
|---|---|---|
symbol / strategy / metric |
string | 対象銘柄・戦略 ID・最適化メトリクス |
windows |
array | ウィンドウごとの結果（IS/OOS メトリクス・skip_reason 等） |
is_valid_windows / valid_oos_windows / total_windows / skipped_windows |
int | 各種ウィンドウ数 |
all_is_invalid |
bool | 全ウィンドウで IS 最適化が失敗したか |
freemium_limit_notices |
array | Trial 制限通知 |
opt_run_id |
string | null | --save 指定時に記録した optimization_runs の run_id（--save なし・記録失敗時は null。キーは常に載る） |
pre_filter_pass |
bool | null | 平均 OOS メトリクスが閾値以上か（判定不能なら null） |
pre_filter |
object | 適用閾値（sharpe_min / max_dd_max / min_trades / goal） |
pre_filter_pass / pre_filter は --goal を省略しても既定閾値で必ず載り、backtest run と命名・契約を揃えています。
backtest monte-carlo --json¶
保存済みバックテスト結果のトレード履歴からモンテカルロシミュレーションを実行します。envelope なしの生オブジェクト。
| フィールド | 型 | 意味 |
|---|---|---|
initial_capital |
number | 初期資産 |
simulations_run |
int | 試行回数 |
mean_final_equity / median_final_equity / worst_final_equity / best_final_equity |
number | 最終資産の統計 |
mean_max_drawdown_pct / max_drawdown_95pct |
number | 最大ドローダウン（平均・95 パーセンタイル） |
ruin_probability_pct |
number | 破産確率（%） |
pre_filter_pass |
bool | null | 破産確率が既定閾値（5%）以下か |
pre_filter |
object | max_ruin_pct（既定 5.0） |
有効なトレードが 10 件未満の場合は stderr にエラーを出して終了コード 1 になります（純 JSON は出ません）。
backtest dca --json¶
積立（ドルコスト平均法）のシミュレーション。envelope なしの生オブジェクトです。数値は丸めません（irr_pct だけ小数第4位に丸めます）。コマンドの説明は CLI リファレンスの backtest dca を参照してください。
1窓（--rolling-years なし）
| フィールド | 型 | 意味 |
|---|---|---|
symbol / start / end |
string | 銘柄と窓（日付は YYYY-MM-DD） |
total / months / buy_day / cost_pct |
number / int | null / string / number | 総額・買う回数（未指定は null＝窓の月数）・買う日・片道コスト率（%） |
final / invested / cash / units |
number | 最終額・入れた総額・未投資の現金（通常 0）・口数 |
buys / boosted |
int | 買った回数・買い増しの条件が真だった回数（金額 0 の回は数えない） |
underwater |
bool | final < invested（丸め前） |
mdd_pct / irr_pct |
number | 評価額の最大下落（%）・入金の時期を考えた年率利回り（%） |
curve |
array | {"date", "value", "invested"} の日次系列 |
lump |
object | null | --compare-lump のときの一括（窓の最初の営業日に総額を買う）。curve を除く同じキー |
全窓（--rolling-years N）
| フィールド | 型 | 意味 |
|---|---|---|
years / range |
int / array | 窓の年数・全窓を取る範囲 [開始, 終了] |
rows |
array | 窓ごとに start / end / final / invested / underwater / irr_pct / mdd_pct / boosted / lump_final / lump_wins（後ろ2つは --compare-lump のときだけ値、それ以外は null。lump_wins は lump_final > final を丸め前で判定） |
summary |
object | n_windows / n_underwater / n_lump_wins（--compare-lump なしは null） |
引数の検証エラー（--boost-dd と --boost-sma の同時指定・不正な --buy-day・窓を超える --months など）は終了コード 2、未知の --cost-preset と fixed_per_share を持つプリセットは終了コード 1 です。
backtest withdraw --json¶
取り崩し（定額/定率・物価連動・guard）のシミュレーション。envelope なしの生オブジェクトです。数値は丸めません。コマンドの説明は CLI リファレンスの backtest withdraw を参照してください。
1窓（--rolling-years なし）
| フィールド | 型 | 意味 |
|---|---|---|
symbol / start / end |
string | 銘柄と窓（日付は YYYY-MM-DD） |
initial / rate_pct / mode / cpi |
number / number / string / string | null | 元手・取り崩し率(%)・fixed/percent・--cpi の保存キー（未指定は null） |
guard / guard_cut_pct / cost_pct |
string | null / number / number | guard ルール（yoy/dd:N/null）・発動時の減額率(%)・片道コスト率(%) |
final / final_real |
number | 最終評価額（名目・実質。--cpi 未指定時は同値） |
depleted / depleted_year |
bool / int | null | 窓の途中で尽きたか・尽きた回（尽きていなければ null） |
withdrawn_total / withdrawn_real_total |
number | 取り崩した総額（名目・実質） |
min_withdrawal_ratio |
number | 実質取り崩し額の最小値 ÷ 初回実質取り崩し額 |
guarded |
int | guard が発動した回数 |
schedule |
array | {"date", "amount", "amount_real", "balance_after"} の取り崩しごとの系列 |
全窓（--rolling-years N）
| フィールド | 型 | 意味 |
|---|---|---|
years / range |
int / array | 窓の年数・全窓を取る範囲 [開始, 終了] |
rows |
array | 窓ごとに start / end / final / final_real / depleted / depleted_year / withdrawn_total / withdrawn_real_total / min_withdrawal_ratio / guarded（schedule は含まない） |
summary |
object | n_windows / n_depleted |
引数の検証エラー（--guard と --mode percent の同時指定・--guard の形式違い・--guard-cut が0/10/20以外・--rate が範囲外・--initial が0以下・物価が窓の取り崩し日に届いていない等）は終了コード 2、--cpi の系列が未取得の場合は終了コード 1 です。
一覧系の envelope¶
一覧・スキャン系は {"<複数形>": [...], "count": n} を返します。データ不在でも空配列 + 終了コード 0 です。
| コマンド | envelope キー | 要素の主なキー |
|---|---|---|
strategy list --json |
strategies / count |
strategy_id / name / version / asset_type / timeframe / tags / notes / created_at / updated_at |
backtest list --json |
results / count |
保存済み結果の行（strategy_id / symbol / 主要メトリクス） |
analyze indicator list --json |
indicators / count |
name / category（--detail で params も） |
analyze pairs scan-all --json |
pairs / count |
共和分検定結果（加えて cointegrated_count） |
system describe --json |
commands / count |
command / path / options / json_supported |
エラー出力¶
存在しない ID を渡した等の not found 系エラーは、--json 指定時に stdout へ次の 3 キー固定の JSON を出し、終了コード 1 で終了します。
| フィールド | 型 | 意味 |
|---|---|---|
error |
string | ローカライズ済みメッセージ |
code |
string | 機械判定用の安定コード（例 strategy_not_found） |
id |
string | 見つからなかったリソース ID |
--json を付けない場合は stderr に 1 行のメッセージを出して終了コード 1（stdout は空）。引数エラー（Click UsageError）は終了コード 2 です。
関連リンク¶
- エージェントから見た CLI 規約 — stdout 純度・envelope・終了コードの規約
- alpha-forge-mcp リファレンス — MCP 経由での利用