finalrun-use-cli

FinalRun CLI ガイドとオペレーター

.finalrun/ を含むリポジトリ内で、公開されている finalrun CLI を安全に使用できるよう、リポジトリのユーザーを支援します。ユーザーからコントリビューター向けのセットアップを明示的に求められない限り、モノレポのコントリビューターワークフローではなく、アプリのリポジトリで公開済み CLI を使用する方法を優先してください。

前提条件

公開パッケージをインストールし、CLI を利用できることを確認します。

npm install -g @finalrun/finalrun-agent
finalrun --help

Android または iOS をローカルで実行する場合は、ホストの準備状況を診断する最初の手順として finalrun doctor を使用してください。

finalrun doctor

信頼できる情報源

• finalrun --help、finalrun test --help、finalrun suite --help など、ローカル CLI のヘルプを優先してください。
• 実行方法を案内する前に、.finalrun/ 内の実際のワークスペースファイルを確認してください。
• リポジトリ内で確認できる内容を質問する前に、.finalrun/config.yaml、.finalrun/env/、.finalrun/tests/、.finalrun/suites/ を確認してください。
• finalrun init など、サポートされていないコマンドを作り出さないでください。

基本的なワークフロー

1. ワークスペースを確認し、コマンドの実行が必要な場合は finalrun が PATH 上で利用できることを確認します。
2. finalrun check で最初に検証します。これにより、実行結果をユーザーが信頼する前に、セレクター、スイート、設定、環境バインディング、アプリのオーバーライドが検証されます。
3. 使用する予定の正確な finalrun test または finalrun suite コマンドを説明します。該当する場合は、選択した --env、--platform、--model も含めてください。
4. 検証の失敗はブロッカーとして扱います。CLI エラーを平易な言葉で説明し、テストが実行されたかのように装わないでください。
5. 検証または実行の後、finalrun runs を使って最近の実行アーティファクトを確認します。
6. finalrun start-server はバックグラウンドで UI の動作を開始するため、実行前にユーザーへ確認してください。
7. ユーザーが YAML テスト、スイート、または環境バインディングの作成や編集を希望する場合は、その作業を finalrun-generate-test に案内してください。

ワークスペースが見つからない場合

.finalrun/ がない場合：

• FinalRun は .finalrun/ を含むリポジトリから実行する必要があることを説明します。
• 必ず必要なのは .finalrun/tests のみであり、suites/ が必要なのはスイートを使うワークフローに限られることを明確にします。
• 想定される構造を示します。
• スキャフォールドの計画を提案するか、ユーザーを finalrun-generate-test に案内します。
• CLI がワークスペースを自動的にブートストラップできるとは主張しないでください。

想定される構造：

.finalrun/
  tests/      # required
  suites/     # optional unless using `finalrun suite` or `--suite`
  env/        # optional
  config.yaml # optional

検証とエラー処理

• finalrun check はデフォルトの検証コマンドです。
• テスト実行の結果を信頼する前に、必ず検証してください。
• finalrun test と finalrun suite は、検証に合格した場合のみ実行されます。CLI は実行開始前にセレクター、スイート、設定、環境変数のバインディング、アプリのオーバーライドを検証します。
• finalrun test または finalrun suite が検証中に失敗した場合は、CLI エラーを分かりやすくそのまま伝え、意味を説明し、実行されたかのように説明しないでください。
• セレクター、スイート、設定、環境変数、バインディングの問題は、まず CLI の出力から診断してください。推測してはいけません。

シークレットと認証情報のエラーには、明示的なユーザー操作が必要です。

• .finalrun/env/<env>.yaml が存在しない、形式が不正、または参照されているバインディングが不足している場合は、該当するファイルやバインディングの問題を正確に説明し、環境ファイルを修正するか、正しい --env を選ぶようユーザーに伝えてください。
• シークレットのプレースホルダーの形式が不正な場合は、FinalRun で正確な ${ENV_VAR} 形式が必要であることを説明してください。
• シークレットが存在しないシェル環境変数を参照している場合は、不足している変数名を示し、検証または実行が成功する前にユーザーがその変数をエクスポートするか設定する必要があると伝えてください。
• 仕様が不明な ${secrets.*} または ${variables.*} バインディングを参照している場合は、解決できないバインディング名を示し、環境ファイルで宣言する必要があると伝えてください。
• プロバイダーの API キーが不足している場合は、現在のモデルで必要な変数名（OPENAI_API_KEY、GOOGLE_API_KEY、または ANTHROPIC_API_KEY）を正確に伝えてください。デフォルトモデルが設定されていない場合は、繰り返し使うための設定として、.finalrun/config.yaml に model: google/gemini-3-flash-preview を追加し、~/.zshrc に export GOOGLE_API_KEY=<your-key> を追加し、source ~/.zshrc でシェルを再読み込みしてから再実行するよう勧めてください。--api-key に言及するのは、ユーザーが一度限りの実行を希望した場合に限ります。
• シークレットの値を捏造、推測、記述したり、ユーザーに知らせずに代用したりしてはいけません。

