CLI Reference

✓ Fresh · 2026-02-24

Complete reference for all Pi command-line flags, session management, package commands, and RPC mode.

Basic Usage

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

You can pass file references and messages directly on the command line:

pi @src/index.ts "Refactor this file to use async/await"

Session Flags

Flag	Description
pi	Start a new session
pi -c	Continue the most recent session
pi -r	Browse and select from past sessions
pi --no-session	Ephemeral mode (session is not saved)
pi --session <path|id>	Resume a specific session by path or ID

Extension Loading

Load TypeScript extensions at startup:

# Single extension
pi -e extensions/my-ext.ts

# Stack multiple extensions
pi -e ext1.ts -e ext2.ts

# Combine with session flags
pi -c -e extensions/damage-control.ts

Extensions are loaded in order. Later extensions can override behaviors of earlier ones.

Package Commands

Pi has a built-in package manager for installing extensions, skills, prompts, and themes.

Install

# From npm
pi install npm:@foo/pi-tools

# Pinned version
pi install npm:@foo/pi-tools@1.2.3

# From git
pi install git:github.com/user/repo

# Git with tag
pi install git:github.com/user/repo@v1

# Project-local install (uses .pi/ instead of ~/.pi/)
pi install -l npm:@foo/pi-tools

Manage

# List installed packages
pi list

# Update all (skips pinned versions)
pi update

# Remove a package
pi remove npm:@foo/pi-tools

# Configure package resources (enable/disable)
pi config

Install Location

Flag	Global Path	Project Path
(default)	~/.pi/agent/npm/ or ~/.pi/agent/git/	-
-l	-	.pi/npm/ or .pi/git/

RPC Mode

For non-Node.js integrations, Pi supports an RPC protocol over stdin/stdout:

pi --mode rpc

This enables external applications to communicate with Pi programmatically using structured JSON messages. See the SDK documentation for programmatic usage details.

File References

Use @ to reference files on the command line:

# Single file
pi @README.md "Summarize this"

# Multiple files
pi @src/index.ts @src/utils.ts "Find bugs in these files"

# Glob patterns
pi @src/**/*.ts "Review all TypeScript files"

Environment Variables

Pi reads the following environment variables:

Variable	Purpose
PI_HOME	Override default config directory (~/.pi)
PI_MODEL	Set default model
PI_THEME	Set default theme
Various *_API_KEY	Provider authentication (see Installation)

Exit Codes

Code	Meaning
0	Normal exit
1	Error during execution
130	Interrupted (Ctrl+C)