pi/packages/coding-agent/docs/cli.md

Command Line

This page documents Pi's built-in command-line commands and options. Run pi --help or append --help to a command for the exact interface in your installed version. The top-level help also includes options registered by loaded extensions.

pi [options] [--] [@files...] [messages...]
pi install <source> [options]
pi remove <source> [options]
pi uninstall <source> [options]
pi update [target] [options]
pi list
pi config [options]
pi auth <check|print-api-key|print-bearer-token> [options]
pi mcp <list|login|logout> [options]

Invocation and output

pi
pi --print "Summarize this repository"
git diff | pi --print "Review this change"
pi --mode json "Inspect this repository" > events.jsonl

With terminal stdin and stdout, Pi opens the terminal UI unless --print, --mode json, or --mode rpc selects another interface. When either stream is redirected and neither JSON nor RPC mode is selected, Pi uses print mode. See CLI Integration for choosing between interactive, print, JSON, RPC, and SDK integration.

Input	Behavior
message	Provide an initial prompt
@path	Include a text file or image in the first prompt
Piped stdin	Prepend its contents to the first prompt
--	Stop option parsing so a prompt can begin with -

Pi resolves @path from the current working directory. The working directory also controls project configuration, resource discovery, and session grouping.

--print controls whether Pi runs once and exits. --mode selects the output interface. --mode text does not force one-shot execution when stdin and stdout are terminals; use --print for that behavior.

Option	Behavior
-p, --print	Run the supplied prompts, write the final assistant text to stdout, then exit
--mode text	Select text output; still open the terminal UI when stdin and stdout are terminals
--mode json	Run the supplied prompts, write JSONL events to stdout, then exit
--mode rpc	Read JSONL commands from stdin and write responses and events to stdout until shutdown
--export <input> [output]	Export a session file to HTML and exit; derive the destination when output is omitted

RPC mode rejects @file arguments. JSON and RPC modes reserve stdout for protocol records. See JSON Event Stream and RPC Protocol.

Models

pi --model sonnet:high

See Choose a Model for model selection and Providers for credentials.

• --provider <name>
  Restricts --model lookup to one provider. It requires --model.
• --model <pattern>
  Selects by exact ID or fuzzy ID/name match. It accepts provider/id and an optional :<thinking> suffix.
• --api-key <key>
  Uses a non-persistent API-key override. It requires a model selected through --model or --models.
• --thinking <level>
  Sets off, minimal, low, medium, high, xhigh, or max. It overrides a --model suffix and is clamped to the model's capabilities.
• --models <patterns>
  Sets a comma-separated scope for startup and cycling. It accepts exact IDs, fuzzy matches, case-insensitive globs, and optional :<thinking> suffixes.
• --list-models [search]
  Lists available models, optionally filtered by a fuzzy search, then exits.

Sessions

pi --continue

See Sessions and Context for resuming, forking, naming, and storing sessions.

• -c, --continue
  Continues the most recent session for the current project.
• -r, --resume
  Opens the session selector.
• --session <path|id>
  Opens by file path, exact ID, or partial ID. Pi searches the current project first and offers to fork a cross-project match.
• --session-id <id>
  Opens the exact project session ID or creates it if absent. IDs accept letters, numbers, ., _, and -.
• --fork <path|id>
  Forks an existing session into a new session for the current project.
• --session-dir <dir>
  Overrides storage and lookup. It takes precedence over PI_CODING_AGENT_SESSION_DIR and the sessionDir setting.
• --no-session
  Uses an in-memory session that is not persisted.
• -n, --name <name>
  Sets the session display name.

Constraints:

• Session IDs must start and end with a letter or number.
• --fork cannot be combined with --session, --continue, --resume, or --no-session.
• --session-id cannot be combined with --session, --continue, or --resume. Combine it with --fork to choose the new ID.

Tools

pi --tools read,grep,find,ls --print "Review this project"

