ドキュメントメニュー
マネージドランナー
ワークフローファイル
CLI から単発のジョブを実行する
ターミナルやコーディングエージェントから、任意のコマンドを新しい Latchkey ランナーで実行します。CLI が作業ツリーをパックし、ログをストリーミングで返し、コマンド自身の終了コードで終了します。
要点
npm install -g @latchkeydev/cliの後、latchkey run 'npm ci && npm test'がコマンドを新しい Latchkey ランナーで実行し、コマンド自身の終了コードで終了します。- 作業ツリーはジョブと一緒に送られます:
.gitignoreのルールが適用され、--excludeでさらに除外でき、クレデンシャルの形をしたファイルはデフォルトで除外され、.latchkeyignoreがその 3 つすべてを上書きします。 - ジョブは通常のランナー分数として、同じ無料分プールから課金されます。その支出はCost ページに独自の CLI jobs 行として表示されます。
- ジョブを実行できる API キーが必要です。オーナーまたは管理者が Settings, API keys and agents でキーを作成し、Access で CLI runner を選びます。コーディングエージェントは MCP の
run_jobツールを通じて同じサーフェスにアクセスします。
Latchkey CLI (@latchkeydev/cli) は、新しい CI マシンを、ローカルコマンドのように呼び出せるものに変えます。 latchkey run 'npm ci && npm test' は作業ツリーをパックし、隔離された Latchkey ランナーでコマンドを実行し、出力をターミナルにストリーミングし、コマンド自身の終了コードで終了します。アップロードには .gitignore で無視されるもの (node_modules など) が含まれないため、コマンドは最初に依存関係をインストールします。これにより、スクリプト化できる検証ループになります: プッシュする前に、CI が実行するのと同じやり方で、クリーンな Linux マシン上でチェックを実行できます。プッシュ前の検証、CI でのみ発生する失敗の再現 (クリーンなワークスペース、新規インストール、Linux)、そして他のシェルコマンドと同じようにこれを操作するコーディングエージェントのために作られています。
~/acme-api のターミナルで latchkey run 'npm test' を実行すると、Packing context from /Users/me/acme-api...、Packed 412 file(s), 3.1 MB compressed.、Created job cli-6f0e8a3c-6a3e-4a7e-9d5f-0f1c2b3a4d5e.、ダッシュボードのジョブへのリンク、Uploading context (3.1 MB)...、Context uploaded.、Submitted; state: queued.、続いて state: provisioning が表示されます。ジョブのログがストリームで返り、ジョブエージェントの [latchkey] 行が 2 行、state: running、そして 412 件のテスト成功で終わる npm test の出力が続きます。最後に state: succeeded と Job cli-6f0e8a3c-6a3e-4a7e-9d5f-0f1c2b3a4d5e succeeded (exit 0). が表示されます。
latchkey run 'npm test' は作業ツリーをまとめ、新しいランナーでジョブを開始し、そのログをストリームで返します。CLI 自身の進捗 (ここでは薄く表示) は stderr に、ジョブの出力は stdout に出力され、コマンドはジョブの終了コードで終了します。インストールと認証#
npm でグローバルにインストールするか (Node 20.18.1 以降)、npx @latchkeydev/cli でアドホックに実行します。スコープ付きのパッケージ名をインストールしてください: npm 上のスコープなしの latchkey パッケージは無関係のプロジェクトです。
オーナーまたは管理者が Settings, API keys and agents でキーを作成し、Access で CLI runner を選びます。権限は作成時に固定されます: 既存のキーが遡って権限を得ることはありません。完全なキー (lk_live_ で始まります) は一度だけ表示されます。
latchkey login は課金対象のものを何も起動せずにキーを検証し、このマシン用に保存します (~/)。CI やエージェントループでは、保存された設定を使わず、代わりに環境変数 LATCHKEY_TOKEN を設定してください。
~/acme-api のターミナルで latchkey login を実行すると Latchkey API key (input hidden): と入力を求め、キーを貼り付けても何も表示されません。続いて Logged in. Key lk_live_…a1b2 saved to /Users/me/.config/latchkey/config.json. と表示し、終了コード 0 で終了します。
latchkey login はキーを保存する前に検証し、貼り付けている間キーは一切表示されません。確認の行に表示されるのは、キーの先頭 8 文字と末尾 4 文字だけです。ジョブを実行する#
すべての実行は同じ 5 つのことを行います: 現在のディレクトリをコンテキストアーカイブにパックし、アップロードし、新しいランナーでコマンドを実行し、ログをライブでストリーミングして返し、コマンド自身の終了コードで終了します。キャンセルされたジョブは 130 で終了し、開始前に Latchkey が期限切れにしたジョブは 124 で終了し、--timeout で停止されたコマンドは timeout_exceeded で失敗として終わって 1 で終了するため、スクリプトやエージェントはログテキストを 1 行も解析せずに結果で分岐できます。
複数の手順からなるチェックは引用符で囲んだ 1 つの引数として渡し、必要ならその中でディレクトリを移動します。ランナーはその行を -e と -o pipefail 付きの bash で実行するため、最初に失敗したコマンドで止まります。先頭の bash -c や sh -c を別々の単語として入力すると、そのシェルはスクリプトの最初の単語しか実行しないため、CLI は何かをパックしたり送信したりする前に終了コード 2 でそれを拒否し、代わりに実行する行を表示します。その行はシェルを 1 つの引数の中に残し、シェルを外すのは -e と -o pipefail 付きの bash だったときだけです。引用符で囲んだ 1 つの引数の中の bash -c や、latchkey run bash ci.sh は、書いたとおりに実行されます。
latchkey run 'npm run e2e' はジョブのログをストリーミングし、Ctrl-C が押されるまで続けます。CLI は job still running: latchkey cancel cli-8c41a0f2-7d3e-4b9a-a5c6-1e2f3d4b5c6a | latchkey logs cli-8c41a0f2-7d3e-4b9a-a5c6-1e2f3d4b5c6a --follow と表示し、シェルは終了コード 130 を返しますが、ジョブはランナー上で動き続けます。続いてジョブ ID を指定した latchkey cancel が Cancellation requested; the runner honors it within about 10 seconds (current state: running). と表示します。
latchkey cancel を実行するとランナー上のジョブは約 10 秒以内に止まります。~/acme-api のターミナルで、latchkey run --timeout 120 'npm run e2e' が Packing context from /Users/me/acme-api...、Packed 412 file(s), 3.1 MB compressed.、Created job cli-5d9e2c71-4b8a-4f06-9e3d-a1c7b2f4e860.、ダッシュボードのジョブへのリンク、Uploading context (3.1 MB)...、Context uploaded.、Submitted; state: queued. を表示します。ジョブのログがストリームで返ってきます。ジョブエージェントの [latchkey] の行、state: running、Playwright を起動する e2e スクリプトと Running 86 tests using 4 workers、そして成功したテストごとに 1 つずつ並ぶドットの行です。コマンドの開始から 2 分後、ログに [latchkey] job timed out after 120s が出ます。続いて CLI が state: failed と Job cli-5d9e2c71-4b8a-4f06-9e3d-a1c7b2f4e860 failed. The job reported: timeout_exceeded を表示し、終了コード 1 で終了します。
スイートを複数のランナーに分割する#
長いスイートは、シャードごとに 1 つのジョブにすると早く終わります。新しいバッチの予算を設定し、テストランナー自身の分割フラグをパッケージ自身の test スクリプトを通して渡して、シャードごとにジョブを 1 つずつ --detach で開始し、それから各ジョブを追ってその判定を得ます。スクリプトを通すと、パッケージの pretest のステップ (テストの型チェックなど) が CI と同じようにすべてのシャードで実行されます。テストランナーを直接呼び出すと、これらのステップは飛ばされます。このブロックは、シャードが 1 つでも拒否されるとそれ以降のシャードを開始せず、開始できなかったシャードか失敗したシャードがあれば 0 以外の終了コードで終わります:
batch="suite-$(date +%Y%m%d%H%M%S)" failed=0 ids=() latchkey budget set "$batch" 4 || failed=1 for shard in 1 2 3 4; do [ "$failed" -eq 0 ] || break id=$(latchkey run --batch "$batch" --size large --detach "npm ci && npm test -- --shard=$shard/4") || true if [ -n "$id" ]; then ids+=("$id"); else echo "shard $shard not started"; failed=1; fi done for id in "${ids[@]}"; do code=0 latchkey logs "$id" --follow > "$id.log" || code=$? echo "$id exited $code" [ "$code" -eq 0 ] || failed=1 done [ "$failed" -eq 0 ]
各シャードは自分のインストールの費用を払い、シャードごとに分単位で切り上げて課金されます。また、各シャードはワークスペースの同時実行ジョブ数の上限にも数えられ、この上限はワークスペースのすべてのエージェントとワークフローの実行が共有しています。余分なインストールを取り戻せるほど長いスイートだけを分割し、一度に始めるジョブは上限を十分に下回るようにしてください。ワークフローファイル は matrix で同じように分割します。
コマンド一覧#
| コマンド | 何をするか |
|---|---|
latchkey login | API キーを検証し、このマシン用に保存する |
latchkey run | 現在のディレクトリをパックし、新しいランナーでコマンドを実行し、ログをストリーミングし、コマンドの終了コードで終了する |
latchkey list | 最近のジョブを、まだ実行中のものも含めて新しい順に一覧表示する |
latchkey logs | ジョブのログを出力するか、--follow で完了までテールする |
latchkey status | ジョブの状態、ランナーサイズ、タイミング、終了コードを表示する |
latchkey cancel | キャンセルをリクエストする。実行中のジョブは約 10 秒以内に停止する |
latchkey budget | バッチの最初の予算 (米ドル) と同時に実行されるジョブの最初の上限を設定するか、引き下げるか、支出とともに表示する。API キーではどちらも引き上げることはできない |
latchkey batch | 1 つのバッチの予算、支出、状態ごとのジョブ数、ジョブを表示する |
latchkey wait | ジョブまたはバッチの終了を待ち、それぞれの結果をまとめて表示する |
latchkey watch | 自己修復が記録したものの修正しなかった CI の失敗をポーリングし、ジョブ (Latchkey on GH では実行) ごとに最初の新しい失敗をコーディングエージェントに引き渡す |
latchkey cache | ジョブの中からキャッシュエントリを復元または保存し、依存関係のディレクトリを次のジョブへ引き継ぐ |
latchkey artifact | Latchkey CI の実行のジョブの中でアーティファクトをアップロードまたはダウンロードし、その実行のジョブ間でファイルを渡す |
latchkey oidc | Latchkey CI の実行のジョブの中で短期間有効な ID トークンを取得し、保存したキーなしでジョブが クラウドにサインイン できるようにする |
latchkey secrets | ワークフローファイル のステップが読み取るシークレットを、ワークスペース全体または 1 つのリポジトリに設定する |
latchkey migrate | リポジトリの GitHub Actions から Latchkey CI への移行を計画し、そのためのプルリクエストを開く (開くには Allow opening migration pull requests を有効にして作成したキーが必要) |
latchkey steps | ワークフローファイルで指定できる Latchkey のステップ を、それぞれ最新バージョンの入力とそのルールとともに一覧表示する |
latchkey validate | 変更したワークフローファイルを、実行を開始せずに確認する。最初の拒否か、そのジョブと 1 回の実行にかかりうる最大のコストを示す |
latchkey preflight | 1 つのワークフローファイルを、Latchkey がコンパイルするとおりに、コミットやプッシュの前に作業ツリーで実行する (Latchkey CI に接続されたリポジトリが必要) |
latchkey workflows | 手動実行を受け付ける ワークフローファイル の実行を、ブランチまたはタグで入力とともに手動で開始する (Allow starting Latchkey CI workflows を有効にして作成したキーが必要) |
実際に使うことになる run のフラグ: --size はランナーを選択します (small がデフォルト。medium、large、xlarge はワークフローで使う ランナーサイズ に対応します)。--env KEY=VALUE はシークレットや設定をファイルとして送らずに渡します。--timeout は 30 秒から 3 時間まで受け付けます (ジョブのデフォルトは 30 分)。--detach はジョブを送信して終了するため、後からテールできます。--no-context は何もアップロードせず、空のワークスペースでコマンドを実行します。--batch <name> は、ジョブを、/ と % を含まず、. または .. だけでもない 1 文字から 64 文字までの名前を持つバッチに入れます (シェルのすべてのジョブに適用するには LATCHKEY_BATCH を一度設定します)。これで、1 つの作業のジョブと支出をまとめて読めます。すべてのリモートコマンドは機械可読な出力のための --output json を受け付け、パッケージには、コーディングエージェントが完全な契約を読み取れる独自の詳細リファレンス (SKILL.md) が同梱されています。
各リリースで追加、変更、修正された内容は、Latchkey CLI の変更履歴 にあります。
latchkey run --detach 'npm ci && npm test' は通常の実行と同じ進捗行を出しながら作業ツリーをまとめてアップロードし、ジョブ ID cli-2b9d4e71-0c5a-4f3e-8a6d-7e1f9c3b5a20 を表示してすぐに戻ります。その ID を指定した latchkey status はジョブの各行を表示します。State running、Runner size small、Rate $0.0025 a minute、Cost so far $0.0025 at list rate, before free minutes、Timeout 1800s、Cancel requested no、まだ値のない Exit code と Failure reason、そして Created、Submitted、Started の時刻です。その ID と --follow を指定した latchkey logs は、ジョブのログを最初からテスト結果まで表示し、最後に state: succeeded と Job cli-2b9d4e71-0c5a-4f3e-8a6d-7e1f9c3b5a20 succeeded (exit 0). を表示します。
--detach はストリーミングせず、すぐにジョブ ID を返します。latchkey status でジョブの状態を読み、latchkey logs --follow でログを最初から追跡すると、ジョブの終了コードで終了します。~/acme-api のターミナルで latchkey list --limit 5 を実行すると、ワークスペースの新しい 5 件のジョブが、JOB、STATUS、SIZE、BATCH、KEY、DURATION、COST、COMMAND、QUEUED の列を持つ表で表示されます。最も新しい cli-4e7a9c21-8b3d-4f6e-a1c5-9d2b7e0f3a64 は、バッチ refactor-auth の medium で running の状態にあり、キー claude-code で開始されたもので、コマンドは npm run、所要時間はハイフン、ここまでのコストは 0.5 セントと表示されます。次の 2 件は同じバッチの small で npm test を実行したもので、1 件は 1m52s で success となり 0.5 セント、もう 1 件は 2m07s で failure (1) となり 0.75 セントです。最後の 2 件はキー laptop からバッチなしで実行されたもので、large の npm run が 6m31s で success となり 7 セント、small の npm ci が 48s で success となり 0.25 セントです。各行の末尾は、そのジョブがキューに入った時刻で、2026-10-15T10:42:18.604Z から 2026-10-15T09:47:12.773Z までさかのぼります。
latchkey list ですぐに見つかります。実行中のジョブも一覧に含まれ、終了するまで所要時間は表示されません。失敗したジョブはステータスの横に終了コードが付き、コマンド列にはプログラムと最初のサブコマンドだけが表示されるため、コマンドラインのトークンが表示されることはありません。~/acme-api のターミナルで cat ci/deps.sh を実行すると、5 行のスクリプトが表示されます: set -e、npm install -g @latchkeydev/cli、latchkey cache restore --key npm-cache --version v1、npm ci --cache .npm-cache、latchkey cache save --key npm-cache --version v1 .npm-cache。latchkey run --quiet 'bash ci/deps.sh' は新しいジョブの ID cli-0d4f7b2e-6c1a-4e95-a8b3-f2e7c9d1a046 とダッシュボードのジョブへのリンクを表示し、続いてジョブのログを表示します: ジョブエージェントの [latchkey] 行、added 9 packages in 2s、cache miss: npm-cache (version v1)、added 1291 packages in 41s、cache saved: npm-cache (61834215 bytes)。同じコマンドをもう一度実行すると cli-8f3a6e19-b2d7-4c40-9e5f-1a7c0b4d2e83 が開始され、そのログは added 9 packages in 2s、cache restored: npm-cache (61834215 bytes)、added 1291 packages in 9s、cache entry already exists: npm-cache was not overwritten となります。どちらの実行も終了コード 0 で終了します。
latchkey cache はジョブの中で実行されるため、ジョブはまず CLI をインストールします。最初の実行ではキャッシュが見つからず、npm のキャッシュを保存します。次の実行では npm ci の前にそれを復元し、その保存ではエントリをそのまま残します。エントリのあるキーが上書きされることはないためです。キャッシュが見つからないときは、キャッシュプロキシのエラーと同じく終了コード 0 になるため、空のキャッシュや使えないキャッシュがジョブを失敗させることはありません。--quiet を付けると、CLI 自身の出力はジョブ ID とそのリンクだけになります。latchkey artifact もジョブの中で動きますが、ワークフローファイル の実行のジョブの中だけです: upload --name <name> <path...> はパスを 1 つのアーティファクトにまとめ、download --name <name> はこのジョブが必要とするジョブがアップロードしたものを取得します。アップロードでは、.git や .env のように名前がドットで始まるファイルとディレクトリは、--include-hidden-files を指定しない限り含まれません。そのフラグなしでそれらを指定したアップロードと、パスの下に通常のファイルが 1 つもないアップロードは失敗します。latchkey cache と違い、アップロードやダウンロードが失敗すると終了コード 1 で終わり、ステップが失敗します。プリフライトのジョブはアーティファクトをアップロードもダウンロードもできません: ストアはそのジョブの呼び出しをすべて拒否し、コマンドは終了コード 199 で終わります。プリフライトはジョブの最初に失敗したステップでこのコードを読み取り、そのジョブを失敗ではなく実行されなかったものとして報告します。名前、上限、アーティファクトの保持期間のルールはワークフローファイルのページにあります。
~/acme-api のターミナルで latchkey secrets set NPM_TOKEN を実行すると Secret value (input hidden): と入力を求め、値を入力している間は何も表示されません。続いて Set NPM_TOKEN for the workspace (version 1). と表示します。次に echo "$DATABASE_URL" の出力を latchkey secrets set DATABASE_URL --repository acme/api にパイプすると、パイプから値を読み取り、Set DATABASE_URL for acme/api (version 2). と表示します。どちらのコマンドも終了コード 0 で終了します。
latchkey secrets set は、ワークフローファイルのステップが ${{ secrets.NAME }} として読み取るシークレットを、ワークスペース全体に、または --repository を付けて 1 つのリポジトリに保存します。値は非表示のプロンプトかパイプから読み取られ、コマンドラインから受け取ることはなく、表示されることもありません。同じ名前をもう一度設定すると、新しいバージョンが保存されます。Allow setting workspace secrets を有効にして作成したキーが必要です。CLI ジョブは、代わりに --env でシークレットを受け取ります。ジョブと一緒に送られるもの#
latchkey run は実行したディレクトリをパッケージ化します。それを囲むリポジトリは決して対象になりません。そのため、サブディレクトリから実行するとそのサブディレクトリだけが送られ、--context <dir> を指定すると別のディレクトリを対象にできます。コマンドはアップロードされたツリーのルートで実行されるため、--context が指定したディレクトリがランナー上のワークスペースルートになります。--context と --exclude はコマンドより前でのみ読み取られるため、コマンド自身のフラグはそのまま渡されます。何が含まれるかは 4 つのルールが決め、最後に意見を表明したルールが勝ちます:
- パッケージ化されるツリー内のすべての
.gitignoreは追跡されていないファイルに適用されるため、ignore された依存関係のインストール物やビルド出力は手元に残り、ジョブは CI と同じようにゼロからインストールします。対象になるのはツリー内にある ignore ファイルだけです: サブディレクトリから実行すると、リポジトリルートの.gitignoreは適用されなくなります (パッケージ化のルートに.latchkeyignoreを置くのが解決策です)。 --exclude <pattern>はコマンドラインから直接さらに除外します。gitignore 構文で、フラグ 1 つにつきパターンを 1 つ指定します。否定は使えません: 先頭の!は使用方法エラーになります。--excludeはより多くを除外できるだけで、除外されたものを再び含めることはできないからです。- クレデンシャルの形をしたファイル (
.envファイル、秘密鍵、クラウドのクレデンシャルファイル) は組み込みの拒否リストによって除外され、除外はすべて出力に表示されます。--excludeのどのパターンも、クレデンシャルの拒否リストが除外したファイルを送ることはできず、拒否リストが除外したファイルはすべて報告されます。.gitignoreがそれらを再び含めることも決してできません。 .latchkeyignoreファイル (同じ構文) はその 3 つすべてより優先されます: さらに除外するためにも、拒否リストが除外したものを意図的に再び含めるためにも使えます。後者の場合は、ファイル名を明示した目立つ警告が表示されます。それができる唯一のルールソースです。リポジトリの所有者自身のファイルだからです。- 1 つのリポジトリの 2 つのパッケージを必要とするジョブは、両方を含むディレクトリをパックし、その 1 つのコマンドの中でディレクトリを移動します (
cd shared && npm ci && cd ../web && npm ci && npm test)。1 つのパッケージのディレクトリだけをパックすると、隣のパッケージは手元に残ります。 - ジョブはクリーンなランナーで実行されるため、すべてのコマンドはインストールから始まります。
node_modulesを対象にする ignore ルールがなければ、それは送られ、何の得にもならないのにアップロードの時間がかかります: 末尾にスラッシュを付けないnode_modulesの 1 行を.latchkeyignoreに書いて、手元に残してください。 .gitignoreのパターンに一致するのにgit add -fでコミットされたファイルは送られます。パックは git が追跡しているファイルを含めるからです。テストが読む設定ファイルのうち、クレデンシャルのパターンに一致するコミット済みのものは、引き続き手元に残ります (*.config.tfvarsは*.tfvarsに一致します): シークレットを含まないなら、.latchkeyignoreの!行で戻してください。
!test/fixtures/**/*.txt !terraform/*.config.tfvars
クレデンシャルの拒否リスト: 39 パターン
- .env112 B除外
- .env.example98 B含まれる
- .git/除外
- .gitignore37 B含まれる
- .latchkeyignore34 B含まれる
- .npmrc52 B除外
- README.md1.8 KB含まれる
- data/除外
- seed.sql1.4 GB除外
- dist/除外
- server.js612 KB除外
- node_modules/除外
- 2,315 フォルダ内の 18,240 ファイル212 MB
- npm-debug.log9.6 KB除外
- package-lock.json186 KB含まれる
- package.json1.2 KB含まれる
- src/含まれる
- routes.ts4.1 KB含まれる
- server.ts2.3 KB含まれる
- test/含まれる
- api.test.ts5.4 KB含まれる
- fixtures/含まれる
- tls.key1.7 KB除外
.npmrc によって、.gitignore の内容にかかわらず除外されます。latchkey run はそれを名指しで表示し、戻せるのは .latchkeyignore の ! 行だけです。制限#
| 制限 | 値 |
|---|---|
| コマンドライン | 16,384 文字 |
| 環境変数 | ジョブあたり 64 個 |
| ジョブのタイムアウト | 30 秒から 3 時間、デフォルトは 30 分 |
| ジョブの予算 | デフォルトではなし。--budget または budget_usd を指定すると、ジョブは、そのサイズの定価で分単位に数えた費用がその金額に達した時点で停止されます |
| バッチの予算 | デフォルトではなし。latchkey budget set または set_batch_budget ツールで設定または引き下げられ、API キーで引き上げられることはありません。バッチのジョブの費用が定価で予算に達すると、そのバッチの新しいジョブは拒否され、キュー内のジョブは保留されます。実行中のジョブは最後まで実行されるため、バッチは予算をわずかに超えて終わることがあります |
| 支出上限 | 暦月ごとのワークスペースの上限で、オーナーまたは管理者が設定します。上限に達すると、latchkey run は拒否され (exit 1)、実行中のジョブは停止されます (exit 130)。ジョブやバッチの予算をこの上限より高く設定することはできません。 |
| コンテキストのアップロード | 圧縮時 200 MiB、非圧縮時 1 GiB、250,000 エントリ |
| ワークスペースごとに保持されるコンテキスト | デフォルトでは、アップロードされたコンテキストはどの時点でも合計 20 GiB までです。アップロードは、そのアーカイブが削除され、かつアップロード URL の有効期限が切れたとき、またはアップロード自体の有効期限が切れたときに解放されます |
| ジョブの作成 | ワークスペースあたり、正時で区切った 1 時間ごとに Developer 120、Launch 240、Scale 600。Enterprise は契約によります。ワークスペースが独自の回数を持つこともあり、拒否のメッセージには実際に適用されている回数が示されます。拒否された作成も、その 1 時間の回数に含まれます。 |
| API キーあたりの読み取り | API キーごとに、毎分 0 秒で切り替わる 1 分あたり 900 回。Jobs API の読み取りと MCP の読み取りツールを合わせて数え、拒否された読み取りも回数に含まれます。超えると、その 1 分が終わるまで読み取りは拒否され、待つ秒数が示されます (retry_after_s。Jobs API の 429 には Retry-After ヘッダーも付きます)。ランの待機 (latchkey wait --commit または --pr、MCP ツール wait_run) は数えられません。 |
| ジョブの記録 | ジョブ終了後、ステータスは引き続き読み取り可能で、ログは 30 日間、キャンセルは約 24 時間利用できます。latchkey list にはそれより古いジョブも引き続き表示されます |
上限を超えたコンテキストは、何かがアップロードまたは課金される前に、ローカルでのパックの段階で失敗します。最も大きなパスが名指しで表示されるため、修正はたいてい .latchkeyignore の 1 行で済みます。
ワークスペースの同時実行ジョブ数の上限に達しても、ジョブは拒否されません。Latchkey はジョブをキューで保留し、実行中のジョブが終わると開始します。自分が開始したジョブがワークスペースの上限かその近くで保留されている間は、新しいジョブを開始せず、チェックをより少ないジョブにまとめてください。
~/acme-api のターミナルで latchkey budget set refactor-auth 10 を実行すると Set the budget of batch refactor-auth to $10.00. Spent so far: $2.415 at list rates. と表示されます。latchkey budget set refactor-auth 5 は予算を引き下げ、Set the budget of batch refactor-auth to $5.00. Spent so far: $2.415 at list rates. と表示します。latchkey budget set refactor-auth 20 は引き上げを求めるもので、CLI は拒否の文 Batch refactor-auth already has a budget of $5.00, and an API key can only lower a batch's budget, so Latchkey left it unchanged. Start the work under a new batch name, or ask a workspace owner to raise this one. を表示し、このコマンドは終了コード 1 で終了します。
課金#
CLI ジョブは通常のランナー分数です: 同じサイズのワークフロージョブと同じ 1 分あたりの料金 で、ジョブごとに切り上げられ、まず同じ毎月の 無料分プール から差し引かれます。メーターはコマンドの開始からジョブの終了までを計測します。キュー待ちとプロビジョニングの時間が課金されることはありません。Cost ページでは、この支出は独自の CLI jobs 行として表示されます。これらのジョブはどのリポジトリにもワークフローにも属さないためです。ジョブが終了すると、latchkey status と latchkey list に、そのジョブのコストが無料分を差し引く前の定価で表示されます。
自己修復はここでも機能します#
すべての CLI ジョブは、ワークフロージョブと同じ 自己修復 の仕組みの下で実行されます。環境の失敗 (不安定なレジストリ、欠けているシステムパッケージ、満杯のディスク) はジョブの実行中にその場で診断され、適用できる修復があれば修正されます: 修復後のリトライが通れば 0 で終了し、何も適用できなければコマンド本来の終了コードがそのまま残ります。コードの本物の欠陥は変更されずに通過するため、終了コードは真実を語ります。ワークフロージョブとの違いが 1 つあります: CLI ジョブにはリポジトリがないため、修復がプルリクエストを開くことはありません。修正はランナー上で行われるか、まったく行われないかのどちらかです。失敗を診断するために、自己修復はアップロードされた作業ツリーのファイルを読むことがあります: 1 回の診断で最大 4 回の参照で、ファイルの先頭 8 KiB までです。読み取った内容は当社の AI モデルプロバイダーに送られ、アップロード自体が削除された後も、修復の記録に 90 日間保持されます。--exclude で除外したファイルがランナーに届くことはありません。診断は課金対象の時間内で実行されるため、失敗した実行は成功した実行よりも目に見えて多く課金されます (通常はおよそ 1 分の追加)。失敗の反復作業をするときは、その分を見込んでおいてください。
逆方向: watch#
latchkey run は、あなたが Latchkey に何かの確認を頼むものです。latchkey watch は、Latchkey があなたに何かが壊れたと伝えるものです: 自己修復が記録したものの修正しなかった失敗 (ワークフローの実行に加えて、CLI ジョブも) をポーリングし、ジョブ (Latchkey on GH では実行) ごとに最初の新しい失敗を、コーディングエージェント (デフォルトは Claude Code、それ以外は --agent) に引き渡します。エージェントは MCP サーバー を通じて失敗の記録を読み取るため、まずそちらで接続してください。一回限りの一覧表示には --once を、何も起動せずに出力だけするには --no-spawn を使います。watch はどのキーでも実行できます。読み取りしか行わないためです。
~/acme-api で latchkey watch を実行すると Watching for new failures every 15s (2 existing failures ignored). New ones go to: claude と表示されます。修復されなかった新しい失敗が届くと failure 7c2e9a14-3b5d-4f81-9a6e-0d4c8b2f1e37 と表示し、続く 1 行にリポジトリ acme/api、ワークフロー ci、カテゴリ test_failure、失敗したファイル src/auth/refresh.ts、根本原因 token expiry compared in seconds against a millisecond clock を並べ、その次に実行の GitHub リンク、最後に Handing 7c2e9a14-3b5d-4f81-9a6e-0d4c8b2f1e37 to claude… と表示します。
組み合わせて使う#
- AI エージェントを接続する: MCP の
run_jobツールは、ターミナルなしの同じジョブサーフェスです。空のワークスペースから始まります。作業ツリーを送る手段は CLI です。 - ランナーの概要: CLI ジョブは同じ 4 つのランナーサイズと同じ ランナーイメージ で実行され、ジョブごとに新しく、終了時に破棄されます。
- ランナーの使用量と無料分数: 1 分単位の計測と無料ティアの仕組み。
- Cost: CLI ジョブの支出がダッシュボードのどこに表示されるか。
よくある質問#
Q.01ジョブは git 履歴を見られますか?
いいえ。.git ディレクトリは常に除外され、再び含めることはできません。ジョブに見えるのはディスク上にあるままのファイルで、ランナーが可能な場合に作る 1 コミットだけのリポジトリに入っているため、git コマンドは動きます。その HEAD はあなたのコミットではないので、コマンドがコミット SHA やブランチ名を必要とする場合は、--env で渡してください。
Q.02ジョブはローカルのサービスやデータベースにアクセスできますか?
いいえ。ランナーは、あなたのノート PC への経路を持たない、新しく隔離されたマシンです。見えるのはアップロードされたツリーと、渡した環境変数だけで、それ以外は何もありません。対話的なコマンドが固まるのも同じ理由です: 向こう側にはターミナルがないため、入力を求めるものはすべて、タイムアウトがジョブを終わらせるまで待ち続けます。
Q.03Ctrl-C を押すとどうなりますか?
止まるのはテールであって、ジョブではありません: ジョブはランナー上で実行 (と課金) を続けます。中断通知には 2 つのフォローアップが表示されます。ジョブを停止する latchkey cancel <id> と、再アタッチする latchkey logs <id> --follow です。