Pi Agent Harnessv0.84.3 · verified August 26, 2026

Pi Coding Agent Cheatsheet

A practical map of Pi's deliberately small core and programmable command surface: CLI modes and flags, 23 built-in slash commands, Session Tree branching, Pi Packages, Extensions, Skills, prompt templates, special shell input, and JSONL RPC.

View the command map Explore Session Tree

minimal core · infinite surface

$ pi --model sonnet:high

session: tree-native JSONL

tools: read bash edit write

extensions: programmable

/tree

├─ approach A

│ └─ active branch

└─ approach B

▌

Core, bundled, and dynamic capabilities are labeled separately.

The essential mental model

Pi has six command surfaces, not one

The built-in CLI and slash registry are intentionally small. The installed surface grows through Extensions, Skills, prompt templates, Packages, and programmatic clients.

CLI and options

Launch Pi interactively, print one response, stream JSON events, or run the JSONL RPC protocol.

Core slash commands

Twenty-three built-in commands cover models, sessions, sharing, trust, reloads, and configuration.

Special input

Use @ for files, ! for shell output the model can see, and !! for local-only shell output.

Dynamic commands

Prompt templates, Skills, and Extensions expand the command surface at runtime.

Pi Packages

Install bundles of Extensions, Skills, prompts, and themes from npm, git, or a local path.

RPC protocol

Control prompts, queues, models, thinking, bash, compaction, and session trees over stdin/stdout.

Package migration

The current package is @earendil-works/pi-coding-agent. The former @mariozechner/pi-coding-agent package is deprecated at 0.73.1 and points users to Earendil Works.

Complete overview

Pi command map

The tree separates fixed CLI commands, runtime modes, core slash commands, bundled llama.cpp support, dynamic resources, and special input.

Pi command map

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

CLI commands
├── install <source>
├── remove <source>
├── uninstall <source>               # alias: remove
├── update [source|self|pi]
├── list
├── config
└── auth
    ├── check
    ├── print-api-key
    └── print-bearer-token

Runtime modes
├── interactive                      # default TUI
├── text                             # pi -p / --mode text
├── json                             # event stream
└── rpc                              # stdin/stdout JSONL

Core slash commands
├── /settings      /model            /thinking
├── /scoped-models /login            /logout
├── /new           /resume           /name
├── /session       /tree             /fork
├── /clone         /compact          /copy
├── /export        /import           /share
├── /trust         /reload           /hotkeys
├── /changelog     /quit
└── /llama                           # bundled extension

Dynamic command surface
├── /<prompt-template>
├── /skill:<skill-name>
├── /<extension-command>
└── --<extension-flag>

Special input
├── @file                             # attach file or image
├── !command                          # execute + add output to context
└── !!command                         # execute without LLM context

Quick start

Commands worth memorizing first

These cover interactive work, one-shot automation, continuation, read-only review, tree navigation, and process integration.

Open the TUI

pi

Start an interactive Pi session in the current project.

One-shot task

pi -p "Fix the TypeScript errors"

Process a prompt non-interactively, print the result, and exit.

Continue recent work

pi -c "Continue the implementation"

Resume the most recent project session with a new message.

Read-only review

pi --tools read,grep,find,ls -p "Review this repository"

Limit Pi to the built-in read-only tools for a safer review pass.

Explore a branch

/tree

Jump to an earlier session node and continue on a new branch.

Embed as a process

pi --mode rpc

Control Pi over line-delimited JSON through stdin and stdout.

pi

Interactive

Full terminal UI with slash commands, selectors, and session navigation.

pi -p "..."

Print / text

Run one task, print the assistant response, and exit for shell automation.

pi --mode json "..."

JSON events

Emit the agent event stream as JSON lines for pipelines and log processors.

pi --mode rpc

RPC

Keep Pi alive as a controlled subprocess using stdin/stdout JSONL commands.

CLI options

Control models, sessions, tools, and resources

All rows here are registered by the core parser. Extensions may append additional long flags to the local help output.

Models and reasoning

Select a provider and model, tune reasoning, or restrict Ctrl+P model cycling.

--provider <name>

Core

Select an LLM provider.

--model <pattern>

Values: provider/model · fuzzy pattern · optional :thinking suffix

Core

Select a model by ID or fuzzy pattern. A value such as sonnet:high also sets thinking.

--api-key <key>

Core

Provide a credential for this run instead of saved auth or environment variables.

--thinking <level>

Values: off · minimal · low · medium · high · xhigh · max

Core

Set the requested reasoning level when the selected model supports it.

