CLI リファレンス

Preview docs describe unreleased preview builds. Stable docs remain at /docs/.

Nagi の CLI は、インテグレーションやエージェントが使うのと同じローカルソケット API を通じて、実行中のサーバーと通信します。

ほとんどのコマンドは JSON レスポンスを出力します。決定的な自動化が欲しいときはスクリプトから使ってください。

起動とステータス

nagi                         # デフォルトセッションを起動またはアタッチ
nagi --session work          # 名前付きセッションを起動またはアタッチ
nagi --remote workbox        # SSH 越しにアタッチ (ローカルのキーバインドを使用)
nagi --remote workbox --remote-keybindings server
nagi --remote workbox --handoff
nagi --no-session            # シングルプロセスの逃げ道
nagi --default-config        # デフォルト設定を表示
nagi update                  # 設定済みチャンネルからダウンロードしてインストール
nagi update --handoff        # 対応する実行中サーバーでライブハンドオフにオプトイン
nagi completion zsh          # zsh 補完スクリプトを生成
nagi channel show            # stable または preview を表示
nagi channel set preview     # プレビュービルドにオプトイン
nagi channel set stable      # Linux/macOS の直接インストールを安定版に戻す
nagi --version               # バージョンを表示

ステータスコマンド:

nagi status
nagi status server
nagi status client

API スキーマコマンド:

nagi api schema
nagi api schema --json
nagi api schema --output nagi-api.schema.json

nagi api schema は、インストール済みバイナリに同梱されたソケットプロトコルスキーマの短い概要を表示します。完全な JSON Schema ドキュメントが欲しいときは --json を使い、ファイルに書き出すには --output PATH を使ってください。

シェル補完

nagi completion zsh
nagi completions zsh
nagi completion bash
nagi completion fish
nagi completion powershell
nagi completion elvish

completion はスクリプトを標準出力に表示します。completions はエイリアスです。一時的な zsh セッションでは、スクリプトを直接読み込めます:

source <(nagi completion zsh)

永続的な zsh 設定では、生成された _nagi 関数を compinit が実行される前の fpath 上に置いてください:

mkdir -p ~/.zfunc
nagi completion zsh > ~/.zfunc/_nagi

その後、.zshrc に次の内容があることを確認してください:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

サーバー

nagi server
nagi server stop
nagi server reload-config
nagi server agent-manifests [--json]
nagi server update-agent-manifests [--json]
nagi server reload-agent-manifests

nagi server はヘッドレスサーバーを明示的に起動します。監視下やサービス的な構成で使ってください。reload-config はペインを再起動せずにリロード可能な設定を適用します。agent-manifests は、アクティブなエージェント検出マニフェストのソース、キャッシュされたリモートバージョン、直近のリモート更新結果を表示します。update-agent-manifests はリモートマニフェストの更新を即座に取得し、実行中のサーバーにリロードして、更新後のマニフェスト状態を表示します。生のステータスレスポンスが欲しいときは --json を渡してください。reload-agent-manifests は、ローカルオーバーライドの編集後にエージェント検出マニフェストを実行中のサーバーにリロードします。

通知

nagi notification show <title> [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request]

notification show は設定済みの [ui.toast] 配信を使います。--position はアプリ内の Nagi トーストにのみ影響します。--sound のデフォルトは none で、done と request は通知が表示されたときにのみ、既存の完了音と要注意音を再生します。

セッション

nagi session list [--json]
nagi session attach <name>
nagi session stop <name> [--json]
nagi session delete <name> [--json]

デフォルトセッションを明示的に停止する必要があるときは、セッション名として default を使ってください。

ワークスペース

nagi workspace list
nagi workspace create [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
nagi workspace get <workspace_id>
nagi workspace focus <workspace_id>
nagi workspace rename <workspace_id> <label>
nagi workspace report-metadata <workspace_id> --source ID [--token NAME=VALUE] [--clear-token NAME] [--seq N] [--ttl-ms N]
nagi workspace close <workspace_id>

フォーカスを奪わずにワークスペースを作成します:

nagi workspace create --cwd ~/project --label api --no-focus

Worktree

nagi worktree list [--workspace ID | --cwd PATH] [--json]
nagi worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--json]
nagi worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--json]
nagi worktree remove --workspace ID [--force] [--json]

