CLI リファレンス

klaus のコマンドは run(フロー実行)・ui(localhost Web UI 起動)・validate(スキーマ検証)・schema(JSON Schema 出力)・generate(OpenAPI 仕様からのフロー生成。OpenAPI からのフロー生成を参照)・init(雛形生成)・history(実行履歴の参照)の7つ。

--help

klaus --help および klaus run --help の末尾には、docs サイト(このサイト。英語版はサイトのルート、/en/ 配下ではない)へのリンク・klaus init で雛形生成できる旨・exit code の一行要約が付与される。

klaus run

klaus run <files...> [options]

複数ファイルを渡すと順次実行する(glob 展開はシェルに任せる)。

オプション	説明	デフォルト
`--env <name>`	フロー定義の `env:` 指定を上書き(`--env-file` とは併用不可)	フローの `env:`
`--env-file <path>`	`environments/` 配下の名前付き環境の代わりに、任意パス(cwd 相対または絶対)の YAML ファイルから環境変数を読み込む。フロー定義の `env:` を上書きする。`-e`/`--env` とは併用不可	—
`--var <key=value>`	その場限りのテンプレート変数を設定する(繰り返し指定可。値自体に `=` を含められる。最初の `=` のみを区切りとして扱う)。環境ファイルの値と同じ名前空間(裸の `{{name}}`)に入り、環境から読み込んだ同名キーを上書きする	—
`--json`	TTY でも JSON 出力を強制	—
`--text`	非 TTY でも text 出力を強制(`--json` とは併用不可)	—
`--report <list>`	生成するレポート形式のカンマ区切りリスト: `junit`、`tap`(例: `junit,tap`)	—
`--report-file <path>`	`--report` で指定したレポート形式の出力先(繰り返し指定可。詳細は後述)	フォーマットごとの既定値(後述)
`--no-history`	履歴 JSONL への書き込みを無効化	履歴有効
`--no-mask`	stdout(JSON/text 出力とも)へのシークレットマスキングを無効化	マスク有効
`--record <dir>`	record モード: 実際に HTTP リクエストを送信し、マスク済みの request/response ペアを `<dir>` のカセットに保存する	—
`--replay <dir>`	replay モード: 実ネットワークではなく `<dir>` のカセットから HTTP レスポンスを再生する(記録外リクエストは exit code 3 で失敗する)。`--record` とは併用不可	—
`--allow-protected`	`$protected: true` の環境ファイルへの実行を許可する(未指定時は exit code 3 で拒否)	—
`--data <path>`	データ駆動実行: この JSON/YAML データファイルの各行につき、指定した全フローファイルを1回ずつ実行する(詳細は後述の「データ駆動実行(--data)」を参照)	—
`--tags <list>`	カンマ区切りのタグ一覧。フローの `tags:` にいずれか1つでも含まれるものだけを実行する(OR 条件。詳細は後述の「タグによるフロー選択」を参照)	—
`--exclude-tags <list>`	カンマ区切りのタグ一覧。フローの `tags:` にいずれか1つでも含まれるものを除外する。`--tags` より優先される	—
`--jobs <n>`	実行ユニットをこの数だけ並列実行する(1-32 の整数。詳細は後述の「並列実行(--jobs)」を参照)。`--record` とは併用不可	1(逐次実行)

--report はカンマ区切りのフォーマット一覧を受け取る(各要素は trim され、junit か tap のいずれかでなければならない)。未知のフォーマットや空要素を1つでも渡すと stderr にエラーを出して exit 1。--report はフォーマットの重複(例: --report junit,junit)や、--report-file の解決先パスがフォーマット間で同一になる場合も同様に stderr にエラーを出して exit 1 で拒否する(どちらも同一ファイルへの書き込みが競合するため)。--report に N 個のフォーマットを渡した場合、--report-file は同じ順序でちょうど N 回指定する(1個目の --report-file が1個目のフォーマットとペアになる)か、一度も指定しない(この場合フォーマットごとの既定ファイル名 — junit は klaus-report.xml、tap は klaus-report.tap — に書き出される)かのいずれかにする。それ以外の回数(例: 2フォーマットに対して --report-file を1回だけ)はエラーとして拒否され、exit 1 でどのファイルも書き出さない。これは単一フォーマットの従来挙動をそのまま一般化したものであり、--report junit 単体は変わらず klaus-report.xml が既定値になる。--json と --text、または -e/--env と --env-file を同時に指定した場合も同様に stderr にエラーを出して exit 1(何も実行しない)。この -e/--env と --env-file の併用エラーは、コマンドラインで明示的に指定した -e/--env に対してのみ発生する。klaus.config.yaml の run.env による既定値は、明示指定された --env-file と衝突せずそちらに道を譲る(CLI オプションの既定値参照)。