See Settings for configuring the default tool selection.

• -t, --tools <list>
  Replaces the default selection with a comma-separated allowlist of built-in, extension, or custom tools.
• -xt, --exclude-tools <list>
  Disables comma-separated tool names after all other selection options.
• -nbt, --no-builtin-tools
  Disables default built-in tools while retaining extension and custom tools.
• -nt, --no-tools
  Starts with all built-in, extension, and custom tools disabled.

Default enabled tools are read, bash, edit, and write, unless defaultTools changes them. --tools replaces the whole selection, so name every tool you want; defaultTools also accepts +name and -name to change the defaults instead.

Built-in	Purpose
read	Read text files and supported images
bash	Run shell commands
powershell	Run PowerShell commands on Windows
edit	Apply exact text replacements to an existing file
write	Create or overwrite a file
grep	Search file contents
find	Find paths using glob patterns
ls	List directory contents

Built-in extensions add two more tools. They are off by default; the MCP extension turns them on when an MCP server needs them (see MCP). To enable them yourself, name them in --tools or defaultTools.

Built-in extension	Purpose
codemode	Run JavaScript that calls the other tools, for example in parallel with Promise.allSettled; only the script's output reaches the model
tool_search	Search tools that are not declared to the model (codemode and deferred exposure, such as MCP tools) and declare the matches for the next call

Enable codemode

To turn on codemode for every session, add it to the default tools in ~/.pi/agent/settings.json or a project's .pi/settings.json:

{
  "defaultTools": ["+codemode"]
}

This keeps read, bash, edit, and write and adds codemode. For one invocation, list every tool, since --tools replaces the selection:

pi --tools read,bash,edit,write,codemode

Codemode is useful without MCP: scripts can run several tool calls in parallel, filter large output before it reaches the model, call classifier models such as TypeSafe's Jev through models.classify() (see Classifier models), and generate images through models.generateImages() (see Image models).

How codemode works

Scripts run in a QuickJS sandbox and reach the other tools through tools.<name>(args). Codemode describes the script API, how tools are listed and found, the store() and models globals, and the limits.

Tool search

tool_search is off by default; enable it with "defaultTools": ["+tool_search"] or --tools. It uses the same ranking as searchTools() over tools that are not declared yet and declares the matches for the next model call. Loaded tools are recorded in the session like other tool changes, so they stay declared on that branch.

Resources

pi --extension ./review.ts

See Configuration for conventional directories and project trust, Settings for configured paths, and Pi Packages for package sources.

• -e, --extension <path>
  Loads an extension file or directory, or a built-in extension such as builtin:mcp, and is repeatable.
• -ne, --no-extensions
  Disables discovered, configured, and built-in extensions. Explicit -e paths still load, so pi -ne -e builtin:mcp keeps only the built-in MCP support.
• --skill <path>
  Loads a skill file or directory and is repeatable.
• -ns, --no-skills
  Disables discovered and configured skills. Explicit --skill paths still load.
• --prompt-template <path>
  Loads a prompt-template file or directory and is repeatable.
• -np, --no-prompt-templates
  Disables discovered and configured templates. Explicit --prompt-template paths still load.
• --theme <path>
  Loads a theme file or directory and is repeatable.
• --use-theme <name[/name]>
  Selects the initial interactive theme for this run.
• --no-themes
  Disables discovered and configured themes. Explicit --theme paths still load.
• -nc, --no-context-files
  Disables AGENTS.md and CLAUDE.md discovery.

Resource paths apply only to the current process. Relative paths resolve from the current working directory.

Prompts and process

pi --append-system-prompt ./instructions.md

See Configuration for saved configuration, Security for project trust, and Environment Variables for process controls.

• --system-prompt <text|path>
  Replaces the default system prompt with text or the contents of an existing file.
• --append-system-prompt <text|path>
  Appends text or an existing file to the system prompt and is repeatable.
• --tui-mode <mode>
  Uses fullscreen (default) or regular terminal mode.