worktree は、Git チェックアウトの出自情報を持つ通常の Nagi ワークスペースです。worktree create は Git worktree のチェックアウトを作成し、ワークスペースとして開き、親リポジトリのワークスペースとグループ化します。--branch が既存のローカルブランチを指す場合はそれをチェックアウトし、そうでなければ --base または HEAD からブランチを作成します。--path がない場合、チェックアウトは <worktrees.directory>/<repo>/<branch-slug> の下に作成されます。

workspace close は Nagi の状態だけを閉じます。worktree remove が明示的なチェックアウト削除の経路です。git worktree remove を実行し、ブランチは決して削除せず、Git がダーティなチェックアウトを拒否する場合は --force が必要です。

リポジトリは .nagi/project.toml で、制限付きのセットアップ、チェック、サービス、 クリーンアップ、無視ファイルの厳密なコピーを宣言できます。検出と検証はコードを実行せず、 実行には必ず --yes が必要です:

nagi project detect [PATH] [--json]
nagi project validate [PATH] [--json]
nagi project setup [PATH] --yes [--json]
nagi project check [PATH] [--id ID] --yes [--json]
nagi project cleanup [PATH] --yes [--json]
nagi project services start [PATH] --mission ID --run ID --yes [--json]
nagi project services status [PATH] --mission ID --run ID [--json]
nagi project services stop [PATH] --mission ID --run ID --yes [--json]
nagi project resources preview [--json]
nagi project resources apply --digest DIGEST --yes [--json]

サービスには衝突しない loopback ポートが割り当てられ、HTTP ヘルスチェックを通過する必要が あります。同じ mission/run の正常なサービスは、再起動後に重複起動せず引き継がれます。 クリーンアップは確認済み digest と完全一致するプレビューだけを適用します。worktree へのコピーは 明示された通常ファイルだけに限定され、symlink、glob、秘密らしい名前、過大ファイル、上書きは拒否されます。

ミッション

nagi mission list
nagi mission get <mission_id>
nagi mission proof <mission_id>
nagi mission close <mission_id>
nagi mission handoff <mission_id> --to <codex|claude-code|opencode|acp> --preview
nagi mission handoff <mission_id> --to <provider> --start --artifact-sha256 <sha256> --generated-at-millis <timestamp>

ハンドオフにはコックピットを使う方法を推奨します。ブロック中またはレビュー中の ミッションを開き、h を押してワークスペースのスナップショットを確認し、次の プロバイダーと書き込み範囲を選択します。CLI から開始する場合は、プレビューが 表示したダイジェストとタイムスタンプが必要なため、古いコンテキストから自動化を 再開することはできません。

ACP エージェントは、シェルを介さないローカル stdio プロセスとして設定します:

[providers.acp]
command = ["my-acp-agent", "--stdio"]

タブ

nagi tab list [--workspace <workspace_id>]
nagi tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
nagi tab get <tab_id>
nagi tab focus <tab_id>
nagi tab rename <tab_id> <label>
nagi tab close <tab_id>

ペイン

nagi pane list [--workspace <workspace_id>]
nagi pane current [--pane ID|--current]
nagi pane get <pane_id>
nagi pane layout [--pane ID|--current]
nagi pane process-info [--pane ID|--current]
nagi pane neighbor --direction left|right|up|down [--pane ID|--current]
nagi pane edges [--pane ID|--current]
nagi pane focus --direction left|right|up|down [--pane ID|--current]
nagi pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
nagi pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
nagi pane rename <pane_id> <label>|--clear
nagi pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--focus] [--no-focus]
nagi pane swap --direction left|right|up|down [--pane ID|--current]
nagi pane swap --source-pane ID --target-pane ID
nagi pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
nagi pane move <pane_id> --new-tab [--workspace ID] [--label TEXT] [--focus|--no-focus]
nagi pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--focus|--no-focus]
nagi pane close <pane_id>

出力を読む:

nagi pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N]
nagi pane read <pane_id> --source visible --ansi
nagi pane read <pane_id> --source recent-unwrapped --lines 120

入力を送る:

nagi pane send-text <pane_id> <text>
nagi pane send-keys <pane_id> <key> [key ...]
nagi pane run <pane_id> <command>

