Pi coding agent cheatsheet

Pi is a small coding-agent harness whose defaults are intentionally inspectable: the installed v1.4.0 binary exposes read, bash, edit, and write, while skills, extensions, prompt templates, and packages add capability. This page separates facts read from pi --help from behavior documented in the official repository.

The verification date is 2026-10-23. Treat project-local settings and extensions as executable input: review them before approving or automating a run.

Command drill

16 verified Pi coding agent commands. Read the task, type the command, press Enter. Every answer is on this page's tables - this drill only asks what the verified data already states.

Answer key - all 16 commands

Print the installed Pi version. pi --version
Start an interactive session in the current directory. pi
Continue the previous session for this project. pi --continue
Choose a session to resume. pi --resume
Run ephemerally without saving the session. pi --no-session
Override where sessions are stored and found. pi --session-dir ./tmp/pi-sessions
Show the active session file, ID, messages, tokens, and cost. /session
Navigate to an earlier point and continue from that branch. /tree
Run the line-oriented JSON RPC interface without persisting a session. pi --mode rpc --no-session
Export a session file to HTML. pi --export session.jsonl output.html
Check whether a provider's credentials are ready; refreshes expired OAuth unless `--no-refresh`. pi auth check --provider openai
Print an API key for an external client. pi auth print-api-key --provider openai
Switch models inside an interactive session. /model
Enable or disable models used by Ctrl+P cycling. /scoped-models
Open the TUI for enabling/disabling package resources. pi config
Edit common interactive settings. /settings

78 commands · verified against the installed binary v1.4.0 and the official docs · checked 2026-10-23 source source source source source

Install & session

Get Pi running, preserve the conversation you care about, and keep session files explicit.

Command	What it does	Notes
`npm install -g --ignore-scripts @earendil-works/pi-coding-agent` docs	Install the Pi coding agent globally.
`pi --version`	Print the installed Pi version.
`pi`	Start an interactive session in the current directory.
`pi "Inspect the auth flow"`	Start interactively with an initial prompt.
`pi @prompt.md @image.png "Review these"`	Attach files to the initial message with @ references.	Use a path Pi can read; image support depends on the provider/model.
`pi --continue`	Continue the previous session for this project.
`pi --resume`	Choose a session to resume.
`pi --session <path\|id>`	Use a particular session file or partial UUID.
`pi --fork <path\|id>`	Fork a session into a new branch/session.
`pi --session-id <id>`	Use an exact project session ID, creating it if missing.
`pi --name "Refactor auth"`	Set a display name for the session.
`pi --no-session`	Run ephemerally without saving the session.	Use this for disposable automation, not work you may need to resume.
`pi --session-dir ./tmp/pi-sessions`	Override where sessions are stored and found.
`/session`	Show the active session file, ID, messages, tokens, and cost.
`/tree`	Navigate to an earlier point and continue from that branch.

Print & headless

Use stdout-friendly modes for scripts, CI, and another process driving Pi.

Command	What it does	Notes
`pi -p "List TODOs"`	Process a prompt non-interactively and exit.	Short form of `--print`.
`pi --mode text -p "Summarize"`	Select ordinary text output explicitly.
`pi --mode json -p "Review package.json"`	Emit the JSON event stream for a headless consumer.	JSON mode is an event stream; use RPC when you need bidirectional control.
`pi --mode rpc --no-session`	Run the line-oriented JSON RPC interface without persisting a session.
`pi --export session.jsonl output.html`	Export a session file to HTML.
`pi --offline -p "Explain this file"`	Disable startup network operations.	This does not make a provider request offline; it only disables Pi startup network work.
`pi --no-tools -p "Answer from context only"`	Disable built-in and extension tools by default.
`pi --tools read,grep,find,ls -p "Review src/"`	Allowlist read-only tools for a review run.	grep/find/ls are read-only built-ins but are off by default.

Provider & model

Choose credentials, model routing, thinking depth, and the models available to cycle.

Command	What it does	Notes
`pi auth <command>`	Print credentials or check provider readiness.
`pi auth check --provider openai`	Check whether a provider's credentials are ready; refreshes expired OAuth unless `--no-refresh`.
`pi auth print-api-key --provider openai`	Print an API key for an external client.
`pi auth print-bearer-token --provider openai-codex`	Print or refresh an OAuth bearer token.
`pi --provider openai --model gpt-4o "Refactor this"`	Choose a provider and model for one run.
`pi --model openai/gpt-4o "Refactor this"`	Use the provider/model-qualified ID without a separate provider flag.
`pi --thinking high "Solve this carefully"`	Set thinking level: off, minimal, low, medium, high, xhigh, or max.
`pi --models "anthropic/,openai/"`	Limit Ctrl+P model cycling to matching patterns.	Patterns support globs and fuzzy matching; a model may also carry `:thinking`.
`/model`	Switch models inside an interactive session.
`/scoped-models`	Enable or disable models used by Ctrl+P cycling.
`export ANTHROPIC_API_KEY=…`	Provide a provider credential through its documented environment variable.	Pi also supports OAuth/login and many provider-specific variables; never commit secrets.

Settings & keybindings

Put durable preferences in the right scope and discover or remap the TUI controls.