• --verbose
  Shows verbose interactive startup information, overriding quietStartup.
• -a, --approve
  Trusts project-local configuration and resources for this process.
• -na, --no-approve
  Ignores trust-gated project-local configuration and resources for this process.
• --offline
  Disables automatic network activity, including model catalog refreshes. Equivalent to PI_OFFLINE=1.
• -h, --help
  Shows help, including flags registered by loaded extensions, then exits.
• -v, --version
  Shows the Pi version, then exits.

Extensions may register additional long-form options. Unknown short options are rejected.

Package commands

pi install npm:@scope/package

See Pi Packages for source formats, filtering, installation, and project scope.

Common tasks

Task	Command
Install a package	pi install <source>
List configured packages	pi list
Remove a package and its settings entry	pi remove <source>
Configure which package resources load	pi config

Add --local or -l to install, remove, uninstall, or config to use project settings instead of global settings.

Update Pi or packages

Running pi update without a target updates Pi itself.

Task	Command
Update Pi	pi update
Update all installed packages	pi update --extensions
Update one installed package	pi update <source>
Refresh model catalogs	pi update --models
Update Pi and all installed packages	pi update --all

Add --force to reinstall Pi when the selected update includes Pi.

Aliases and command options

• pi uninstall <source> is an alias for pi remove <source>.
• pi update --self, pi update self, and pi update pi are aliases for pi update.
• pi update --extension <source> is an alias for pi update <source>.
• -a, --approve trusts project-local files for one command. -na, --no-approve ignores trust-gated project-local files.
• Append -h or --help to a command for its exact usage and option constraints.

Credential commands

pi auth check --provider openai --json

Authentication commands require --provider <provider> or --model <model>. See Providers for supported methods.

Command	Description
pi auth check	Print ready, not_ready, or invalid; exit with status 0, 1, or 2, respectively
pi auth print-api-key	Print the resolved API key
pi auth print-bearer-token	Print a resolved OAuth bearer token

Option	Applies to	Description
--provider <provider>	All	Resolve credentials for a provider
--model <model>	All	Resolve credentials from a model; may be combined with --provider
--json	auth check	Write the structured result as JSON
--credentials	auth check	Emit the resolved credential when ready
--no-refresh	auth check	Do not refresh expired OAuth credentials; refresh is the default
--min-expiry <duration>	print-bearer-token	Require remaining token lifetime using ms, s, m, or h, such as 30m

Credential-printing commands write secrets to stdout.

MCP commands

These commands work outside a session, so agents can run them through bash. See MCP Servers.

Command	Description
pi mcp add <server> [options] -- <command> [args...]	Add or replace a stdio server in mcp.json; --env KEY=VALUE (repeatable) and --cwd <dir> set its environment and working directory. Arguments after the command are passed to it
pi mcp add <server> [options] --url <url>	Add or replace a streamable HTTP server; --header KEY=VALUE (repeatable), --bearer-token-env-var <NAME> (sends Authorization: Bearer ${NAME}), --oauth-client-id, --oauth-client-secret, --oauth-callback-port, and --oauth-client-name configure authentication
pi mcp remove <server>	Remove a server from mcp.json; stored OAuth credentials are kept
pi mcp list [--json]	Connect to every enabled server and print its state, tools, and errors; exit with 1 when a config entry is invalid or an enabled server is not connected
pi mcp login <server> [--timeout <seconds>]	Sign in to an OAuth server: open the authorization page and wait for the browser (default 300 seconds); a terminal also accepts the pasted redirect URL
pi mcp logout <server>	Delete the stored OAuth credentials of a server

add and remove change ~/.pi/agent/mcp.json, or .pi/mcp.json in the current directory with --local (-l). add also takes --exposure <mode> (see Exposure) and --description <text> and does not connect; run pi mcp list to check the server.

Project .pi/mcp.json files are only read for projects that are already trusted.