<key> は Nagi のキーコンボ構文を使います: a のような通常の印字可能キー、enter、tab、esc、backspace、left、right、up、down のような特殊キー、ctrl+h、control+j、alt+x、shift+tab のような修飾キーコード、f1 のようなファンクションキー、そして minus、plus、backtick のような名前付き記号です。レガシーな C-c と c-c は ctrl+c のエイリアスとして受け付けられます。

pane run はテキストと Enter をアトミックに送信します。コマンドには send-text + send-keys Enter よりこちらを使ってください。

カスタムフックからエージェント状態を報告する:

nagi pane report-agent <pane_id> \
  --source ID \
  --agent LABEL \
  --state idle|working|blocked|unknown \
  [--message TEXT] \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path PATH]

公式インテグレーションがネイティブセッション参照を報告している場合、pane get、pane list、agent get、agent list は読み取り専用の agent_session オブジェクトを含みます。ネイティブセッション参照が保存されていない場合、このフィールドは省略されます。

これらのコマンドは、ペインを制御しているフォアグラウンドプロセスの cwd を解決できる場合に foreground_cwd を含みます。既存の cwd フィールドは、ラベルと follow-cwd 挙動に使われるペイン/ワークスペースの cwd のままです。

意味的な状態を奪わずに、表示専用のペインメタデータを報告する:

nagi pane report-metadata <pane_id> \
  --source ID \
  [--agent LABEL] \
  [--applies-to-source ID] \
  [--title TEXT|--clear-title] \
  [--display-agent TEXT|--clear-display-agent] \
  [--state-label STATUS=TEXT] \
  [--clear-state-labels] \
  [--token NAME=VALUE] \
  [--clear-token NAME] \
  [--seq N] \
  [--ttl-ms N]

STATUS は idle、working、blocked、done、unknown のいずれかです。--agent と --applies-to-source は --title、--display-agent、--state-label だけを保護し、トークンパッチは保護しません。トークンのクリアまたは TTL の更新は報告側が管理します。表示名を変えるには --display-agent を使ってください。

メタデータのテキストは保存前に正規化されます。Nagi は前後の空白を取り除き、制御文字を除去し、--title、--display-agent、各 --state-label、トークンの値を 80 文字に制限します。正規化後に空になったトークン値は、そのキーをクリアします。

--token は名前付き表示値を設定し、--clear-token は削除します。指定しなかったトークンは変わりません。ペイントークンはエージェントサイドバー行で $name として、ワークスペーストークンはスペース行で使えます。TTL は、その呼び出しで更新した各トークンキーに個別に適用されます。

--source と --applies-to-source は 80 文字以下で、ASCII の英字、数字、コロン、ドット、アンダースコア、ハイフンのみを含められます。--ttl-ms はメタデータを自動失効させ、1 から 86400000 ミリ秒の間でなければなりません。置き換え・クリア・ペインまたはワークスペースのクローズまで残るべきメタデータでは省略してください。--seq により、Nagi は同じ --source からの古い報告を無視できます。古い報告は API には受理されますが、ペイン状態には無視されます。ペインまたはワークスペースが存続する間、シーケンス付きトークン報告を送れる異なるソースは最大 32 個で、クリアや失効でもその枠は解放されません。

エージェント