--models <patterns>

Core

Set a comma-separated, glob-aware model list for Ctrl+P cycling.

--list-models [search]

Core

List available models, optionally using a fuzzy search term.

System prompt and context

Replace or extend the system prompt and control project instruction discovery.

--system-prompt <text>

Core

Replace Pi's default coding-assistant prompt.

--append-system-prompt <text>

Core

Append text or file contents to the system prompt; repeat as needed.

--no-context-files

Aliases: -nc

Core

Disable discovery of AGENTS.md and CLAUDE.md context files.

Sessions

Continue, select, fork, name, relocate, or avoid persisting a session.

--continue

Aliases: -c

Core

Continue the most recent project session.

--resume

Aliases: -r

Core

Open the session picker at startup.

--session <path|id>

Core

Use a session file path or partial session UUID.

--session-id <id>

Core

Use an exact current-project session ID, creating it when missing.

--fork <path|id>

Core

Fork the selected session into a new session file before starting.

--session-dir <dir>

Core

Override the directory used for session storage and lookup.

--no-session

Core

Use an ephemeral session that is not saved to disk.

--name <name>

Aliases: -n

Core

Set a human-readable session name at startup.

Tool control

Apply allowlists and denylists across built-in, custom, and Extension tools.

--tools <list>

Aliases: -t

Core

Enable only the comma-separated tool names.

--exclude-tools <list>

Aliases: -xt

Core

Disable the comma-separated tool names.

--no-tools

Aliases: -nt

Core

Disable all built-in, custom, and Extension tools.

--no-builtin-tools

Aliases: -nbt

Core

Disable built-ins while leaving Extension and custom tools available.

Extensions, Skills, prompts, and themes

Load individual resources or disable automatic discovery for a controlled run.

--extension <path>

Aliases: -e

Core

Load an Extension file explicitly; repeat for multiple files.

--no-extensions

Aliases: -ne

Core

Disable discovery while still allowing explicit -e paths.

--skill <path>

Core

Load a Skill file or directory explicitly; repeat as needed.

--no-skills

Aliases: -ns

Core

Disable Skill discovery and loading.

--prompt-template <path>

Core

Load a prompt-template file or directory.

--no-prompt-templates

Aliases: -np

Core

Disable prompt-template discovery.

--theme <path>

Core

Load an additional theme file or directory.

--use-theme <name[/name]>

Core

Set the initial theme for this run without changing settings.

--no-themes

Core

Disable theme discovery and loading.

Modes, trust, and general behavior

Choose output, TUI layout, trust, startup networking, and parsing behavior.

--print

Aliases: -p

Core

Run non-interactively, print the response, and exit.

--mode <mode>

Values: text · json · rpc

Core

Select text, JSON event, or RPC output.

--tui-mode <mode>

Values: regular · fullscreen

Core

Use the regular or fullscreen TUI.

--export <file>

Core

Export a session file to HTML and exit.

--approve

Aliases: -a

Core

Trust project-local resources for this run.

--no-approve

Aliases: -na

Core

Ignore project-local resources for this run.

--offline

Core

Disable startup network operations; equivalent to PI_OFFLINE=1.

--verbose

Core

Force verbose startup output.

--

Core

Stop option parsing; treat later values as messages or @file inputs.

--help / --version

Aliases: -h / -v

Core

Show local help or the installed version.

Official built-in tool names

read, bash, edit, and write are the primary tools. grep, find, and ls are optional read-only built-ins. PowerShell is available on Windows.

readbashpowershelleditwritegrepfindls

Packages, updates, and credentials

The top-level Pi command groups

Pi install manages Pi Packages, not the binary. Likewise, pi uninstall is only an alias for removing a Package.

Pi Packages

Manage bundles from npm, git, HTTPS, SSH, or a local directory.

pi install <source>

Values: npm: · git: · https:// · ssh:// · local path

Core

Install a Pi Package and add it to user settings.

pi install -l <source>

Core

Install for the current project and update .pi/settings.json.

pi remove <source>

Core

Remove a configured Pi Package.

pi uninstall <source>

Core

Alias for pi remove; it does not uninstall the Pi CLI.

pi list

Core

List Packages in user and trusted project settings.

pi config [-l]

Core

Open the TUI for enabling or disabling package resources.

Update commands

Update the CLI, installed Packages, or model catalogs independently.

pi update

Aliases: pi update --self · pi update pi · pi update self

Core

Update Pi itself; self-update is the default target.

pi update --extensions

Core

Update installed Pi Packages without updating Pi.

pi update --models

Core

