简体中文
·
English
·
日本語
·
한국어
# Pier 本機 CLI ユーザーマニュアル
`pier` は本機の Pier を操作します。プロジェクトを開く、ウインドウとパネルを探す、ターミナルを動かす、エージェントの状態を見る、git 作業ツリーを管理する、が対象です。リモート API ではなく、Claude Code、Codex、OpenCode など各ツール本体のコマンドラインの代わりにもなりません。
> 本ページは GitHub で読める入口です。アプリ内の検索できるマニュアルは [`pier-cli-user-manual.canvas.tsx`](./pier-cli-user-manual.canvas.tsx) と [`data.json`](./data.json) です（現在は簡体字中国語）。ここにある戻り値は読むための例です。スクリプトは現行の `--json` 応答の `ok`、`data`、`error` を見てください。
## 60 秒で始める
正式インストールパッケージの `pier` は、アプリが動いていなければ先に起動してから実行します。リリース版は Shell の `PATH` を書き換えません。Pier が標準の `/Applications` にある場合は、先に現在のターミナルで次を実行します。
```bash
export PATH="/Applications/Pier.app/Contents/Resources/bin:$PATH"
```
アプリが `~/Applications` にある場合は、パスを `$HOME/Applications/Pier.app/Contents/Resources/bin` に変えます。そのあと実行します。
```bash
# 1. 本機の Pier に接続できているか確認
pier status --json
# 2. 現在のプロジェクトを Pier で開く（同じ作業ディレクトリの通常ターミナルがあればフォーカス）
pier . --json
# 3. ウインドウとパネルを見る
pier windows list --json
pier panels list --json
# 4. Pier が知る製品と、実行中のエージェントを見る
pier agents catalog --json
pier agents list --json
```
`PATH` を変えず、`/Applications/Pier.app/Contents/Resources/bin/pier <コマンド…>` を直接実行しても構いません。ソースから開発しているときは：
```bash
pnpm --silent cli:dev -- status --json
```
`node ./bin/pier.mjs <コマンド…>` を直接実行することもできます。
## よく使うオプション
| オプション | 意味 |
| --- | --- |
| `--json` | 安定した JSON を出す。スクリプトは常に付ける |
| `--print-envelope` | 送る予定のリクエストだけ印刷し、実行しない |
| `--no-focus` | Pier のウインドウを前面に出さないようにする |
| `--window ` | ウインドウを指定する。先に `pier windows list --json` で調べる |
成功応答は `ok: true` と `data` を含みます。失敗応答は `ok: false`、エラーコード、人が読めるメッセージを含みます。
## プロジェクトを開いてパネルを整える
```bash
# 現在のディレクトリを開く。同じ作業ディレクトリの通常ターミナルがあればフォーカス、なければ新規
pier . --json
# 指定ディレクトリを開く。現在の配置の右側に分割して足すこともできる
pier open /path/to/repo --json
pier open . --split right --json
# ファイルを開く（既に開いていればタブを再利用。:行[:列] を付けられる）
pier src/app.ts:12 --json
# パネルを探してフォーカス
pier panels list --json
pier panels focus --json
# ターミナルを新規に開く（常に新規。再利用しない）
pier terminal open --cwd . --json
pier terminal open --cwd . --json -- claude
```
ターミナルを探すコマンドは、ターミナルの全内容を返しません。
```bash
pier terminal list --json
pier terminal get --panel --json
```
通常の Shell ターミナルには、テキストやキーを送れます。
```bash
pier terminal send --panel --text "pnpm test" --json
pier terminal key --panel --key enter --json
```
エージェントパネルでは、次節の `agents turn`、`agents interrupt`、`agents terminate` を使います。通常のターミナルコマンドで実行状態を迂回しないでください。
## エージェントを実行して見る
先に Pier が知るエージェント一覧を見てから、継続して動くセッションを開始します。
```bash
pier agents catalog --json
pier agents start --agent codex --cwd . --json
```
`agents start` は `bootId`、`runtimeId`、`generation`、`panelId` を返します。以降のコマンドはこの実行参照を使います。
```bash
pier agents turn \
--boot \
--runtime \
--generation \
--text "現在の変更を確認してテストを実行" \
--json
pier agents wait \
--boot \
--runtime \
--generation \
--until attention \
--json
```
よく使う照会と操作は次のとおりです。表の `<実行参照>` は、同じ `--boot --runtime --generation ` の組です。
| コマンド | 用途 |
| --- | --- |
| `pier agents list --json` | 実行中のエージェントパネルを一覧 |
| `pier agents get --panel --json` | 実行中のインスタンスを照会 |
| `pier agents screen <実行参照> --json` | いま見えているターミナル領域を読む。会話全体ではない |
| `pier agents watch <実行参照> --json` | 実行状態の変化を受け取り続ける |
| `pier agents focus <実行参照> --json` | 対応するパネルに戻る |
| `pier agents interrupt <実行参照> --json` | 現在の実行を中断 |
| `pier agents terminate <実行参照> --json` | その実行インスタンスを終了 |
`accepted: true` は入力が届いたことだけを表し、作業が終わったことではありません。`agents wait` は `ready`、`waiting`、`exited`、`attention` を待ちます。`agents watch` は状態変化を観察します。最終結果はエージェント自身の出力です。
最初のタスクは、確認済みのネイティブ対話型起動引数で渡します。未対応のコマンドや未確認のバージョンでは、拡張入力欄に下書きとして保存し、手動送信を待ちます。`inputDisposition` は `native-launch`、`draft`、`unconfirmed` のいずれかです。`creationStatus: unconfirmed` の場合は、重複起動する前にパネルを確認してください。ネイティブの承認はターミナルで手動で行います。
未送信の下書きは添付ファイルと編集形式を含めて保存され、再起動後に復元されます。送信が中断した場合は要確認となり、自動再送しません。`agents turn` は末尾の改行も保持し、送信前にチェックポイントを保存します。受理は転送の確認に限ります。
`agents interrupt` はネイティブ Ctrl+C を送ります。`agents terminate` は TERM、2 秒後に KILL を送り、宿主が起動したプロセスの終了を最大 10 秒待ちます。タイムアウトはエラーです。停止後もアプリ終了まではパネルと出力を閲覧・コピーできます。パネルを閉じるには `terminal close` を使います。ターミナルから独立したサービスの回収や、タスクの成功を保証するものではありません。
## git 作業ツリー
```bash
# リポジトリ内の作業ツリーを照会
pier worktrees list --path /path/to/repo --json
# 独立した作業ツリーを作って開く
pier worktrees create \
--path /path/to/repo \
--name retry-policy \
--branch feature/retry-policy \
--base main \
--json
pier worktrees open /path/to/retry-policy --json
# 作業ツリーを検査または照会
pier worktrees check --path /path/to/retry-policy --json
pier worktrees get --path /path/to/retry-policy --json
```
Pier が管理する作業ツリーを削除する前に、Pier は活発な実行と未コミットの変更を確認します。
```bash
pier worktrees remove --path /path/to/retry-policy --json
```
## Shell タスク
ここでのタスクは、プロジェクトに設定した build、test などの Shell 実行です。タスク台帳や自動スケジューラではありません。
```bash
pier tasks list --path . --json
pier tasks run --path . --json
pier tasks status --json
pier tasks output --json
pier tasks stop --json
pier tasks cancel --json
```
## 通知、設定、プラグイン
```bash
# 通知
pier notifications list --unread --json
pier notifications get --id --json
pier notifications focus --id --json
pier notifications mark-read --id --json
# 読み取り専用の設定とプラグイン情報
pier preferences read --json
pier plugins list --json
pier plugins inspect --json
```
プラグインの有効化と無効化は Pier の「設定 → プラグイン」で行います。本機 CLI にこの書き込み権限はありません。
## 接続のトラブルシュート
- Pier アプリが起動していることを確認してください。`pier` コマンドが入っているだけでは不十分です。
- 開発時は `pnpm --silent cli:dev -- <コマンド…>` を使い、インストール版へ誤接続しないでください。
- ウインドウが複数あるときは、先に `pier windows list --json` を実行してから `--window ` を渡します。
- スクリプトは `ok` と `error.code` を見てください。人向けの出力テキストに依存しないでください。
- `agents wait` のタイムアウトは、エージェントが失敗したことと同じではありません。`agents get` または `agents watch` で状態を照会し続けられます。
コマンドのより詳しいグループ分けと状態は [`data.json`](./data.json) を見てください。Pier の Files パネルで [`pier-cli-user-manual.canvas.tsx`](./pier-cli-user-manual.canvas.tsx) を開くと、検索できるアプリ内マニュアルも使えます。