Command	What it does	Notes
`pi config`	Open the TUI for enabling/disabling package resources.	Tab switches between scopes.
`/settings`	Edit common interactive settings.
`~/.pi/agent/settings.json` docs	Global settings for all projects.
`.pi/settings.json` docs	Project settings that override global settings.	Nested objects merge; project-local resources may trigger a trust prompt.
`~/.pi/agent/keybindings.json` docs	Customize interactive keybindings.
`/hotkeys`	Show the full active keyboard shortcut list.
`Ctrl+L / Ctrl+P / Shift+Tab` docs	Open the model selector / cycle models / cycle thinking level.
`Escape / Escape twice` docs	Cancel the current operation / open the session tree.
`Ctrl+O / Ctrl+T` docs	Collapse tool output / thinking blocks.

Extensions, skills & packages

Extend Pi deliberately: skills guide the model, extensions add code, and packages distribute resources.

Command	What it does	Notes
`pi install npm:@org/[email protected]`	Install an extension/package and add it to settings.	Use `-l` for project-local installation.
`pi install git:github.com/org/repo@v1`	Install a package from a Git source.
`pi list`	List installed packages and resources from user and project settings.
`pi update [source\|self\|pi]`	Update Pi itself (the default), one named package, or - with flags - installed packages or model catalogs.	Bare `pi update` updates Pi only. `--extensions` updates installed packages only, `--all` updates Pi and packages, `--models` refreshes model catalogs, `--force` reinstalls Pi.
`pi mcp list`	Show MCP server state, tools, and errors without starting a session.	Also `pi mcp add\|remove\|login\|logout`; config lives in `~/.pi/agent/mcp.json` or, in trusted projects, `.pi/mcp.json`. `--no-mcp` disables MCP for a run.
`pi remove <source>`	Remove a package source from settings.	Alias: `pi uninstall`; add `-l` for project scope.
`pi -e ./extension.ts`	Load an extension source for one run.	Paths, npm, and git sources are supported; use auto-discovered locations for extensions you keep.
`pi --skill ./skills/review`	Load a skill file or directory for one run.
`pi --no-extensions --no-skills`	Disable extension discovery and skills discovery.	Explicit `-e` paths still load when discovery is disabled.
`~/.pi/agent/extensions/ · .pi/extensions/` docs	Global and project-local auto-discovery locations for TypeScript extensions.
`~/.pi/agent/skills/ · ~/.agents/skills/ · .pi/skills/ · .agents/skills/` docs	Common user and project skill locations; project `.agents/skills/` directories are also searched through ancestors.
`/skill:<name>`	Invoke a loaded skill as a slash command.	Skill commands are enabled by default via `enableSkillCommands`.
`/reload`	Reload keybindings, extensions, skills, prompts, themes, and context files.

Compaction & context

Keep long sessions useful by understanding what is loaded, summarized, and retained.

Command	What it does	Notes
`/compact [instructions]`	Manually summarize older context, optionally steering the summary.
`compaction.enabled: true` docs	Enable automatic compaction when context approaches its limit.
`compaction.reserveTokens: 16384` docs	Reserve response space before auto-compaction triggers.
`compaction.keepRecentTokens: 20000` docs	Keep roughly this many recent tokens out of the summary.
`/tree`	Navigate branches; Pi can summarize a branch when switching context.
`pi --no-context-files`	Disable discovery/loading of AGENTS.md, AGENTS.override.md, and CLAUDE.md files.	This is useful for isolating unexpected project instructions.
`AGENTS.md / CLAUDE.md`	Context files Pi discovers and loads unless disabled.

RPC & automation

Drive Pi from another process while retaining structured control over prompts, events, and session state.

Command	What it does	Notes
`pi --mode rpc --no-session` docs	Start the JSON-lines RPC process for a language-agnostic client.
`{"type":"prompt","message":"Run tests"}` docs	Send a prompt message to an RPC session.	The RPC client owns the UI; do not assume interactive TUI commands work over RPC.
`{"type":"compact","customInstructions":"Keep commands and failures"}` docs	Request compaction over RPC with custom instructions.
`get_commands` docs	RPC command for discovering extension, prompt-template, and skill commands.
`--mode json`	Emit a one-way JSON event stream; extensions run without interactive UI.	For bidirectional automation, use RPC.
`PI_CODING_AGENT_DIR=…`	Override Pi’s config directory (default `~/.pi/agent`).
`PI_CODING_AGENT_SESSION_DIR=…`	Set the session storage directory unless `--session-dir` overrides it.
`PI_OFFLINE=1`	Disable startup network operations.

Safety caveats

The useful defaults are powerful; make trust boundaries and tool access explicit before automation.

Command	What it does	Notes
`pi --approve`	Trust project-local files and resources for this run.	This is project trust, not a sandbox or command-approval mechanism. Only use when you have inspected project-local settings, skills, and extensions.
`pi --no-approve`	Ignore trust-protected project-local files and resources for this run.	This is project trust, not a sandbox or command-approval mechanism.
`pi --exclude-tools bash,write`	Denylist dangerous tools while retaining the rest.
`pi --no-builtin-tools`	Disable built-in tools while retaining extension/custom tools.	That can still leave powerful extension tools available.
`pi --no-context-files --no-extensions --no-skills`	Start with project instructions and customization discovery disabled.	Use as a troubleshooting/isolation baseline, not as a security guarantee.
inspect before `pi install` docs	Review package source and pin a trusted version before installing.	Official docs warn that extensions run with full system permissions and can execute arbitrary code.
`never commit API keys or session files` docs	Keep credentials and potentially sensitive transcripts outside source control.	`/share` uploads a private GitHub gist; private does not mean safe for secrets.