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

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

Source: https://latchkey.dev/ja/documentation/latchkey-cli

## Summary

- `npm install -g @latchkeydev/cli` の後、`latchkey run 'npm test'` がコマンドを新しい Latchkey ランナーで実行し、コマンド自身の終了コードで終了します。
- 作業ツリーはジョブと一緒に送られます: `.gitignore` のルールが適用され、クレデンシャルの形をしたファイルはデフォルトで除外され、`.latchkeyignore` が両方を上書きします。
- ジョブは通常のランナー分数として、同じ無料分プールから課金されます。その支出はコスト分析ページに独自の **CLI Jobs** 行として表示されます。
- **Allow running CLI jobs (includes reading)** を有効にして作成した API キーが必要です。コーディングエージェントは MCP の `run_job` ツールを通じて同じサーフェスにアクセスします。

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

## インストールと認証

1. **CLI をインストールする** npm でグローバルにインストールするか (Node 20.18.1 以降)、`npx @latchkeydev/cli` でアドホックに実行します。スコープ付きのパッケージ名をインストールしてください: npm 上のスコープなしの `latchkey` パッケージは無関係のプロジェクトです。
2. **ジョブ実行可能な API キーを作成する** **Settings, API Keys** で (オーナーと管理者)、**Allow running CLI jobs (includes reading)** にチェックを入れてキーを生成します。権限は作成時に固定されます: 既存のキーが遡って権限を得ることはありません。完全なキー (`lk_live_` で始まります) は一度だけ表示されます。
3. **ログインする** `latchkey login` は課金対象のものを何も起動せずにキーを検証し、このマシン用に保存します (`~/.config/latchkey/config.json`)。CI やエージェントループでは、保存された設定を使わず、代わりに環境変数 `LATCHKEY_TOKEN` を設定してください。

## ジョブを実行する

```terminal
$ 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 行も解析せずに結果で分岐できます。

> **終了コードが判定です**
> `latchkey run 'npm test'` が 0 で終了すれば、スイートはクリーンな Linux ランナーで通過したことを意味します。非ゼロなら通過しなかったことを意味します。出力を別のコマンドにパイプすると、その判定は下流コマンドのステータスに置き換わります。ログと終了コードの両方が必要な場合は、代わりにファイルへリダイレクトしてください。

## コマンド一覧

| コマンド | 何をするか |
| --- | --- |
| `latchkey login` | API キーを検証し、このマシン用に保存する |
| `latchkey run` | 現在のディレクトリをパックし、新しいランナーでコマンドを実行し、ログをストリーミングし、コマンドの終了コードで終了する |
| `latchkey list` | 最近のジョブを、まだ実行中のものも含めて新しい順に一覧表示する |
| `latchkey logs` | ジョブのログを出力するか、`--follow` で完了までテールする |
| `latchkey status` | ジョブの状態、ランナーサイズ、タイミング、終了コードを表示する |
| `latchkey cancel` | キャンセルをリクエストする。実行中のジョブは約 10 秒以内に停止する |
| `latchkey watch` | 自己修復が修正できなかった CI の失敗をポーリングし、それぞれをコーディングエージェントに引き渡す |

実際に使うことになる `run` のフラグ: `--size` はランナーを選択します (`small` がデフォルト。`medium`、`large`、`xlarge` はワークフローで使う [ランナーサイズ](/documentation/runners-overview) に対応します)。`--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` ファイル (同じ構文) は両方より優先されます: さらに除外するためにも、拒否リストが除外したものを意図的に再び含めるためにも使えます。後者の場合は、ファイル名を明示した目立つ警告が表示されます。

> **git 履歴は手元に残ります**
> `.git` ディレクトリは決して送られず、再び含めることもできません。そのため、ジョブに見えるのはファイルであって、履歴やリモートではありません。ジョブ内でコミット SHA やブランチ名が必要ですか? `--env` で渡してください。本物のシークレットも `--env` に置くべきで、アップロードされるツリーに入れてはいけません。

## 制限

| 制限 | 値 |
| --- | --- |
| コマンドライン | 16,384 文字 |
| 環境変数 | ジョブあたり 64 個 |
| ジョブのタイムアウト | 30 秒から 2 時間、デフォルトは 30 分 |
| コンテキストのアップロード | 圧縮時 200 MB、非圧縮時 1 GiB、250,000 エントリ |
| ジョブの作成 | ワークスペースあたり毎時 120 ジョブ |
| ジョブの記録 | ステータスとログはジョブ終了後、約 24 時間読み取り可能です。`latchkey list` にはそれより古いジョブも引き続き表示されます |

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

## 課金

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

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

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

## 逆方向: watch

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

## 組み合わせて使う

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

## よくある質問

### ジョブは git 履歴を見られますか?

いいえ。`.git` ディレクトリは常に除外され、再び含めることはできません。ジョブに見えるのは、ディスク上にあるままのファイルです。コマンドがコミット SHA やブランチ名を必要とする場合は、`--env` で渡してください。

### ジョブはローカルのサービスやデータベースにアクセスできますか?

いいえ。ランナーは、あなたのノート PC への経路を持たない、新しく隔離されたマシンです。見えるのはアップロードされたツリーと、渡した環境変数だけで、それ以外は何もありません。対話的なコマンドが固まるのも同じ理由です: 向こう側にはターミナルがないため、入力を求めるものはすべて、タイムアウトがジョブを終わらせるまで待ち続けます。

### Ctrl-C を押すとどうなりますか?

止まるのはテールであって、ジョブではありません: ジョブはランナー上で実行 (と課金) を続けます。中断通知には 2 つのフォローアップが表示されます。ジョブを停止する `latchkey cancel <id>` と、再アタッチする `latchkey logs <id> --follow` です。

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt