Pi の使い方

本ページでは、クイックスタートには載せきれない日常の使い方をまとめています。

対話モード

インターフェースには 4 つの主要エリアがあります：

• 起動ヘッダー - ショートカット、読み込まれたコンテキストファイル、プロンプトテンプレート、スキル、拡張機能
• メッセージ - ユーザーメッセージ、アシスタント応答、ツール呼び出し、ツール結果、通知、エラー、拡張 UI
• エディター - 入力欄。枠線の色は現在の思考レベルを示す
• フッター - 作業ディレクトリ、セッション名、トークン/キャッシュ使用量、コスト、コンテキスト使用量、現在のモデル

エディターは /settings などの組み込み UI やカスタム拡張 UI によって一時的に置き換えられます。

エディター機能

機能	方法
ファイル参照	@ を入力してプロジェクトファイルをあいまい検索
パス補完	Tab でパスを補完
複数行入力	Shift+Enter、または Windows Terminal では Ctrl+Enter
画像	Ctrl+V で貼り付け、Windows では Alt+V、またはターミナルへドラッグ
Shell コマンド	!command を実行し出力をモデルへ送信
非表示 Shell コマンド	!!command を実行するが出力はモデルへ送信しない
外部エディター	Ctrl+G で $VISUAL または $EDITOR を開く

すべてのショートカットとカスタマイズは Keybindings を参照してください。

スラッシュコマンド

エディターで / を入力するとコマンド補完が開きます。拡張機能はカスタムコマンドを登録でき、スキルは /skill:name、プロンプトテンプレートは /templatename で展開されます。

コマンド	説明
/login、/logout	OAuth または API キー認証情報を管理
/model	モデルを切り替え
/scoped-models	Ctrl+P サイクル用モデルの有効/無効
/settings	思考レベル、テーマ、メッセージ配信、トランスポート
/resume	過去のセッションから選択
/new	新しいセッションを開始
/name <name>	セッション表示名を設定
/session	セッションファイル、ID、メッセージ、トークン、コストを表示
/tree	セッション内の任意の地点へジャンプしてそこから続行
/fork	過去のユーザーメッセージから新しいセッションを作成
/clone	現在のアクティブブランチを新しいセッションに複製
/compact [prompt]	コンテキストを手動で圧縮。任意でカスタム指示
/copy	最後のアシスタントメッセージをクリップボードにコピー
/export [file]	セッションを HTML にエクスポート
/share	非公開 GitHub gist にアップロードし共有可能な HTML リンクを取得
/reload	キーバインド、拡張、スキル、プロンプト、コンテキストファイルを再読み込み
/hotkeys	すべてのキーボードショートカットを表示
/changelog	バージョン履歴を表示
/quit	pi を終了

メッセージキュー

エージェントがまだ作業中でもメッセージを送信できます：

• Enter はステアリングメッセージをキューに入れ、現在のアシスタントターンがツール呼び出しの実行を終えた後に配信されます。
• Alt+Enter はフォローアップメッセージをキューに入れ、エージェントがすべての作業を終えた後に配信されます。
• Escape は中止し、キュー内のメッセージをエディターに戻します。
• Alt+Up はキュー内のメッセージをエディターに取り戻します。

Windows Terminal では Alt+Enter はデフォルトで全画面表示です。pi がそのショートカットを受け取るには、Terminal setup の説明に従って再マップしてください。

配信は Settings の steeringMode と followUpMode で設定します。

セッション

セッションは作業ディレクトリごとに整理され、~/.pi/agent/sessions/ に自動保存されます。

pi -c                  # 直近のセッションを続行
pi -r                  # セッションを閲覧して選択
pi --no-session        # 一時モード。保存しない
pi --name "my task"    # 起動時にセッション表示名を設定
pi --session <path|id> # 特定のセッションファイルまたはセッション ID を使用
pi --fork <path|id>    # セッションを新しいセッションファイルにフォーク

便利なセッションコマンド：

• /session は現在のセッションファイルと ID を表示します。
• /tree はファイル内のセッションツリーを移動し、放棄されたブランチを要約できます。
• /fork はより前のユーザーメッセージから新しいセッションを作成します。
• /clone は現在のアクティブブランチを新しいセッションファイルに複製します。
• /compact は古いメッセージを要約してコンテキストを解放します。

詳細は Sessions と Compaction を参照してください。

コンテキストファイル

Pi は起動時に次の場所から AGENTS.md または CLAUDE.md を読み込みます：

• グローバル指示用の ~/.pi/agent/AGENTS.md
• 現在の作業ディレクトリから上へたどる親ディレクトリ
• 現在のディレクトリ

コンテキストファイルには、プロジェクトの規約、コマンド、安全ルール、設定を記載します。--no-context-files または -nc で読み込みを無効にできます。

システムプロンプトファイル

デフォルトのシステムプロンプトは次で置き換えられます：

• プロジェクト用の .pi/SYSTEM.md
• グローバル用の ~/.pi/agent/SYSTEM.md

いずれかの場所の APPEND_SYSTEM.md で、デフォルトを置き換えずに追記できます。

プロジェクト信頼

対話起動時、プロジェクトローカルの設定、リソース、またはプロジェクト .agents/skills を含むプロジェクトフォルダがあり、~/.pi/agent/trust.json にそのフォルダまたは親フォルダの保存済み決定がない場合、pi は信頼する前に確認します。

プロジェクトを信頼すると、pi は .pi/settings.json と .pi リソースの読み込み、不足しているプロジェクトパッケージのインストール、プロジェクト拡張の実行が可能になります。

信頼決定の前に、pi はコンテキストファイル、ユーザー/グローバル拡張、CLI -e 拡張のみを読み込み、project_trust イベントを処理できるようにします。プロジェクトローカル拡張、プロジェクトパッケージ管理の拡張、プロジェクト設定は、プロジェクトが信頼された後にのみ読み込まれます。信頼が現在のプロセスで未解決の別 cwd のセッションに切り替える場合も同様です。

非対話モード（-p、--mode json、--mode rpc）では信頼プロンプトは表示されません。適用可能な保存済み信頼決定がない場合、グローバル設定の defaultProjectTrust を使用します：ask（デフォルト）と never はそれらのプロジェクトリソースを無視し、always は信頼します。--approve/-a または --no-approve/-na で 1 回の実行のプロジェクト信頼を上書きできます。

拡張または保存済み決定が適用されない場合、defaultProjectTrust がフォールバック動作を制御します。~/.pi/agent/settings.json で "ask"、"always"、"never" に設定するか、/settings で変更してください。

pi config とパッケージコマンドは同じプロジェクト信頼フローを使用しますが、pi update はプロンプトしません。--approve で 1 コマンド分プロジェクトローカル設定を信頼するか、--no-approve で無視します。

対話モードで /trust を使うと、直接の親フォルダの信頼を含め、将来のセッション用にプロジェクト信頼決定を保存できます。書き込むのは ~/.pi/agent/trust.json のみです。現在のセッションは再読み込みされないため、変更を反映するには pi を再起動してください。

セッションのエクスポートと共有

/export [file] でセッションを HTML に書き出します。

/share で非公開 GitHub gist にアップロードし、共有可能な HTML リンクを取得します。

オープンソース作業で pi を使い、モデル、プロンプト、ツール、評価研究用にセッションを公開したい場合は badlogic/pi-share-hf を参照してください。Hugging Face データセットにセッションを公開します。

CLI リファレンス

pi [options] [@files...] [messages...]

パッケージコマンド

pi install <source> [-l]     # パッケージをインストール。-l はプロジェクトローカル
pi remove <source> [-l]      # パッケージを削除
pi uninstall <source> [-l]   # remove のエイリアス
pi update [source|self|pi]   # pi のみ、または 1 つのパッケージソースを更新
pi update --all              # pi とパッケージを更新。固定 git ref を調整
pi update --extensions       # パッケージのみ更新。固定 git ref を調整
pi update --self             # pi のみ更新
pi update --extension <src>  # 1 つのパッケージを更新
pi list                      # インストール済みパッケージを一覧
pi config                    # パッケージリソースの有効/無効

これらのコマンドは pi パッケージを管理し、pi update は pi CLI インストール自体も更新できます。pi 自体をアンインストールするには Quickstart を参照してください。pi config とプロジェクトパッケージコマンドは --approve/--no-approve を受け付け、1 コマンド分プロジェクトローカル設定を信頼または無視します。pi update はプロジェクト信頼をプロンプトしません。

パッケージソースとセキュリティに関する注意は Pi Packages を参照してください。

モード

フラグ	説明
default	対話モード
-p、--print	応答を表示して終了
--mode json	すべてのイベントを JSON 行で出力。JSON mode を参照
--mode rpc	stdin/stdout 経由の RPC モード。RPC mode を参照
--export <in> [out]	セッションを HTML にエクスポート

print モードでは、pi はパイプされた stdin も読み取り、初期プロンプトにマージします：

cat README.md | pi -p "Summarize this text"

モデルオプション

オプション	説明
--provider <name>	anthropic、openai、google などのプロバイダー
--model <pattern>	モデルパターンまたは ID。provider/id と任意の :<thinking> をサポート
--api-key <key>	環境変数を上書きする API キー
--thinking <level>	off、minimal、low、medium、high、xhigh
--models <patterns>	Ctrl+P サイクル用のカンマ区切りパターン
--list-models [search]	利用可能なモデルを一覧

セッションオプション

オプション	説明
-c、--continue	直近のセッションを続行
-r、--resume	セッションを閲覧して選択
--session <path|id>	特定のセッションファイルまたは部分 UUID を使用
--fork <path|id>	セッションファイルまたは部分 UUID を新しいセッションにフォーク
--session-dir <dir>	カスタムセッション保存ディレクトリ
--no-session	一時モード。保存しない
--name <name>、-n <name>	起動時にセッション表示名を設定

ツールオプション

オプション	説明
--tools <list>、-t <list>	特定の組み込み、拡張、カスタムツールを許可リスト
--exclude-tools <list>、-xt <list>	特定の組み込み、拡張、カスタムツールを無効化
--no-builtin-tools、-nbt	組み込みツールを無効化。拡張/カスタムツールは有効のまま
--no-tools、-nt	すべてのツールを無効化

組み込みツール：read、bash、edit、write、grep、find、ls。

リソースオプション

オプション	説明
-e、--extension <source>	パス、npm、git から拡張を読み込み。繰り返し可能
--no-extensions	拡張の自動検出を無効化
--skill <path>	スキルを読み込み。繰り返し可能
--no-skills	スキルの自動検出を無効化
--prompt-template <path>	プロンプトテンプレートを読み込み。繰り返し可能
--no-prompt-templates	プロンプトテンプレートの自動検出を無効化
--theme <path>	テーマを読み込み。繰り返し可能
--no-themes	テーマの自動検出を無効化
--no-context-files、-nc	AGENTS.md と CLAUDE.md の自動検出を無効化

--no-* と明示的フラグを組み合わせ、設定を無視して必要なものだけを読み込めます。例：

pi --no-extensions -e ./my-extension.ts

その他のオプション

オプション	説明
--system-prompt <text>	デフォルトプロンプトを置換。コンテキストファイルとスキルは引き続き追記
--append-system-prompt <text>	システムプロンプトに追記
--verbose	詳細起動を強制
-a、--approve	この実行でプロジェクトローカルファイルを信頼
-na、--no-approve	この実行でプロジェクトローカルファイルを無視
-h、--help	ヘルプを表示
-v、--version	バージョンを表示

ファイル引数

ファイルの前に @ を付けてメッセージに含めます：

pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"

例

# 初期プロンプト付き対話
pi "List all .ts files in src/"

# 非対話
pi -p "Summarize this codebase"

# パイプ stdin 付き非対話
cat README.md | pi -p "Summarize this text"

# 名前付きワンショットセッション
pi --name "release audit" -p "Audit this repository"

# 別モデル
pi --provider openai --model gpt-4o "Help me refactor"

# プロバイダープレフィックス付きモデル
pi --model openai/gpt-4o "Help me refactor"

# 思考レベル省略記法付きモデル
pi --model sonnet:high "Solve this complex problem"

# モデルサイクルを制限
pi --models "claude-*,gpt-4o"

# 読み取り専用モード
pi --tools read,grep,find,ls -p "Review the code"

# 1 つの拡張または組み込みツールを無効化し、残りは利用可能
pi --exclude-tools ask_question

環境変数

変数	説明
PI_CODING_AGENT_DIR	設定ディレクトリを上書き。デフォルトは ~/.pi/agent
PI_CODING_AGENT_SESSION_DIR	セッション保存ディレクトリを上書き。--session-dir で上書きされる
PI_PACKAGE_DIR	パッケージディレクトリを上書き。Nix/Guix store パスに有用
PI_OFFLINE	起動時のネットワーク操作（更新チェック、パッケージ更新チェック、インストール/更新テレメトリ）を無効化
PI_SKIP_VERSION_CHECK	起動時の Pi バージョン更新チェックをスキップ。pi.dev への最新バージョン要求を防ぐ
PI_TELEMETRY	インストール/更新テレメトリとプロバイダー帰属ヘッダーを上書き：1/true/yes または 0/false/no。更新チェックは無効化しない
PI_CACHE_RETENTION	サポートされる環境で long に設定するとプロンプトキャッシュを延長
VISUAL、EDITOR	Ctrl+G 用の外部エディター

設計原則

Pi はコアを小さく保ち、ワークフロー固有の動作は拡張、スキル、プロンプトテンプレート、パッケージに委ねます。

組み込み MCP、サブエージェント、権限ポップアップ、プランモード、To-do、バックグラウンド bash は意図的に含まれません。それらのワークフローは拡張やパッケージとして構築・インストールするか、コンテナや tmux などの外部ツールを使えます。

詳細な理由はブログ記事をお読みください。