Pi CLI

pi is an AI coding assistant CLI exposing read, bash, edit, and write tools. This skill covers every aspect of controlling it from the command line.

Core Commands

# Interactive session (default)
pi

# Interactive with initial prompt
pi "Refactor the auth module"

# Non-interactive: process and exit
pi -p "List all .ts files in src/"

# Include files in prompt
pi @prompt.md @image.png "What does this do?"

# Multiple messages (interactive)
pi "Read package.json" "What dependencies do we have?"

Session Management

pi --continue              # Continue previous session (-c)
pi --resume                # Pick a past session to resume (-r)
pi --session <path>        # Use a specific session file
pi --fork <path|uuid>      # Fork a session into a new one
pi --session-dir <dir>     # Custom directory for session storage
pi --no-session            # Ephemeral session (nothing saved)
pi --export session.jsonl output.html  # Export session to HTML

Extension Management

pi install <source>        # Install extension source globally
pi install <source> -l     # Install locally (project-level)
pi remove <source>         # Remove extension source
pi uninstall <source>      # Alias for remove
pi update                  # Update all installed extensions
pi update <source>         # Update a specific extension
pi list                    # List installed extensions
pi config                  # Open TUI to enable/disable resources
pi <command> --help        # Help for any sub-command

Model & Provider Selection

# Default provider: google
pi --provider anthropic --model claude-sonnet-4 "..."

# Provider/model shorthand (no --provider needed)
pi --model openai/gpt-4o "..."
pi --model anthropic/claude-opus-4 "..."

# Fuzzy / glob matching
pi --model "*sonnet*" "..."

# With thinking level shorthand
pi --model sonnet:high "Solve this complex problem"
pi --thinking high "..."   # off | minimal | low | medium | high | xhigh | max

# Cycle through multiple models with Ctrl+P
pi --models claude-sonnet,claude-haiku,gpt-4o
pi --models "github-copilot/*"
pi --models sonnet:high,haiku:low

# Discover available models
pi --list-models
pi --list-models sonnet

Tool Configuration

Default enabled tools: read, bash, edit, write

# Full tool set
pi --tools read,bash,edit,write,grep,find,ls "..."

# Read-only (no file modifications)
pi --tools read,grep,find,ls -p "Review the code in src/"

# Disable all tools (built-in and extension)
pi --no-tools "..."

Available tools:

Skills, Extensions & Themes

# Load specific skill(s)
pi --skill /path/to/skill-dir "..."
pi --skill /path/to/skill1 --skill /path/to/skill2 "..."

# Disable automatic skill discovery
pi --no-skills "..."           # -ns shorthand

# Load extension(s) explicitly
pi --extension /path/to/ext.js "..."   # -e shorthand
pi -e ext1.js -e ext2.js "..."

# Disable automatic extension discovery
pi --no-extensions "..."       # -ne shorthand

# Load prompt template(s)
pi --prompt-template /path/to/template "..."

# Disable automatic prompt template discovery
pi --no-prompt-templates "..."  # -np shorthand

# Load theme(s)
pi --theme /path/to/theme "..."

# Disable automatic theme discovery
pi --no-themes "..."

System Prompt Control

pi --system-prompt "You are a Rust expert. ..."
pi --append-system-prompt "Always add tests for new code."
# Can also point to a file:
pi --append-system-prompt @extra-instructions.md

Output Modes

pi --mode text   # Default: human-readable output
pi --mode json   # JSON-structured output
pi --mode rpc    # RPC protocol (for tool integrations)

Misc Flags

pi --api-key <key>     # Override API key (defaults to env vars)
pi --verbose           # Force verbose startup output
pi --offline           # Disable startup network ops (same as PI_OFFLINE=1)
pi --version           # Show version number
pi --help              # Show full help

Extension-Specific Flags

Some extensions register their own flags to the pi CLI:

# Enable per-session control sockets
pi --session-control "..."

# Specify a custom MCP configuration file
pi --mcp-config /path/to/mcp-config.json "..."

Environment Variables

Common Patterns

Scripting / Automation

# Run a task and capture output (non-interactive)
pi -p --mode json "Summarize src/auth.ts" > summary.json

# Pipe a generated prompt
echo "Explain this error: $(cat error.log)" | xargs pi -p

# Combine with --no-session for isolated one-shots
pi -p --no-session "Generate a UUID"

Code Review Pipeline

# Read-only review, no mutations possible
pi --tools read,grep,find,ls -p @PR_DIFF.patch "Review this PR for security issues"

Locked-down Model Run

pi --model anthropic/claude-opus-4:high \
   --thinking high \
   --no-extensions \
   --no-skills \
   -p "Solve the following algorithm problem: ..."

Resuming & Branching Conversations

# Resume the most recent session and continue
pi -c "Now add unit tests for what we built"

# Fork a past session to explore a different direction
pi --fork abc123 "Try a different approach using Redis instead"

Export Session to HTML

pi --export ~/.pi/agent/sessions/my-session/session.jsonl
pi --export session.jsonl report.html