安全ポリシー

ユーザーから依頼された場合、追加の承認なしで安全に実行できます。

• finalrun check
• finalrun doctor
• finalrun runs

実行前に確認してください。

• finalrun test
• finalrun suite
• finalrun start-server

事前に確認する理由：

• テストの実行には時間がかかり、プロバイダーのクレジットを消費する場合があります。
• サーバーコマンドはバックグラウンドプロセスを起動し、ブラウザーを開く場合があります。

実行後

finalrun test または finalrun suite の完了後、CLI は構造化された概要を出力します。エージェントの応答は結果によって異なります。

成功時

CLI はアーティファクトのディレクトリとレポート URL を含む短い確認メッセージを出力します。エージェントは次のように対応してください。

• 成功したことを分かりやすく伝えます。
• ユーザーが実行結果を確認できるよう、レポート URL を記載します。
• そこで終了します。追加の実行、スイートへの拡張、追加のチェックを提案してはいけません。

失敗時

CLI は失敗の概要を出力し、失敗した各テストとそのアーティファクトへのパスを示します。エージェントは次の手順に従ってください。

1. 失敗の出力を読み、どのテストがなぜ失敗したかを特定します。
2. 失敗したテストごとに、CLI が示したアーティファクトファイルを読み、ユーザーに伝える情報をまとめます。
   • result.json — テスト結果、失敗メッセージ、ステップごとの結果。
   • actions/ — 各ステップでエージェントが試みた内容を示す個別のエージェントアクションファイル（JSON）。推論、実行したアクション、成功したかどうかが含まれます。
   • screenshots/ — 各アクション時点のデバイス画面を示す、ステップごとのスクリーンショット。
   • recording.mp4 または recording.mov — テスト全体の画面録画（存在する場合）。
   • device.log — テスト中に取得されたデバイスレベルのログ（Android では logcat、iOS では log stream）（存在する場合）。
   • runner.log — 実行全体を記録した CLI 独自のログ（実行ディレクトリのルートにあります）。
3. 失敗について、テストで何を実行しようとしていたか、どこで失敗したか、その時点でデバイス画面に何が表示されていたかを、分かりやすく要約します。
4. 具体的な次の手順を提案します。テスト仕様の更新が必要か、アプリにバグがあるか、環境設定に問題があったかを示します。

アーティファクトファイルを探すようユーザーに依頼してはいけません。 CLI が完全なパスを出力するため、そのファイルを直接読み、調査結果を伝えてください。

コマンドリファレンス

検証

• finalrun check [selectors...]
  • .finalrun ワークスペース、セレクター、スイートマニフェスト、環境変数のバインド、アプリのオーバーライドを検証します
  • --env、--platform、--app、--suite に対応しています
  • --env が省略された場合は、.finalrun/config.yaml の env を使用します

実行

• finalrun test [selectors...]
  • .finalrun/tests の 1 つ以上の仕様を実行します
  • --env、--platform、--app、--suite、--api-key、--model、--debug、--max-iterations に対応しています
  • これらのフラグが省略された場合は、.finalrun/config.yaml の env と model を使用します
  • 実行開始前に検証します
• finalrun suite <suitePath>
  • .finalrun/suites のスイートマニフェストを 1 つ実行します
  • --env、--platform、--app、--api-key、--model、--debug、--max-iterations に対応しています
  • これらのフラグが省略された場合は、.finalrun/config.yaml の env と model を使用します
  • 実行開始前に検証します

診断

• finalrun doctor
  • ローカルの Android および iOS ホストの準備状況を確認します
  • --platform に対応しています

レポート

• finalrun runs
  • 現在のワークスペースのローカル実行アーティファクトを一覧表示します
  • --json に対応しています
• finalrun start-server
  • 現在のワークスペースのローカルレポート UI を起動するか、既存のものを再利用します
  • --port と --dev に対応しています

明示的に指定した CLI フラグは、.finalrun/config.yaml のデフォルト値より優先されます。

共通 CLI フラグ

• --env <name>
  • check、test、suite で使用します
  • .finalrun/env/<name>.yaml を選択します
• --platform <android|ios>
  • check、test、suite、doctor で使用します
  • コンテキストまたはアプリのオーバーライドからプラットフォームを推定できない場合に必須です
• --app <path>
  • check、test、suite で使用します
  • .apk は Android、.app は iOS を示します
• --model <provider/model>
  • test と suite で使用します
  • .finalrun/config.yaml ですでに model が定義されていない場合は必須です