--env-file は、読み込んだファイルの $protected: true を名前付き環境と全く同じように尊重する: --allow-protected を併せて渡さない限り exit code 3 で拒否される。

--var の値は {{env.X}}(OS 環境変数参照)と異なり、シークレットとして登録されず、出力でもマスクされない。真のシークレットを渡したい場合は OS 環境変数経由で {{env.X}} として参照し、実行履歴に記載のマスキングの恩恵を受けること。

--env / --report / --report-file / --no-history / --no-mask / --jobs は klaus.config.yaml で既定値を設定できる。--var・--env-file・--data・--tags・--exclude-tags は設定できない。詳細は CLI オプションの既定値を参照。

タグによるフロー選択(--tags / --exclude-tags)

フロー定義には最上位で tags: [smoke, auth] を宣言できる(フロー定義リファレンス参照)。--tags と --exclude-tags はそれぞれカンマ区切りのリストを受け取る(各要素は trim される。trim 後に空文字列になる要素 — 先頭・末尾・連続するカンマなど — があるとエラーになり exit 0 以外・スタックトレース無しで終了する)。

--tags: 指定したタグのうち1つでも持つフローだけを残す(OR 条件)。未指定なら選抜段階での絞り込みは行わない(全フローが通過する)
--exclude-tags: 指定したタグのいずれかを持つフローを除外する。--tags の選抜段階の後に適用される。未指定なら除外を行わない。フローが --tags と --exclude-tags の両方に一致する場合は除外が優先される
タグ無しフロー(tags: フィールドが無い): --tags のどれとも一致しないため、--tags 指定時は除外される。--exclude-tags のどれとも一致しないため、--exclude-tags のみ指定時は保持される
絞り込みで落ちたフローは一切実行されない: タグによる絞り込みで除外されたフローはランナーに到達すらしないため、JSON/JUnit 出力にも実行履歴にも一切現れない。これは記録される skipped ステップとは異なる(ステップ失敗時のフロー挙動参照)
絞り込み結果が0件だとエラー: 絞り込みの結果、実行対象のフローが1件も残らない場合、klaus run は stderr に no flows match the specified tags を出力し、何も実行せず exit 1 で終了する。これは意図的な仕様で、CI でタグ名の typo により意図せず全緑の空実行になる事故を防ぐため
--data との組み合わせ: 絞り込みはデータ駆動実行の行展開より先に行われる — 行 × フローのイテレーションは、絞り込みを通過したフローのみを対象にする
klaus.config.yaml では設定不可(上述のとおり)

データ駆動実行(--data)

--data <path> を指定すると、指定した JSON/YAML データファイルの行ごとに、指定した全フローファイルを1回ずつ実行する(Newman 方式のデータ駆動実行)。データファイルはオブジェクトの配列でなければならず、各値はスカラー(string / number / boolean / null)のみ許容する(ネストしたオブジェクト・配列は拒否される)。CSV には非対応(JSON/YAML のみ。新規依存を追加しないための判断。詳細は src/core/data.ts のスキーマ定義コメントを参照)。空配列も拒否される。

反復順序: 行(外側)× フロー(内側)の順で反復する — flowA(行1), flowB(行1), flowA(行2), flowB(行2), ...(Newman のコレクションランナーと同じイテレーション優先順)
変数注入: 各行の値は --var や環境ファイルと同じテンプレートの env 名前空間(裸の {{name}})に入り、--var の同名キーを上書きし、--var は環境ファイルの同名キーを上書きする(この優先順位を維持)。capture 変数の解決順序には影響しない(従来どおり capture が env 名前空間より先に解決される)
値の変換: 行の値が number/boolean の場合は capture 変数と同様 String(value) で文字列化してから注入する。値が null のキーはそもそも注入されない — テンプレートで参照すると通常の未解決変数エラーになる(意図的な仕様)
マスク対象外: --var と同様、行の値はシークレットとして登録されず、出力でもマスクされない。真のシークレットには {{env.X}}(OS 環境変数参照)を使うこと
集約: 全イテレーションのフロー結果は同じ実行結果にフラットに並ぶ — いずれかのイテレーションが失敗すれば実行全体も失敗として扱われる(通常の複数フロー実行と同じ aggregateStatus・exit code のルール)
レポートへの反映: --data 使用時、各フロー結果には 1 始まりの iteration が付く。反映先は次のとおり: --json 出力の各フローエントリの iteration フィールド(追加のみの変更のため version は 2 のまま)、JUnit の <testsuite name="..."> に付く (iteration N) サフィックス(各 <testcase> の classname はフロー名のまま)、text 出力のフローヘッダーに付く (iteration N) サフィックス、実行履歴 JSONL の各エントリの iteration フィールド(追加のみの変更のため v は 1 のまま)

