このページの翻訳は LLM によって生成されています。誤りに気づいた場合は GitHub で issue を開いてお知らせください。

CLI リファレンス

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

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

起動とステータス

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

ステータスコマンド:

pk-herdr status
pk-herdr status server
pk-herdr status client

API スキーマコマンド:

pk-herdr api schema
pk-herdr api schema --json
pk-herdr api schema --output herdr-api.schema.json

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

シェル補完

pk-herdr completion zsh
pk-herdr completions zsh
pk-herdr completion bash
pk-herdr completion fish
pk-herdr completion powershell
pk-herdr completion elvish

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

source <(pk-herdr completion zsh)

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

mkdir -p ~/.zfunc
pk-herdr completion zsh > ~/.zfunc/_herdr

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

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

サーバー

pk-herdr server
pk-herdr server stop
pk-herdr server reload-config
pk-herdr server agent-manifests [--json]
pk-herdr server update-agent-manifests [--json]
pk-herdr server reload-agent-manifests

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

通知

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

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

セッション

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

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

ワークスペース

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

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

pk-herdr workspace create --cwd ~/project --label api --no-focus

ワークスペースは最上位のプロジェクトまたは作業コンテキストです。作成時に最初のタブとルートペインも作られます。JSON レスポンスの .result.workspace.workspace_id、.result.tab.tab_id、.result.root_pane.pane_id から各 ID を取得できます。

Worktree

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

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

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

タブ

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

タブはワークスペース内の別のターミナルレイアウトです。--workspace を省略すると、tab create はアクティブなワークスペースを使い、存在しなければ失敗します。JSON レスポンスの .result.tab.tab_id と .result.root_pane.pane_id から ID を取得できます。

ワークスペースとタブの作成、およびペインの分割は、デフォルトではフォーカスを変えません。--focus は新しいレイアウトを選択し、--no-focus はデフォルトを明示します。--cwd がない場合、新しいターミナルは terminal.new_cwd の設定に従い、デフォルトでは元のペインまたはワークスペースを引き継ぎます。各 --env KEY=VALUE は新しいルートシェルの環境変数を追加または置換します。

ペイン

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

--current を受け付けるペインコマンドは、PK-Herdr ペイン内から実行した場合、呼び出し元の HERDR_PANE_ID を使います。pane split では、明示したペイン ID または --pane ID がそのペインを、--current が呼び出し元ペインを分割します。対象を省略すると UI でフォーカス中のペインを使います。分割レスポンスでは、新しいペイン ID は .result.pane.pane_id にあります。

pane move の後続コマンドには .result.move_result.pane.pane_id を使います。別ワークスペースへの移動ではワークスペース修飾付きのペイン ID が変わり、以前の値は .result.move_result.previous_pane_id に残ります。実行中プロセスの HERDR_PANE_ID、HERDR_TAB_ID、HERDR_WORKSPACE_ID は起動時の値のままですが、PK-Herdr は以前のペイン ID をそのターミナルの別名として保持するため、--current を使うペインコマンドは引き続き解決できます。ライブエージェント名もターミナルに追従します。

出力を読む:

pk-herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
pk-herdr pane read <pane_id> --source visible --ansi
pk-herdr pane read <pane_id> --source recent-unwrapped --lines 120

pane read は UTF-8 のターミナルテキストを直接出力します。デフォルトでは ANSI エスケープを除去し、ソースに装飾が含まれる場合は --format ansi または --ansi で保持します。detection ソースは常にプレーンテキストです。recent 系ソースでは、--lines N は折り返し解除の前に末尾の N 描画行を選び、省略時は 80 行です。visible と detection では、省略時にスナップショット全体を返し、指定時は改行で区切られた末尾 N 行を返します。agent read も同じ出力と行数の動作です。

入力を送る:

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

<key> は PK-Herdr のキーコンボ構文を使います: 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 のエイリアスとして受け付けられます。

標準表記は esc ですが、escape も使えます。

pane run は現在の bracketed paste モードを尊重し、テキストと Enter をアトミックに送信します。コマンドには send-text + send-keys Enter よりこちらを使ってください。個別の送信操作は低レベルのままで、コマンドを送信しません。

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

pk-herdr 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]

pk-herdr pane report-agent-session <pane_id> \
  --source ID \
  --agent LABEL \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path PATH] \
  [--session-start-source SOURCE]

pk-herdr pane release-agent <pane_id> \
  --source ID \
  --agent LABEL \
  [--seq N]

report-agent-session はライフサイクル状態を報告せずにネイティブセッション識別子を更新します。release-agent は、そのエージェントプロセスが終了したときに、そのソースのライフサイクル権限を終了します。

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

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

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

pk-herdr 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 を使ってください。

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

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

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

エージェント

ペインとエージェントの使い分けや一連の連携例は、エージェント自動化を参照してください。

pk-herdr agent list
pk-herdr agent get <target>
pk-herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
pk-herdr agent send-keys <target> <key> [key ...]
pk-herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
pk-herdr agent rename <target> <name>|--clear
pk-herdr agent focus <target>
pk-herdr agent wait <target> [--until STATUS]... [--timeout MS]
pk-herdr agent attach <target> [--takeover]
pk-herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
pk-herdr agent explain <target> [--json|--verbose]
pk-herdr agent explain --file PATH --agent LABEL [--json|--verbose]

エージェントターゲットは、一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID です。ターミナル ID とエージェント kind のラベルだけでは指定できません。agent start で起動するエージェントには名前が必須で、手動で起動したエージェントは名前なしのままペイン ID で指定します。

