CLI commands and flags
Run pi --help to see all options. This page explains session working directories and the commands that pi-rust adds: pi completion, pi doctor, pi sessions, pi stats, pi extensions, the run limits, and structured output.
pi-rust also adds --fast. It turns on fast mode for one run. See Fast mode.
Shell completion
pi completion bash|zsh|fish|powershell prints a completion script. The script completes options, subcommands, and file paths. For --model and --provider, the script gets the models of the built-in catalog and models.json from pi.
To see how to install each script, run pi completion --help. Examples:
echo 'eval "$(pi completion bash)"' >> ~/.bashrc
pi completion fish > ~/.config/fish/completions/pi.fish
pi doctor
pi doctor prints a short report with these items:
- The version and the target.
- The installation method and path.
- Other
piprograms that come earlier onPATH, for example the npm pi. - Errors in
settings.json,models.json,auth.json, andmcp.json. - The providers that have credentials. The report shows their names and sources. It does not show the secrets.
- Model Context Protocol (MCP) servers whose commands are missing.
- The features that the terminal supports.
pi doctor --json prints the same report as JSON. pi doctor does not use the network and does not start MCP servers. If it finds a problem, it exits with code 1.
Session working directories
A session records the working directory where it was created. Tools, @path references, project configuration, and context files use the session’s working directory. If you open the session from another directory, its saved working directory does not change.
| Entry point | Working directory |
|---|---|
--continue, -c |
The current directory. Continues its most recent session. |
--resume, -r, or /resume |
The selected session’s saved working directory. |
--session <path|id> |
The session’s saved working directory. Accepts a file path or full or partial ID. |
/import |
The imported JSONL session’s saved working directory. Also preserves its ID. |
--session-id <id> |
The current directory. Opens its session with this exact ID, or creates one. |
--fork <path|id> |
The current directory, in a new session. Accepts a file path or full or partial ID. |
A --session ID found in another directory, when you choose to fork it |
The current directory, in a new session. |
If the saved directory no longer exists, interactive mode asks whether to use the current directory. This choice applies only to that run; it does not change the saved session header. Other modes return an error.
Sessions
pi sessions lists the saved sessions of the current project, newest first. For each session, it shows a short ID, the last activity, the number of messages, the cost, and the name or the first prompt.
| Option | Effect |
|---|---|
--all |
List the sessions of all projects. |
--limit <n> |
Show the newest n sessions. |
--json |
Print an array. |
To delete sessions, use these commands:
pi sessions rm <id-prefix|path>...deletes sessions by ID prefix or by file path. If a prefix matches more than one session, the command deletes nothing and lists the matches.pi sessions prune --older-than 30ddeletes the sessions that had no activity for that time. The units ares,m,h,d, andw. The command prints the number of bytes that it frees. With--dry-run, it shows the sessions that it can delete and does not delete them.
On a terminal, both commands ask before they delete. In other cases, they need --yes.
MCP sign-in commands
pi mcp login <server> [-l] [--timeout <seconds>] signs in to a configured OAuth server. The timeout covers the whole sign-in and defaults to 300 seconds. pi mcp logout <server> [-l] deletes its saved OAuth credentials.
For either command, -l or --local requires the server to come from the trusted project’s .pi/mcp.json. The command rejects a server that only the global config defines. Without this option, both commands use the configured server from either scope. If the server name is misspelled, the error suggests a close match when one exists.
pi mcp add <server> --lifecycle lazy ... adds a server that connects on first use. See MCP server lifecycle.
Usage stats
pi stats adds up the sessions of the current project. With --all, it adds up the sessions of all projects. It shows these totals:
- The number of sessions, prompts, and assistant turns.
- The input tokens, output tokens, cache tokens, and cost.
- The totals for each model and provider, and for each day of the last 14 days.
--since 7d counts only the recent activity. --json prints the report as JSON.
pi stats and pi sessions list only read session files. No session command uses the network. All session commands obey --session-dir, PI_CODING_AGENT_SESSION_DIR, and the sessionDir setting.
pi sessions --all --limit 10
pi sessions prune --older-than 30d --dry-run
pi stats --since 7d
Subscription limits
pi usage shows the limits of the subscription logins:
- Claude and ChatGPT (Codex): the 5-hour and weekly windows.
- Cursor: the billing cycle.
- The
xailogin: the weekly SuperGrok credits and Grok Build use. - Google Antigravity: the quota.
For each window, it shows the used percentage and the time to the reset.
pi usage <provider>shows one provider.--jsonprints{ "providers": [...] }in the shape of the native extension methodusage.get.- The exit code is 1 when every provider has an error.
pi usage
pi usage anthropic --json
Subscription usage limits lists the endpoints.
Run limits
| Flag | Effect |
|---|---|
--max-turns <n> |
Stops a run after n assistant responses to one prompt. Tool results do not count. The count starts at zero for each prompt. |
--max-cost <usd> |
Stops the run when the total cost of the session reaches the limit. This total is the same as the cost in the footer. After this limit stops a run, a new prompt does not start a run. |
Both limits apply in all modes, but only for the current process. A limit stops the run in the same way as Esc, after the tool results of the last turn. Thus the session file stays valid, and pi -c can continue it. If a run ends by itself on its last turn under the limit, pi does not stop it.
pi -p --max-turns 20 --max-cost 0.50 "Fix the failing tests"
# The exit code is 3 when a limit stopped the run.
echo $?
When a limit stops a run in print mode or in --mode json, pi does these steps:
- It writes a line such as
pi: stopped after 20 turns (--max-turns)to stderr. - It does not print the remaining messages.
- It exits with code 3.
JSON mode and remote procedure call (RPC) mode also send a run_limit event before agent_end:
{"type":"run_limit","limit":"maxTurns","max":20,"turns":20,"cost":0.1234,"message":"stopped after 20 turns (--max-turns)"}
The event has these fields:
limit:maxTurnsormaxCost.max: the limit.turns: the number of responses in the run.cost: the total cost of the session in US dollars.
If the cost limit stops a prompt before its run starts, pi sends only the event. An RPC prompt then gets the disposition handled. Interactive mode shows the message as a status line. If an extension registers its own --max-turns or --max-cost flag, the extension gets the value, as in upstream pi.
Structured output
--output-schema <file> makes the final answer in print mode a JSON value that matches a JSON Schema. Scripts can then read the answer. pi does these steps:
- It adds the schema to the system prompt.
- It checks the last response with the validator that it uses for tool arguments. It accepts one code fence around the JSON, such as
```json. - If the response is not valid JSON or does not match the schema, it sends the errors back in the same session. Then it asks for correct JSON.
--output-retries <n> sets the number of correction prompts that pi sends. The default is 1, and 0 sends none.
pi -p --output-schema review.schema.json \
"Review the diff in HEAD" > review.json
# The exit code is 4 when the answer still does not match.
echo $?
The results are as follows:
-
If the answer matches the schema, text mode prints only the JSON value, on one compact line.
--mode jsonends with anoutputevent:{"type":"output","value":{"verdict":"approve","issues":[]}} -
If the answer still does not match after the retries, pi writes the errors to stderr and exits with code 4. Text mode prints nothing to stdout.
-
After an error or an aborted response, pi exits with code 1.
-
After a run limit, pi exits with code 3. See Run limits.
Before pi starts, it checks the schema file. The file must be valid JSON. It must use only local $refs, and only keywords and patterns that the validator supports.
The flag works only in print mode: with -p, with --mode json, or when stdin or stdout is not a terminal. Interactive mode, RPC mode, and Agent Client Protocol (ACP) mode reject it. If an extension registers its own --output-schema or --output-retries flag, the extension gets the value.
Extensions
# List built-in and installed extensions, including disabled ones.
pi extensions list
pi extensions search todo
pi extensions info todo
pi extensions install marketplace:todo
# The source can also be a git URL or a local path.
pi extensions install npm:<package>
pi extensions disable builtin:mcp
pi extensions enable builtin:mcp
pi extensions remove npm:<package>
# Open a TUI to turn resources on and off.
pi config
- If a name matches more than one extension, use the exact path from
list. - To change the project-local settings, add
-l. Project changes need trust (--approve). - After a change, restart pi or run
/reload. - Third-party extensions are executable code. Install only sources that you trust.
- Use the marketplace to find native Rust extensions in the signed release catalog.
Extension runtime
pi-rust runs extensions on QuickJS by default. It can also run them on Node 22 or later.
# Run extensions on Node.
pi --extension-runtime node
# Use Node only for packages that need it.
pi --extension-runtime auto
# The same as --extension-runtime node, from the environment.
PI_EXTENSION_RUNTIME=node pi
# Use the node program at this path.
PI_NODE_PATH=/opt/node22/bin/node pi --extension-runtime node
| Value | Engine |
|---|---|
quickjs |
The embedded QuickJS engine. This is the default. |
node |
A node process. |
auto |
Node when a loaded package sets package.json pi.runtime: "node" or ships a .node addon. Otherwise QuickJS. |
- pi reads the choice from
--extension-runtime, thenPI_EXTENSION_RUNTIME, thenextensionRuntimein the project settings, then in the global settings. - pi finds
nodeinPI_NODE_PATH, then onPATH. - If Node is missing, older than version 22, or does not start, pi shows one warning and uses QuickJS.
See Node backend for how the backend works.