並列実行(--jobs)

--jobs <n> を指定すると、複数の実行ユニットを順番にではなく同時に実行する。実行ユニットとは1つのフローファイル(--data 指定時は、--data のイテレーション優先順が生成するのと同じ単位である「フローファイル × データ行」の組)を指す。<n> は 1〜32 の整数でなければならず、範囲外・非整数の値は --port/--last と同じ流儀で exit 0 以外・スタックトレース無しで拒否される。

デフォルトは 1(逐次実行)、Hurl のような既定並列ではない: klaus はここで意図的に Hurl 等のツールと異なる選択をしている。--jobs を指定しない場合、このオプションが存在する前のバージョンと出力がバイト単位で完全に一致する(ワーカープールも並び替えレイヤーも一切介さない、既定経路は無変更)。
フロー内のステップは --jobs の値に関わらず常に逐次実行のまま: 並列化されるのはユニット(フローファイル単位の実行)のみで、1つのフロー内のステップが並列化されることはない。ステップ N で capture した値をステップ N+1 で使うようなフローの挙動は従来と変わらない。
結果の順序は常に完了順ではなく入力順: RunResult.flows(したがって --json 出力・JUnit/TAP レポートの並び順・exit code の集約)は、どのユニットが実際に先に完了したかに関わらず、--data が既に使っているイテレーション優先順(行が外側・フローが内側)のまま並ぶ。runId・aggregateStatus・exit code は --jobs の影響を受けない。
text 出力の順序: --jobs を 2 以上にすると、klaus は各ユニットのステップ進捗行をバッファし、入力順で手前にある全ユニットが既に出力し終わってから、そのユニットの全ブロックをまとめて出力する — そのため実際のリクエストは並行して走っていても、text 出力を読む人間から見ると --jobs 1 のときと同じ順序のまま、入れ替わりも混在も起きない(実装上の補足: 現在最も進んでいるユニットをライブストリーミングする方式ではなく、各ユニットの出力を完全にバッファし、入力順で次に出力可能になったユニットからまとめて解放する方式を採用している)。
実行履歴の順序は保証されない: 各ステップは従来どおり .klaus/history/*.jsonl(実行履歴参照)に1行ずつ追記されるが、--jobs が 2 以上のとき、並行実行中の複数ユニットからの追記が書き込まれたタイミングの順にファイル中で混ざり得る — メモリ上の RunResult とは異なり、この JSONL ファイルの行の順序は入力順を反映しない。各エントリには runId/flow/step/startedAt が引き続き付くため、必要であれば読み出し側でグルーピング・順序の再構成ができる。書き込み自体が壊れたり途中で途切れたりすることはない(各行は1回の O_APPEND によるアトミックな書き込み)。相対的な順序のみが不定になる。
--record とは併用不可: record モードは同じカセットファイル(--record <dir>)へ、method+URL をキーとして全レスポンスを追記する。--jobs を 2 以上にすると、同一の method+URL への並行リクエストが実行のたびに異なる相対順序で追記され得るため、同じ method+URL への繰り返しリクエストを再生した際にどのレスポンスが返るか(findCassetteEntry は最初に記録された一致を採用する)が記録のたびに非決定的になってしまう。そのため --record と --jobs の 2 以上の組み合わせは、何も実行せずエラー・exit code 1 で拒否される。--replay にはこの制約は無い: 各ユニットはリクエスト送信を始める前に、それぞれ独立して自分用の読み取り専用カセット索引を読み込む(全ユニットで1つの索引を共有・事前に一括読み込みするわけではない) — replay 中はカセットファイルへの書き込みが一切発生しないため、この並行した独立読み込みは --jobs を 2 以上にしても安全である。

出力モード

自動判定: stdout が TTY なら text、非 TTY(パイプ / エージェント実行 / CI)なら JSON。--json で非 TTY でも JSON を強制、--text で TTY でなくても text を強制できる(両者は同時指定不可)
結果データは stdout、診断メッセージ(パースエラー・警告)は stderr に分離される

text 出力(人間向け)

ステップ完了ごとにインクリメンタルに出力される。成功は1行要約のみ、失敗時だけ詳細を出す(フル詳細は履歴 JSONL 側に残る)。

認証フロー (/path/to/auth-flow.yaml)
  PASS login (200, 6ms)
  FAIL get-me (200, 3ms)
    body $.email: expected "a@example.com" but got "b@example.com"
  SKIP logout: skipped because a previous step failed

1 flow, 3 steps: 1 passed, 1 failed, 1 skipped (12ms)

行種別: PASS / FAIL(失敗アサーションの expected/actual、レスポンスボディは約500文字で切り詰め)/ SKIP(理由付き)/ ERROR(runtime エラーのメッセージ)
TTY では ANSI 色付き(pass=緑 / fail=赤 / skip=黄)。--json 時は常に色なし。環境変数 NO_COLOR(色を無効化)/ FORCE_COLOR(非 TTY でも色付け。FORCE_COLOR=0 は無効化)にも対応。ただし非 TTY で FORCE_COLOR を効かせるには text 出力自体を強制する --text の併用が必要(非 TTY のままでは既定で JSON 出力になり、色付き text 経路に到達しない)
FAIL の詳細行・ERROR のメッセージ(レスポンス本文由来)に含まれる制御文字は、可視エスケープ(\n / \r / \t / \xNN)に変換されたうえで出力される。改行も対象にしているのは、レスポンス本文に改行を仕込んで偽の PASS 行を捏造したり出力を隠したりする端末出力の偽装を防ぐため

JSON 出力(機械向け)

実行完了後に1個の JSON(pretty print なし、1行の compact JSON)を stdout に出力する。逐次出力はしない。エージェント向けにトークン数を抑えるため failure-focused な構造にしてある: 成功(passed)したステップは name / status / durationMs のみの1行要約に落とし、failed / error / skipped のステップだけ request/response スナップショットや assertions などの詳細を持つ。

jsonc

{
  "version": 2,           // 出力スキーマのバージョン
  "runId": "<uuid>",
  "startedAt": "2026-08-08T…",
  "durationMs": 123,
  "status": "passed",     // "passed" | "failed" | "error"
  "summary": { "flows": 1, "steps": 2, "passed": 1, "failed": 1, "error": 0, "skipped": 0 },
  "flows": [
    {
      "name": "認証フロー",
      "file": "…",
      "status": "failed",
      "durationMs": 120,
      "steps": [
        {
          // passed ステップは1行要約のみ(historyRef は履歴記録が有効なときだけ付与)
          "name": "login",
          "status": "passed",
          "durationMs": 6,
          "historyRef": { "date": "2026-08-08", "runId": "<uuid>", "step": "login" }
        },
        {
          // failed/error/skipped ステップは詳細を持つ
          "name": "get-me",
          "status": "failed",
          "durationMs": 4,
          "historyRef": { "date": "2026-08-08", "runId": "<uuid>", "step": "get-me" },
          "startedAt": "2026-08-08T…",
          "request": { "method": "GET", "url": "…", "headers": {}, "body": "…" },
          "response": { "status": 200, "headers": {}, "body": "…" },
          "assertions": [ { "ok": false, "kind": "status", "expected": 200, "actual": 401, "message": "…" } ]
        }
      ]
    }
  ]
}

truncate: 詳細に含まれる request/response の body(JSON ボディは文字列化してから)、SSE events の data、WS wsMessages の data はいずれも約500文字で切り詰める(text 出力の切り詰めと同じ規則)。JSON ボディの構造そのままの全文は履歴側にしか無い
{{env.X}} 由来のシークレットは既定でマスクされる(履歴 JSONL・--report junit と同じ規則。URL エンコード形(encodeURIComponent 形・form-urlencoded 形・WHATWG URL 正規化に近い encodeURI 形)・JSON エスケープ形も対象。詳細は実行履歴を参照)。--no-mask を付けるとこの JSON 出力のマスクだけを無効化できる(履歴 JSONL・JUnit ファイル出力は常にマスクされる)
制御文字の可視エスケープ(text 出力や JUnit レポートで行われるもの)はここには適用されず、生の値のまま出力される
historyRef: 履歴記録が有効な実行(--no-history を付けていない)では、各ステップ(passed 含む)に historyRef: { date, runId, step } が付く。全文が必要な場合は klaus history show <runId> --step <step> で取得する(詳細は klaus history / 実行履歴を参照)。--no-history 実行時は historyRef を省略する
SSE / WebSocket ステップでは response.body は無く、受信データは events(SSE)/ wsMessages(WS)フィールドに入る

JUnit レポート

--report junit で flow = <testsuite>、step = <testcase> の XML を --report-file に書き出す。stdout の text / JSON 出力とは独立して併用できる。特殊文字は XML エスケープされる。

{{env.X}} 由来のシークレットは履歴 JSONL と同じ規則でマスクされる(URL エンコード形(encodeURIComponent 形・form-urlencoded 形・WHATWG URL 正規化に近い encodeURI 形)・JSON エスケープ形も対象。詳細は実行履歴を参照)。このマスクは stdout の text / JSON 出力(--json を含む)にも既定で適用される。--no-mask を付けると stdout 側のマスクだけを無効化できる — 履歴 JSONL・JUnit ファイル出力は常にマスクされ、--no-mask の影響を受けない。レスポンス本文由来の制御文字は XML 1.0 が許容するタブ・LF・CR 以外を可視エスケープ(\xNN)に変換したうえで書き出される。この制御文字の可視エスケープは JUnit レポートと text 出力にのみ適用され、JSON 出力(--json を含む)には適用されない。

TAP レポート

--report tap で TAP version 13 形式のファイルを --report-file に書き出す: 先頭の 1..N プラン行(N = 全フロー通しての総ステップ数)に続けて、実行順に1ステップ1行の ok/not ok 行(<flowName> > <stepName> という名前)が並ぶ。skipped ステップは # SKIP <理由> ディレクティブ付きの ok として表現される(TAP には専用の skip 行が無いため)。failed/error ステップは not ok になり、失敗したアサーションごとに1行の # ... 診断コメント(error ステップは実行時エラーメッセージ)が続く。flow/step 名や診断メッセージに含まれる改行と # は、行指向の TAP フォーマットを壊さないようエスケープされる。

マスキングは JUnit レポートと同じ規則に従う({{env.X}} 由来のシークレットを制御文字のサニタイズより先にマスクし、--no-mask の影響を受けない)。

--report にカンマ区切りリストを渡す(例: --report junit,tap)と、1回の実行で両方のフォーマットを生成できる。ペアリングの規則は前述の --report/--report-file の説明を参照。

exit code

code	意味
0	全件成功
1	一般エラー(不正な CLI 引数・予期しない例外)
2	定義ファイルのパースエラー
3	実行時エラー(接続不能・タイムアウト・キャプチャ失敗等)
4	アサーション失敗

判定ルールの詳細:

実行前に全ファイルをパース検証する。1件でもパースエラーがあれば何も実行せず、stderr にファイル名と理由を出して exit 2
実行中に環境ファイル(environments/*.yaml)のパースエラーが出た場合も exit 2
実行後、runtime エラー(status "error")を含むフローがあれば 3、なければアサーション失敗(status "failed")があれば 4、全成功で 0。3 と 4 が混在する場合は 3 を優先
履歴 JSONL の書き込み失敗は stderr への警告のみで、ステップ結果・exit code には影響しない

エージェント(Claude Code 等)は exit code だけで故障箇所を判別できる: 2 なら定義を直す、3 なら対象 API の起動状態を見る、4 ならアサーション内容とレスポンスを比較する。

klaus ui

klaus ui [-p <n>] [-H <host>] [--no-open]

オプション	説明	デフォルト
`-p`, `--port <n>`	待ち受けポート	`4884`(固定)
`-H`, `--host <host>`	待ち受けホスト	`127.0.0.1`
`--no-open`	ブラウザの自動起動を抑止	自動起動する

起動するとトークン付き URL(http://127.0.0.1:<port>/?token=…)を stdout に表示し、デフォルトブラウザで開く。Ctrl+C で終了。サーバーの機能・セキュリティモデル・HTTP API は localhost UI を参照。

--port / --host / --no-open は klaus.config.yaml で既定値を設定できる。詳細は CLI オプションの既定値を参照。

共有のマルチユーザーホストでは、このトークン付き URL がブラウザ起動コマンドの引数として渡るため、他のローカルユーザーからプロセス一覧経由で読める可能性がある。そうした環境では --no-open を指定し、表示された URL を自分で開くこと。

docker-compose での利用

コンテナ内で klaus ui を使う場合、ポートマッピングを固定するために既定ポート(4884)をそのまま使い、コンテナ外(ホスト側)から到達できるよう --host 0.0.0.0 を指定する。

yaml

services:
  klaus:
    image: your-klaus-image
    command: ["klaus", "ui", "--host", "0.0.0.0", "--no-open"]
    ports:
      - "4884:4884"

--host 0.0.0.0 を指定するとネットワーク内の他ホストからも接続できるようになる(表示される URL は開ける URL として 127.0.0.1 のまま示され、末尾に (listening on 0.0.0.0) の注記が付く)。トークン付き URL を知っていれば誰でも UI・API にアクセスできてしまうため、信頼できないネットワークに公開しない、URL を共有しない、など取り扱いに注意すること。

klaus validate

klaus validate [files...] [options]

フロー定義 YAML のスキーマ検証のみを行う(実行・ネットワークアクセスは一切しない)。環境ファイル(environments/*.yaml)は対象外。

オプション	説明	デフォルト
`--json`	TTY でも JSON 出力を強制	—

引数あり: 指定したファイルのみを検証する
引数なし: カレントディレクトリ以下を再帰探索し、フロー候補 YAML(最上位に steps キーを持つもの、klaus ui の GET /api/flows と同じ探索仕様・除外ディレクトリ)を検証する

出力モードは run と同じ判定(TTY なら text、非 TTY または --json なら JSON、結果は stdout・診断は stderr)。

text 出力

ファイルごとに OK(検証成功)または NG(検証失敗)を1行で表示し、NG の場合はエラー一覧を続けて表示する。エラーには主要なケース(method 不正・request/ws の排他や必須・body/graphql の排他・ws の URL スキーム不正・url 欠落・steps 空・step 名重複など)に限り、1行の修正例ヒントが付く。issue の位置が YAML ノードとして解決できた場合は、エラー行の末尾に (line N) が付加される(列番号はテキスト出力には含まれない)。

OK   flows/login.yaml
NG   flows/broken.yaml
  - steps.0.request.method (line 6): request.method is required unless request.graphql is set
    example: method: GET

JSON 出力

jsonc

{
  "version": 1,
  "files": [
    {
      "path": "flows/broken.yaml",
      "valid": false,
      "errors": [
        {
          "path": "steps.0.request.method",
          "message": "request.method is required unless request.graphql is set",
          "hint": "example: method: GET",
          "line": 6,
          "column": 7
        }
      ]
    }
  ]
}

errors[].path は zod issue の path をドット区切りにしたもの(YAML 構文エラーなど issue の位置を特定できない場合は空文字列)。hint は主要なケースにのみ付与される(undefined になりうる)。line / column は issue.path が指す YAML ノードの1始まり行・列番号で、ノードを解決できない場合は付与されない(undefined になりうる)。

exit code は全ファイル valid なら 0、1件でも YAML 構文エラー・スキーマ違反があれば 2。予期しない例外は run と同様 exit 1。

klaus schema

klaus schema [-t <target>]

オプション	説明	デフォルト
`-t`, `--target <target>`	出力するスキーマ。`flow`(フロー定義 YAML)、`run-report`(`run --json` の出力ペイロード)、`config`(klaus.config.yaml)	`flow`

JSON Schema(zod スキーマから生成、2スペース pretty print)を stdout に出力するだけで、ファイルへの書き出しはしない。

各スキーマは静的ファイルとしても公開されている: https://almondoo.github.io/klaus/schema/flow.schema.json / https://almondoo.github.io/klaus/schema/run-report.schema.json / https://almondoo.github.io/klaus/schema/klaus-config.schema.json。npm パッケージにも node_modules/@almondoo/klaus/dist/schema/*.json として同梱される。

run --json の version フィールドは package.json のバージョンとは独立した単なるリテラル値(現在は 2)。このスキーマの後方互換を壊す変更(フィールド削除・型変更・意味変更)をする場合のみ値を上げる(オプショナルフィールドの追加のような後方互換な変更では上げない)。利用側は現在の形が不変とは仮定せず、version を見て分岐すること。

request/ws の排他・どちらか必須、body/graphql の排他、graphql 無しの method 必須、ws.url のスキーム制約、step 名の一意性は zod の superRefine によるカスタムバリデーションであり JSON Schema では表現できないため、該当箇所の description に注記を付与する形で補っている。常に exit 0。

klaus init

klaus init

オプションはない。カレントディレクトリに最小構成を生成する。

生成されるファイル	内容
`api/example.yaml`	`https://example.com` への GET 1件、ステータス200のアサーション(英語コメント付き)
`environments/local.yaml`	`baseUrl` を持つ最小の環境ファイル
`AGENTS.md`	AI コーディングエージェント向けに、コマンド体系・YAML スキーマ要点・assert の運用指針・exit code 表・api/flows のディレクトリ規約を約50行に圧縮したガイド(英語)

既存ファイルは上書きせずスキップし、その旨を stdout に表示する。必要なディレクトリは自動で作成される。常に exit 0。1件以上生成した場合、最後に次のコマンドのヒントを表示する: klaus run api/example.yaml -e local

AGENTS.md には、エージェント実行環境向けの注意点として、klaus ui を安易に起動せずバックグラウンド実行+タイムアウト管理を行うべきこと、および OpenAI Codex CLI はサンドボックスのネットワークアクセスが既定で無効なため klaus run の HTTP リクエストが失敗する場合があること(~/.codex/config.toml の [sandbox_workspace_write] network_access = true で解除)も含まれる。

klaus history

ブラウザ UI を起動せずに実行履歴(.klaus/history/*.jsonl)を CLI から参照する。エージェントが巨大なレスポンスボディに汚染されずに履歴を読めるよう、デフォルトではフィールドを絞って出力する。ファイル規則・スキーマの詳細は実行履歴を参照。

一覧(klaus history)

klaus history [options]

オプション	説明	デフォルト
`--flow <name>`	フロー名で絞り込む(完全一致)	—
`--failed`	status が failed のエントリのみに絞り込む	—
`--last <n>`	取得件数	20
`--fields <csv>`	出力するフィールド(カンマ区切り)	`startedAt,runId,flow,step,status,durationMs`
`--json`	TTY でも JSON 出力を強制する	—

出力モードは klaus run と同じ TTY 判定規約: stdout が TTY なら簡潔なテキスト表(1行1エントリ)、非 TTY(パイプ / エージェント実行)または --json 指定時は compact な JSON 配列を出力する。--fields に request / response / assertions 等を明示指定すれば、デフォルトでは含まれないリクエスト/レスポンスボディも取得できる。

$ klaus history --last 5 --fields step,status,durationMs
step     status  durationMs
get-me   failed  3
login    passed  6

$ klaus history --json --failed
[{"startedAt":"2026-08-08T…","runId":"<uuid>","flow":"認証フロー","step":"get-me","status":"failed","durationMs":3}]

詳細表示(klaus history show)

klaus history show <runId> [--step <name>]

指定した runId に一致する履歴エントリを、保存されたままの形(シークレットはマスク済)ですべて JSON 出力する(TTY 判定はせず常に JSON)。--step を指定するとそのステップのみに絞り込む。該当エントリが無い場合は stderr にメッセージを出して exit 1。

$ klaus history show 3fa1c2e0-... --step get-me
[{"v":1,"runId":"3fa1c2e0-...","flow":"認証フロー","step":"get-me","status":"failed", …}]

klaus history の一覧出力に含まれる runId / step を使って、詳細が必要なエントリだけをこのコマンドで掘り下げる、という使い方を想定している。

CLI リファレンス ​

--help ​

klaus run ​

タグによるフロー選択(--tags / --exclude-tags) ​

データ駆動実行(--data) ​

並列実行(--jobs) ​

出力モード ​

text 出力(人間向け) ​

JSON 出力(機械向け) ​

JUnit レポート ​

TAP レポート ​

exit code ​

klaus ui ​

docker-compose での利用 ​

klaus validate ​

text 出力 ​

JSON 出力 ​

klaus schema ​

klaus init ​

klaus history ​

一覧(klaus history) ​

詳細表示(klaus history show) ​