Pi日本語

PI DOCUMENTATION / 日本語

CLI 統合

原文を読む ↗
非公式日本語訳機械翻訳・対訳チェック済み更新 2026/10/01

デフォルトでは、pi を実行すると対話型ターミナルインターフェースが開きます。入力または出力がパイプ処理またはリダイレクトされる場合、Pi は代わりにプリントモードを使用します。スクリプトやアプリケーション向けに、プリント、JSON、RPC の各モードを明示的に選択することもできます。

4 つのモードはすべて、同じエージェント、セッション、リソース、ツールを使用します。モードによって、Pi への入力方法、出力の公開方法、およびプロセスが後続のコマンドを受け付けるために稼働し続けるかどうかが決まります。

SDK は CLI モードではありません。エージェントを Node.js または Bun プロセスに直接組み込みます。プロセス境界を介するよりも TypeScript から直接アクセスする方が適している場合は、SDK を参照してください。

モードを選択する#

モード インターフェース 稼働期間 使用する場面
対話型 ターミナル UI ユーザーが終了するまで ユーザーが Pi を直接操作する場合
プリント stdout への最終テキスト 1 回の呼び出し スクリプトがアシスタントの最終応答を必要とする場合
JSON stdout への JSONL イベント 1 回の呼び出し プロセスが実行中の進行状況を構造化形式で必要とする場合
RPC JSONL のコマンド、応答、イベント 長時間稼働 プロセスが双方向の制御を必要とする場合

CLI オプションでは、モードとは別に、作業ディレクトリ、モデル、ツール、リソース、セッションの永続化を引き続き選択できます。起動オプションの完全な一覧については、コマンドラインを参照してください。

プリントモードは、指定されたプロンプトを実行し、アシスタントの最終テキストを stdout に書き込んで終了します。

bash
pi --print "Summarize the changes in this repository"

コマンド置換、パイプライン、単発ジョブなど、最終テキストだけが必要な場合はプリントモードを使用します。中間イベントは公開されません。

プリントモードはエラーを stderr に書き込みます。停止理由が error または aborted であるアシスタントの最終応答では、終了ステータスが 0 以外になります。

モードを明示的に選択していない場合、stdin または stdout が非 TTY であれば、プリントモードが選択されます。これにより、--print を追加せずに入出力をパイプ処理できます。

JSON イベントをストリーミングする#

JSON モードは、セッションヘッダーに続けて、エージェントとセッションのイベントを改行区切りの JSON として書き込みます。

bash
pi --mode json "Review this repository" > events.jsonl

これは構造化されたイベント出力であり、単一の JSON 結果でも、モデルの応答形式に対する制約でもありません。

すべてのプロンプトはプロセスの開始時に指定されます。プロセスはその実行のイベントをストリーミングしてから終了し、後続のコマンドは受け付けません。

失敗または中止されたアシスタントの応答はイベントストリームに現れますが、それだけでは終了ステータスは 0 以外になりません。成功か失敗かが重要な場合は、イベントを確認してください。呼び出しでエラーがスローされた場合、Pi は引き続き 0 以外で終了します。

ストリーミングされる message_update レコードには、増大していくメッセージのスナップショットではなく差分が含まれます。差分イベントからリアルタイム出力を組み立てた後、message_end の正式なメッセージで置き換えてください。

agent_end の後に、自動復旧またはキューに登録された処理が続くことがあります。agent_settled は、現在の実行における自動処理の終了を示します。

stdout は JSONL 専用です。診断情報とアプリケーションログは stderr に書き込まれます。フレーミング、イベントの形式、再構築のルールについては、JSON イベントストリームを参照してください。

RPC で Pi を制御する#

RPC モードでは、別のプロセスがコマンドを送信して応答とイベントを受信している間、Pi は稼働し続けます。

bash
pi --mode rpc --no-session

コマンドは JSON オブジェクトとして stdin に書き込まれます。応答とイベントは JSON オブジェクトとして stdout に書き込まれます。各レコードは 1 行を占めます。

対応付けが必要なコマンドには id を追加してください。対応する応答では、その ID が繰り返されます。イベントは 1 つのリクエストではなくセッションのアクティビティを表すため、通常はコマンド ID を持ちません。

prompt の応答が成功であることは、プロンプトが受け付けられた、キューに登録された、または処理されたことを意味します。実行が完了したという意味ではありません。完了を確認する必要がある場合は、agent_settled までイベントの受信を続けてください。

RPC コマンドでは、モデルの変更、状態の確認、セッションの管理、シェルコマンドの実行、拡張機能の UI リクエストへの応答が可能です。

拡張機能のダイアログは、リクエスト・レスポンス方式のサブプロトコルを構成します。拡張機能によるその他の UI 更新は通知であり、クライアントは表示することも無視することもできます。拡張機能の機能のうち TUI 専用のものは、対話型モード以外では利用できないか、機能が制限されます。

Node.js または TypeScript との統合には、@earendil-works/pi-coding-agent の RpcClient の使用を推奨します。これは Pi RPC 子プロセスを起動し、リクエストを対応付け、型付きのコマンドメソッドを公開し、セッションイベントをリスナーに配信します。

RPC クライアントの例では、1 つのプロンプトを送信し、テキストとツールのアクティビティをストリーミングし、agent_settled を待ってから、子プロセスを終了します。この例は、リポジトリの TypeScript チェックに含まれています。

RpcClient.promptAndWait() はプロンプトを送信する前にイベントリスナーを設定し、短時間で完了した場合の競合を回避します。別々の操作として行う場合は、prompt() を呼び出す前に購読し、実行がアクティブな間だけ waitForIdle() を呼び出してください。

クライアントには、実行可能な Pi CLI へのパスが必要です。リポジトリの例は dist/cli.js を参照しているため、チェックアウトからその例を実行する前にパッケージをビルドする必要があります。

RpcClient を使用せずにクライアントを構築する場合は、まず RPC プロトコルを参照し、その後、通信仕様のリファレンスとして RPC コマンドと JSON イベントストリームを使用してください。

Pi をフォークしてブランドを変更する#

ソースコードのフォークでは、package.json を使用して CLI 名と設定ディレクトリを変更できます。

json
{
  "piConfig": {
    "name": "my-agent",
    "configDir": ".my-agent"
  }
}

実行可能ファイル名を設定するには、トップレベルの bin フィールドを変更します。これらの設定は、CLI バナー、設定パス、そこから派生する環境変数名に影響します。

例とリファレンス#

日本語やコマンド名で検索できます。