agent start は既存の利用可能なシェルペインを起動対象にします。対話シェル自身がフォアグラウンドを所有し、フォアグラウンドのコマンド、エディタ、エージェントが動いていない必要があります。トポロジーは別に作成します。名前はライブエージェント間で一意で、[a-z][a-z0-9_-]{0,31} に一致する必要があります。対応する kind は pi、claude、codex、gemini、cursor、devin、agy、cline、omp、mastracode、opencode、copilot、kimi、kiro、droid、amp、grok、hermes、kilo、qodercli、maki です。名前は現在のペイン占有者に属し、そのエージェントの終了、release、置換で消えます。一時的に検出できないだけでは消えません。

start は、期待したエージェントが同じターミナルを所有し、対話入力の準備ができてから返ります。デフォルトの起動タイムアウトは 30000 ミリ秒で、明示する値は 3000 より大きく 300000 以下でなければなりません。

agent prompt は現在の bracketed paste モードを尊重し、working 中でもテキストとエンコード済み Enter をアトミックに送信します。--wait を使う場合、non-working 状態から送信したプロンプトは 5 秒以内に観測可能なライフサイクル変化を起こす必要があり、変化がなければ PK-Herdr は agent_prompt_stalled を返します。呼び出し側のタイムアウトが 5 秒以下なら、通常の timeout エラーを維持します。活動を観測した後、要求された安定状態を待ちます。個々のターンは追跡しません。すでに working の場合、進行中ターンの完了が待機を満たすことがあります。--until は一致状態を絞り込み、--wait なしでは拒否されます。単独の agent wait は現在の状態が一致すれば即座に返ります。どちらもデフォルトは idle、done、blocked です。

idle は入力待ちで、そのタブがフォーカス中の PK-Herdr UI ですでに表示済みの状態です。done は同じ基礎的な idle 状態ですが、表示していないバックグラウンド作業が完了したときに使われます。そのタブをフォーカスするか pane focus / agent focus で対象にすると表示済みになりますが、CLI で読み取るだけでは変わりません。blocked は承認または質問 UI を PK-Herdr が認識した状態です。unknown はエージェントが存在するものの確実に分類できない状態で、作業の成功を意味しません。

agent send-keys は enter、up、esc、ctrl+c などの論理キーを送ります。PK-Herdr は 1 バイトも書き込む前に全キーを検証します。agent read は解決されたターミナルストリームを読み、agent rename は検出済みエージェントに名前を付けます。

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

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

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

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

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

出力待機

ペインの出力を待つ:

pk-herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]

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

pane wait-output は選択したスナップショットを最初にすぐ検索するため、すでに存在する出力も一致します。デフォルトのソース名は recent で、直近 80 行の描画済みターミナル行を折り返し前の出力として扱います。--lines でその行数を変更できます。--match は 1 行内のリテラル部分文字列を検索し、--regex は Rust の正規表現構文で 1 行ずつ一致します。

pane wait-output、agent wait、agent prompt --wait は、--timeout を省略すると無期限に待ちます。タイムアウトまたはサーバーエラーは JSON として stderr に出力され、終了コード 1 になります。CLI 使用法のエラーは終了コード 2 です。

インテグレーション

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

プラグイン

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

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

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

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

ローカル開発:

pk-herdr plugin link <path> [--disabled]
pk-herdr plugin unlink <plugin_id>

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

設定ディレクトリ:

pk-herdr plugin config-dir <plugin_id>

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

アクション:

pk-herdr plugin action list [--plugin ID]
pk-herdr plugin action invoke <action_id> [--plugin ID]

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

ログ:

pk-herdr plugin log list [--plugin ID] [--limit N]

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

pk-herdr 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]
pk-herdr plugin pane focus <pane_id>
pk-herdr plugin pane close <pane_id>

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

--env KEY=VALUE はプロセスを起動するコマンドで繰り返し指定できます。新しく起動されるプロセスにのみ適用されます。HERDR_SOCKET_PATH、HERDR_BIN_PATH、HERDR_ENV、HERDR_WORKSPACE_ID、HERDR_TAB_ID、HERDR_PANE_ID、HERDR_PLUGIN_ID、HERDR_PLUGIN_ROOT、HERDR_PLUGIN_CONFIG_DIR、HERDR_PLUGIN_STATE_DIR、HERDR_PLUGIN_ENTRYPOINT_ID、HERDR_PLUGIN_CONTEXT_JSON のような PK-Herdr 管理の変数は、呼び出し側が与えた環境変数と衝突した場合も権威を保ちます。

読み取りソース

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

この表は読み取り時の意味です。pane wait-output に限り、recent と recent-unwrapped はどちらも recent の折り返し前スナップショットを検索し、デフォルト表記は recent です。

環境変数

変数	目的
`HERDR_CONFIG_PATH`	設定ファイルパスを上書きする。
`HERDR_SESSION`	CLI コマンドの名前付きセッションを選択する。
`HERDR_SOCKET_PATH`	低レベルなソケットパスの上書き。
`HERDR_ENV`	PK-Herdr 管理のペインプロセス内で `1` に設定される。
`HERDR_PANE_ID`	実行中ペインプロセスの公開ペイン id。
`HERDR_TAB_ID`	実行中ペインプロセスの公開タブ id。
`HERDR_WORKSPACE_ID`	実行中ペインプロセスの公開ワークスペース id。
`HERDR_LOG`	ログフィルターを設定する。例: `HERDR_LOG=herdr=debug`。
`HERDR_DISABLE_SOUND`	サウンド通知が有効でも音の再生を無効にする。