• --api-key <key>
  • test と suite で使用します
  • プロバイダー固有の環境変数をオーバーライドします
• --debug
  • test と suite で使用します
  • デバッグログを有効にします
• --max-iterations <n>
  • test と suite で使用します
  • 実行が中止されるまでの反復回数を制限します
• --suite <path>
  • check と test で使用します
  • test では互換性のための指定方法です。finalrun suite <path> の使用を推奨します
• --port <n>
  • start-server で使用します
• --dev
  • start-server で使用します
  • レポート UI を開発モードで実行します

対応プロバイダーとモデル

• 対応プロバイダーは openai、google、anthropic です。
• GPT-5 ファミリー以降の openai/... モデルを使用してください。
• Gemini 3 ファミリー以降の google/... モデルを使用してください。
• Claude Sonnet 4／Opus 4 ファミリー以降の anthropic/... モデルを使用してください。
• サンプルの実行コマンドを使用する前に、finalrun test --help で正確な provider/model の値を確認してください。

一般的なワークフロー

既存のワークスペースを検証します。

finalrun check --env dev

検証後、仕様を 1 つ実行します。

finalrun check auth/login.yaml --env dev --platform android
finalrun test auth/login.yaml --env dev --platform android --model google/gemini-3-flash-preview

検証後、スイートを 1 つ実行します。

finalrun check --suite smoke.yaml --env dev --platform ios
finalrun suite smoke.yaml --env dev --platform ios --model anthropic/claude-3-7-sonnet

最近の実行を確認します。

finalrun runs

レポート UI を開きます。

finalrun start-server

現在のコマンドとモデルのヘルプを確認します。

finalrun --help
finalrun test --help
finalrun suite --help

トラブルシューティング

まず実際の CLI 出力を基に診断してください。推測はしないでください。

• .finalrun/ がない
  • FinalRun は .finalrun/ を含むリポジトリから実行する必要があることを説明してください
• .finalrun/tests/ がない
  • このディレクトリは CLI に必要であることを説明してください
• env ファイルがない、または複数ある
  • .finalrun/env/ が存在するか確認してください
  • env ファイルが複数あり、どれを使うか判別できない場合は、ユーザーに --env <name> を明示的に指定するよう伝えてください
• 不明な env バインディング
  • 解決されていない ${variables.*} または ${secrets.*} バインディングを説明してください
  • env ファイルでそれらを宣言する必要があることをユーザーに伝えてください
• シークレットがない、または形式が不正
  • プレースホルダーは正確に ${ENV_VAR} の形式を使用する必要があります
  • 検証または実行の前に、不足しているシェル環境変数をユーザーがエクスポートする必要があります
  • シークレットの値を記述したり推測したりしないでください
• プロバイダーの API キーがない
  • openai/... では OPENAI_API_KEY を使用します
  • google/... では GOOGLE_API_KEY を使用します
  • anthropic/... では ANTHROPIC_API_KEY を使用します
  • デフォルトモデルが設定されていない場合は、.finalrun/config.yaml に model: google/gemini-3-flash-preview を設定することを推奨してください
  • デフォルトのセットアップ手順では、~/.zshrc に export GOOGLE_API_KEY=<your-key> を設定することを推奨してください
  • source ~/.zshrc でシェルを再読み込みし、再実行するようユーザーに伝えてください
  • 1 回限りの実行を希望する場合に限り、--api-key に言及してください
• .finalrun/config.yaml が無効
  • YAML または設定のエラーを直接示してください
• セレクターやテストスイートの解決に失敗する
  • finalrun test auth/login.yaml は .finalrun/tests/auth/login.yaml から解決されます
  • finalrun suite smoke.yaml は .finalrun/suites/smoke.yaml から解決されます
  • .finalrun/tests/... と .finalrun/suites/... を明示したパスも引き続き使用できます
• アプリのオーバーライドとプラットフォームの不一致
  • .apk のオーバーライドには Android が必要です
  • .app のオーバーライドには iOS が必要です
  • 無視するのではなく、パスまたは --platform の不一致を修正するようユーザーに伝えてください
• ホストの準備状況に関する問題
  • ローカル環境の診断には、デフォルトで finalrun doctor を使用してください

finalrun-generate-test との連携

このスキルは、CLI の使用、検証、実行、レポート作成、トラブルシューティングを対象とします。

ユーザーから次の依頼があった場合：

• 新しい YAML テストを作成する
• テストスイートのマニフェストを更新する
• .finalrun/env/*.yaml のバインディングを追加または変更する
• 新しいテストフローを計画する

その作業は finalrun-generate-test に振り分けてください。

このスキルでは、CLI がこれらのファイルをどこに想定しているか、またセレクターがどのように解決されるかを説明してもかまいませんが、YAML 作成のワークフローを重複して説明しないでください。