nagi agent list
nagi agent get <target>
nagi agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
nagi agent send <target> <text>
nagi agent rename <target> <name>|--clear
nagi agent focus <target>
nagi agent wait <target> --status <idle|working|blocked|unknown> [--timeout MS]
nagi agent attach <target> [--takeover]
nagi agent start <name> [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- <argv...>
nagi agent explain <target> [--json|--verbose]
nagi agent explain --file PATH --agent LABEL [--json|--verbose]

エージェントターゲットには、ターミナル ID、一意なエージェント名、検出または報告されたエージェントラベル、レガシーなペイン ID が使えます。名前とラベルはエージェントのアイデンティティです。ターミナル ID とレガシーペイン ID は低レベルな逃げ道です。

agent read は解決されたターミナルストリームを読みます。agent send はそのストリームにリテラルのテキストを書き込みます。agent get、agent focus、agent wait、agent attach は、解決されたターミナルがエージェントのアイデンティティを持つことを要求します。agent rename はそのアイデンティティを割り当てられます。

agent explain は、スクリーン検出が使うのと同じ下部バッファの検出スナップショットの分類を実行中のサーバーに依頼します。そのためライブの出力はサーバーのアクティブなマニフェストキャッシュを反映します。これは agent.explain ソケットメソッドを使うので、Nagi のアップグレード後にライブ explain を使う前に、サーバーを再起動するか更新済みサーバーへハンドオフしてください。保存済みフィクスチャをローカルで説明するには --file PATH --agent LABEL を使います。デフォルトの出力には、エージェント、最終状態、マニフェストのソースとバージョン、リージョンの証拠付きでマッチしたルール、そしてフォールバック・スキップ・警告の理由が表示されます。--verbose を付けると、可視の証拠フラグ、キャッシュされたリモートバージョン、ローカルオーバーライドのシャドーイング、リモート更新状況、マッチャーとリージョンの証拠付きの評価済みルール全リストが表示されます。issue の報告やテストには --json を付けてください。

通常のターミナル、サーバー、テスト、シェル、低レベルなターミナル制御には pane send-text、pane send-keys、pane run、terminal attach を使ってください。Enter 付きでコマンドを送信したいときは pane run を使います。

ダイレクトターミナルアタッチ

nagi terminal attach <terminal_id> [--takeover]
nagi terminal title set <title>
nagi terminal title clear

ダイレクトアタッチからは ctrl+b q でデタッチします。リテラルの ctrl+b は ctrl+b ctrl+b で送ります。 terminal title clear は Nagi のデフォルトの外側ターミナルウィンドウタイトルを復元します。

Wait

ペインの出力を待つ:

nagi wait output <pane_id> --match <text> [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--regex] [--raw]

ペインのエージェント状態を待つ:

nagi wait agent-status <pane_id> --status <idle|working|blocked|done|unknown> [--timeout MS]

通常のコマンドやサーバーには wait output を使います。コーディングエージェントには wait agent-status を使います。

インテグレーション

nagi integration install pi
nagi integration install omp
nagi integration install claude
nagi integration install codex
nagi integration install copilot
nagi integration install devin
nagi integration install droid
nagi integration install kimi
nagi integration install opencode
nagi integration install kilo
nagi integration install hermes
nagi integration install mastracode
nagi integration install qodercli
nagi integration install cursor
nagi integration uninstall pi
nagi integration uninstall omp
nagi integration uninstall claude
nagi integration uninstall codex
nagi integration uninstall copilot
nagi integration uninstall devin
nagi integration uninstall droid
nagi integration uninstall kimi
nagi integration uninstall opencode
nagi integration uninstall kilo
nagi integration uninstall hermes
nagi integration uninstall mastracode
nagi integration uninstall qodercli
nagi integration uninstall cursor
nagi integration status [--outdated-only]

プラグイン

プラグインコマンドは、ローカル実行型ワークフロープラグインをインストールして実行します。プラグインはマニフェストとプロセス外コマンドの組み合わせです。ホスト側の面は Nagi が、実装言語はプラグインが担います。

プラグインのインストール、一覧、削除:

nagi plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
nagi plugin list [--plugin ID] [--json]
nagi plugin uninstall <plugin_id|owner/repo[/subdir...]>
nagi plugin enable <plugin_id>
nagi plugin disable <plugin_id>

plugin install は owner/nagi-plugin/worktree-bootstrap のような GitHub 省略記法のみを受け付けます。git を使い、対話的なターミナルでは信頼プレビューを表示し、サポートされるマニフェストのビルドコマンドを実行し、GitHub インストールを Nagi 管理のディレクトリに保存します。非対話的なインストールには --yes を使ってください。GitHub 管理プラグインの再インストールは、その管理チェックアウトを置き換えます。ローカルにリンクされたプラグインへの上書きインストールは拒否されます。プラグインのマニフェストは min_nagi_version を宣言しなければならず、プラグインがより新しい Nagi バイナリを要求する場合、install と link は失敗します。plugin list はデフォルトで人間可読です。生の API レスポンスが欲しいときは --json を渡してください。

ローカル開発:

nagi plugin link <path> [--disabled]
nagi plugin unlink <plugin_id>

plugin link は nagi-plugin.toml を含むプラグインディレクトリ、またはマニフェストへの直接パスを受け付けます。ローカルチェックアウトからプラグインを作成・テストしている間はこれが正しいコマンドです。plugin unlink はプラグインの登録を解除し、ファイルには触れません。plugin uninstall はプラグインの登録を解除し、Nagi 管理の GitHub チェックアウトファイルも削除します。GitHub インストールの場合、uninstall はプラグイン id と、install で使うのと同じ owner/repo[/subdir...] 省略記法の両方を受け付けます。アクション、イベントフック、ペイン、リンクハンドラーはマニフェストで宣言します。ランタイムでのアクション登録は v1 の範囲外です。

設定ディレクトリ:

nagi plugin config-dir <plugin_id>

plugin config-dir はプラグインの設定ディレクトリを表示し、必要なら作成します (レガシーなプラグイン設定の場所が存在すれば、そこから初期内容を移します)。セットアップドキュメントやシェルスクリプトで、管理されたプラグインチェックアウトとは別の、.env ファイルなどユーザーが編集する設定のための安定したパスをユーザーに示すのに使ってください。

アクション:

nagi plugin action list [--plugin ID]
nagi plugin action invoke <action_id> [--plugin ID]

plugin action invoke は、インストール済みで有効かつプラットフォーム互換のプラグインアクションのマニフェストコマンドを起動し、開始されたコマンドのログレコードを JSON レスポンスに表示します。複数のプラグインが同じアクション id を使っている場合は、修飾されたアクション id (plugin.id.action) を使ってください。ローカルのアクション id はドットを含められないため、プラグイン id がドットを含んでいても修飾 id は曖昧になりません。

ログ:

nagi plugin log list [--plugin ID] [--limit N]

管理されたターミナルペイン:

nagi plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
nagi plugin pane focus <pane_id>
nagi plugin pane close <pane_id>

plugin pane open は、プラグインがリンクされ、有効で、現在のプラットフォームと互換であることを要求します。マニフェストで宣言された [[panes]] コマンドを Nagi 管理のターミナルペインとして起動します。マニフェストのデフォルトは overlay で、アクティブなペインの上に一時的なズームオーバーレイを開きます。分割、新しいタブ、ズームされたペイン、またはタブレイアウトを変更しないセッションモーダルな popup として開くこともできます。--width と --height は、外側のポップアップ寸法をターミナルセル数または 80% のような割合で指定します。省略した寸法はデフォルトでターミナルの半分になり、小さすぎる値はポップアップの最小サイズに制限されます。ポップアップは Nagi ペインではなく、NAGI_PANE_ID を受け取らず、pane API やエージェント API に参加しません。ターミナル以外のネイティブなプラグインペインは今後の対応面です。

--env KEY=VALUE はプロセスを起動するコマンドで繰り返し指定できます。新しく起動されるプロセスにのみ適用されます。NAGI_SOCKET_PATH、NAGI_BIN_PATH、NAGI_ENV、NAGI_WORKSPACE_ID、NAGI_TAB_ID、NAGI_PANE_ID、NAGI_PLUGIN_ID、NAGI_PLUGIN_ROOT、NAGI_PLUGIN_CONFIG_DIR、NAGI_PLUGIN_STATE_DIR、NAGI_PLUGIN_ENTRYPOINT_ID、NAGI_PLUGIN_CONTEXT_JSON のような Nagi 管理の変数は、呼び出し側が与えた環境変数と衝突した場合も権威を保ちます。

読み取りソース

ソース	意味
visible	現在レンダリングされている画面。UI のフィードバックループに最適。
recent	ターミナルの折り返しを含む直近のスクロールバック。
recent-unwrapped	ソフト折り返しなしの直近のスクロールバック。ログに最適。
detection	エージェントのスクリーン検出が使う下部バッファのスナップショット。

環境変数

変数	目的
NAGI_CONFIG_PATH	設定ファイルパスを上書きする。
NAGI_SESSION	CLI コマンドの名前付きセッションを選択する。
NAGI_SOCKET_PATH	低レベルなソケットパスの上書き。
NAGI_ENV	Nagi 管理のペインプロセス内で 1 に設定される。
NAGI_PANE_ID	実行中ペインプロセスの公開ペイン id。
NAGI_TAB_ID	実行中ペインプロセスの公開タブ id。
NAGI_WORKSPACE_ID	実行中ペインプロセスの公開ワークスペース id。
NAGI_LOG	ログフィルターを設定する。例: NAGI_LOG=nagi=debug。
NAGI_DISABLE_SOUND	サウンド通知が有効でも音の再生を無効にする。