Refresh model catalogs only.

pi update --all

Core

Update both Pi and installed Packages.

pi update <source>

Aliases: pi update --extension <source>

Core

Update one Package source.

pi update --self --force

Core

Reinstall Pi even when the installed version is current.

Credential commands

Check provider readiness or expose a credential to another local tool.

pi auth check

Values: --provider · --model · --json · --credentials · --no-refresh

Core

Check credentials and refresh expired OAuth credentials unless disabled.

pi auth print-api-key

Values: --provider · --model

Core

Print a configured API key for another local client.

pi auth print-bearer-token

Values: --provider · --model · --min-expiry 30m|1h

Core

Print a valid OAuth token, refreshing it when needed.

Pi Packages can run Extensions with full system access, and Skills can instruct the model to use tools. Review third-party source before installation and only trust project-local resources intentionally.

Interactive TUI

Twenty-three core slash commands, plus /llama

The core registry contains exactly 23 commands. /llama comes from Pi's official bundled llama.cpp Extension; installed resources can add more.

Models, providers, and settings

Choose models, thinking, credentials, and the model-cycle scope.

/settings

Core

Open the interactive settings menu.

/model [provider/model]

Core

Open the selector or switch directly to a model.

/thinking [level]

Core

Open the selector or set a supported thinking level.

/scoped-models

Core

Configure models included in Ctrl+P cycling and their order.

/login [provider]

Core

Configure provider-specific authentication.

/logout

Core

Remove saved provider authentication.

Session lifecycle and branching

Create, resume, identify, branch, duplicate, and compact JSONL trees.

/new

Core

Start a fresh session.

/resume

Core

Browse and resume a previous project session.

/name <name>

Core

Set a human-readable session name.

/session

Core

Show the file, ID, message count, tokens, and cost.

/tree

Core

Navigate the current session and continue on an in-file branch.

/fork

Core

Create a new session file from an earlier user message.

/clone

Core

Copy the active branch into a new session file.

/compact [instructions]

Core

Summarize older context, optionally with custom focus.

Export, import, and sharing

Move session data, copy the latest response, or share a transcript.

/copy

Core

Copy the last agent message.

/export [file]

Values: .html · .jsonl

Core

Export HTML by default or specify .jsonl.

/import <file>

Core

Import and resume a JSONL session.

/share

Core

Share the session as a secret GitHub gist with a viewer link.

Runtime and help

Trust, reload, inspect changes and keybindings, or exit.

/trust

Core

Save trust for future sessions; restart to load newly trusted resources.

/reload

Core

Reload keybindings, Extensions, Skills, prompts, themes, and context.

/hotkeys

Core

Show active keyboard shortcuts.

/changelog

Core

Display Pi's changelog.

/quit

Core

Exit Pi.

/llama

Bundled

Manage llama.cpp router model discovery, downloads, loading, and unloading.

@src/auth.ts

Attach a file

Type @ to fuzzy-search files, or pass @file and @image arguments on the CLI.

!git diff

Shell + context

Execute the command and include its output in the current LLM context.

!!git status

Local shell only

Execute the command without adding its output to the LLM context.

Pi's signature workflow

Sessions are trees, not flat transcripts

Every JSONL entry has an ID and parent. Revisit an earlier node without deleting the original path, keep alternatives together, or split a path into a new session.

One session, multiple branches

root user prompt
└── assistant response
    ├── user: approach A
    │   └── assistant
    │       └── user: continue A  ← active
    └── user: approach B
        └── assistant

CommandResult

/tree

Move within the same file and create an in-file branch.

/fork

Pick an earlier user prompt and create a new session file.

/clone

Copy the active branch into a new session file.

Steering vs follow-up

While Pi is running, submit with Enter to steer after current tool calls. Use Alt+Enter to queue a follow-up until the active work finishes.

No fixed command count

Pi becomes the harness you install

Markdown prompts, Agent Skills, TypeScript Extensions, and shareable Packages make two Pi installations expose different slash commands and CLI flags.

Markdown → /name

Prompt Templates

A Markdown file in a prompts directory becomes a slash command named after the file.

~/.pi/agent/prompts/review.md
→ /review security

On-demand guidance

Skills

Agent Skills can load automatically or be invoked through the skill namespace.

.pi/skills/web-search/SKILL.md
→ /skill:web-search

Programmable surface

Extensions

TypeScript Extensions register slash commands, tools, UI, events, providers, and long CLI flags.

pi.registerCommand("deploy", ...)
→ /deploy

Shareable bundles

Pi Packages

