CLI から単発のジョブを実行する

ターミナルやコーディングエージェントから、任意のコマンドを新しい Latchkey ランナーで実行します。CLI が作業ツリーをパックし、ログをストリーミングで返し、コマンド自身の終了コードで終了します。

Latchkey CLI (@latchkeydev/cli) は、新しい CI マシンを、ローカルコマンドのように呼び出せるものに変えます。 latchkey run 'npm test' は作業ツリーをパックし、隔離された Latchkey ランナーでコマンドを実行し、出力をターミナルにストリーミングし、コマンド自身の終了コードで終了します。これにより、スクリプト化できる検証ループになります: プッシュする前に、CI が実行するのと同じやり方で、クリーンな Linux マシン上でチェックを実行できます。プッシュ前の検証、CI でのみ発生する失敗の再現 (クリーンなワークスペース、新規インストール、Linux)、そして他のシェルコマンドと同じようにこれを操作するコーディングエージェントのために作られています。

インストールと認証#

$ npm install -g @latchkeydev/cli
$ latchkey --help

ジョブを実行する#

$ latchkey run 'npm test'
$ latchkey run --size large --timeout 3600 'npm ci && npm run build && npm test'
$ latchkey run --env NODE_ENV=test 'npm test'

すべての実行は同じ 5 つのことを行います: 現在のディレクトリをコンテキストアーカイブにパックし、アップロードし、新しいランナーでコマンドを実行し、ログをライブでストリーミングして返し、コマンド自身の終了コードで終了します。キャンセルされたジョブは 130 で終了し、プラットフォームが期限切れにしたジョブは 124 で終了するため、スクリプトやエージェントはログテキストを 1 行も解析せずに結果で分岐できます。

コマンド一覧#

実際に使うことになる run のフラグ: --size はランナーを選択します (small がデフォルト。medium、large、xlarge はワークフローで使う ランナーサイズ に対応します)。--env KEY=VALUE はシークレットや設定をファイルとして送らずに渡します。--timeout は 30 秒から 2 時間まで受け付けます (ジョブのデフォルトは 30 分)。--detach はジョブを送信して終了するため、後からテールできます。--no-context は何もアップロードせず、空のワークスペースでコマンドを実行します。すべてのリモートコマンドは機械可読な出力のための --output json を受け付け、パッケージには、コーディングエージェントが完全な契約を読み取れる独自の詳細リファレンス (SKILL.md) が同梱されています。

ジョブと一緒に送られるもの#

latchkey run は実行したディレクトリをパッケージ化します。それを囲むリポジトリは決して対象になりません。そのため、サブディレクトリから実行するとそのサブディレクトリだけが送られます。何が含まれるかは 3 つのルールが決め、最後に意見を表明したルールが勝ちます:

• パッケージ化されるツリー内のすべての .gitignore が適用されるため、ignore された依存関係のインストール物やビルド出力は手元に残り、ジョブは CI と同じようにゼロからインストールします。対象になるのはツリー内にある ignore ファイルだけです: サブディレクトリから実行すると、リポジトリルートの .gitignore は適用されなくなります (パッケージ化のルートに .latchkeyignore を置くのが解決策です)。
• クレデンシャルの形をしたファイル (.env ファイル、秘密鍵、クラウドのクレデンシャルファイル) は組み込みの拒否リストによって除外され、除外はすべて出力に表示されます。.gitignore がそれらを再び含めることは決してできません。
• .latchkeyignore ファイル (同じ構文) は両方より優先されます: さらに除外するためにも、拒否リストが除外したものを意図的に再び含めるためにも使えます。後者の場合は、ファイル名を明示した目立つ警告が表示されます。

制限#

上限を超えたコンテキストは、何かがアップロードまたは課金される前に、ローカルでのパックの段階で失敗します。最も大きなパスが名指しで表示されるため、修正はたいてい .latchkeyignore の 1 行で済みます。

課金#

CLI ジョブは通常のランナー分数です: 同じサイズのワークフロージョブと同じ 1 分あたりの料金で、ジョブごとに切り上げられ、まず同じ毎月の 無料分プール から差し引かれます。メーターはコマンドの開始からジョブの終了までを計測します。キュー待ちとプロビジョニングの時間が課金されることはありません。コスト分析 ページでは、この支出は独自の CLI Jobs 行として表示されます。これらのジョブはどのリポジトリにもワークフローにも属さないためです。

自己修復はここでも機能します#

すべての CLI ジョブは、ワークフロージョブと同じ 自己修復 の仕組みの下で実行されます。環境の失敗 (不安定なレジストリ、欠けているシステムパッケージ、満杯のディスク) はジョブの実行中にその場で診断され、適用できる修復があれば修正されます: 修復後のリトライが通れば 0 で終了し、何も適用できなければコマンド本来の終了コードがそのまま残ります。コードの本物の欠陥は変更されずに通過するため、終了コードは真実を語ります。ワークフロージョブとの違いが 1 つあります: CLI ジョブにはリポジトリがないため、修復がプルリクエストを開くことはありません。修正はランナー上で行われるか、まったく行われないかのどちらかです。診断は課金対象の時間内で実行されるため、失敗した実行は成功した実行よりも目に見えて多く課金されます (通常はおよそ 1 分の追加)。失敗の反復作業をするときは、その分を見込んでおいてください。

逆方向: watch#

latchkey run は、あなたが Latchkey に何かの確認を頼むものです。latchkey watch は、Latchkey があなたに何かが壊れたと伝えるものです: 自己修復が診断したものの修正できなかった失敗 (ワークフローの実行に加えて、CLI ジョブも) をポーリングし、新しいものをそれぞれ、正確に一度だけコーディングエージェント (デフォルトは Claude Code、それ以外は --agent) に引き渡します。エージェントは MCP サーバー を通じて完全な失敗コンテキストを読み取るため、まずそちらで接続してください。一回限りの一覧表示には --once を、何も起動せずに出力だけするには --no-spawn を使います。watch はどのキーでも実行できます。読み取りしか行わないためです。

組み合わせて使う#

• AI エージェントを接続する: MCP の run_job ツールは、ターミナルなしの同じジョブサーフェスです。空のワークスペースから始まります。作業ツリーを送る手段は CLI です。
• ランナーの概要: CLI ジョブは同じ 4 つのランナーサイズと同じ ランナーイメージ で実行され、ジョブごとに新しく、終了時に破棄されます。
• ランナーの使用量と無料分数: 1 分単位の計測と無料ティアの仕組み。
• コスト分析: CLI ジョブの支出がダッシュボードのどこに表示されるか。

よくある質問#