Packages distribute Extensions, Skills, prompts, and themes through npm, git, or local paths.

pi install npm:@scope/pi-tools

Common commands that are not core

/plan, /todos, /tools, /preset, /ask, /steer, and /followup appear in examples or third-party Extensions. They are valid when installed, but not part of the fixed 23-command registry.

Process integration

RPC exposes Pi over strict JSONL

Send one JSON object per LF-delimited line on stdin. Pi replies and streams events on stdout for IDEs, custom UIs, and orchestrators.

Prompting

promptsteerfollow_upabortclear_queuenew_session

State

get_stateget_messages

Models

set_modelcycle_modelget_available_models

Thinking

set_thinking_levelcycle_thinking_levelget_available_thinking_levels

Queue modes

set_steering_modeset_follow_up_mode

Compaction and retry

compactset_auto_compactionset_auto_retryabort_retry

Shell

bashabort_bash

Sessions

get_session_statsexport_htmlswitch_sessionforkcloneget_fork_messagesget_entriesget_treeget_last_assistant_textset_session_name

Dynamic commands

get_commands

Pi RPC example

# Start Pi as a JSONL RPC subprocess
pi --mode rpc

# Write one JSON object per line to stdin
{"id":"state-1","type":"get_state"}
{"type":"set_model","provider":"openai","modelId":"gpt-5.5"}
{"type":"set_thinking_level","level":"high"}
{"type":"prompt","message":"Review this repository"}
{"type":"bash","command":"git status"}
{"type":"get_tree"}

get_commands returns Extension commands, prompt templates, and Skills. It intentionally omits TUI-only built-ins such as /settings and /hotkeys.

Keyboard reference

High-value default hotkeys

Bindings are customizable in ~/.pi/agent/keybindings.json. /hotkeys is the best source of truth after local changes.

KeyAction

Ctrl+C

Clear the editor; press again to exit

Ctrl+D

Exit when the editor is empty

Esc

Cancel or abort the current operation

Ctrl+G

Open the prompt in an external editor

Ctrl+L

Open the model selector

Ctrl+P

Cycle to the next scoped model

Shift+Ctrl+P

Cycle to the previous scoped model

Shift+Tab

Cycle the thinking level

Ctrl+O

Collapse or expand tool output

Ctrl+T

Collapse or expand thinking blocks

Ctrl+X

Copy the last assistant message

Alt+Enter

Queue a follow-up message

Alt+Up

Restore queued messages to the editor

Shift+Enter

Insert a new line

Windows and WSL use alternatives for some model, queue, image-paste, and fullscreen-search shortcuts. Check /hotkeys on the target machine.

Choosing the mental model

Pi and OpenCode optimize for different surfaces

Pi keeps workflow choices programmable. OpenCode ships more platform capabilities directly in its CLI and TUI.

CapabilityPiOpenCode

Main interactive commandpiopencode

One-shot automationpi -popencode run

Core philosophySmall programmable harnessFeature-rich built-in platform

Session branchingTree-native /tree, /fork, /cloneSessions and fork workflows

Packages / pluginspi install Pi Packageopencode plugin

MCPImplemented by ExtensionsBuilt-in mcp commands

Sub-agents / plan modeImplemented by ExtensionsBuilt-in agents and modes

Headless integrationJSON events, RPC, SDKServer, API, ACP

Dynamic CLI flagsExtensions register long flagsMore fixed CLI surface

Special shell input!cmd and !!cmdShell mode

Read-only repository review

Allow only Pi's optional read-only built-ins and print one result.

pi --tools read,grep,find,ls \
  -p "Review this repository for security and correctness issues"

JSON automation

Stream structured events for a pipeline or log consumer.

pi --mode json \
  --model openai/gpt-5.5 \
  --thinking high \
  "Fix the failing tests"

Focused continuation

Resume the latest session and add a constraint without opening a picker.

pi -c "Continue, but do not change the database schema"

Controlled customization

Disable discovery and load exactly one audited Extension and Skill.

pi --no-extensions -e ./review.ts \
  --no-skills --skill ./skills/security \
  "Review this project"

Sources and version notes

Official package, repository, and current source

This reference was checked against v0.84.3 and the Earendil Works main branch on August 26, 2026.

Pi repository and README Current npm package CLI parser and help source Package command source Core slash-command registry Session documentation Keybindings documentation RPC documentation

Check the installed environment

Versions move quickly and project resources vary. Use local help and autocomplete as the final authority for a specific machine.

pi --help

pi --version

pi list

pi auth --help

/

/hotkeys

/changelog