pi-mono/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]

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 Provider Authentication for credentials.

• --provider <name>
  Restricts --model lookup to one provider.
• --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.

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
codemode	Run JavaScript that calls the other active tools, for example in parallel with Promise.all; only the script's return value and console output reach the model

codemode scripts run in a QuickJS sandbox that can only reach the other tools. A script may start with an options line such as // @options {"timeout": 30}; timeout is in seconds and unset by default. store(key, value) and load(key) keep JSON values across codemode calls: each successful script that stores values appends a codemode-store custom entry to the session, so resumed sessions keep the values and each branch sees only the values written on its path. Scripts can also use models: getModelsOfType, getAvailableOfType, and getModelOfType list the model catalog, and classify(model, context) runs a classifier model with the session's credentials, at most four at a time per script.

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 and is repeatable.
• -ne, --no-extensions
  Disables discovered and configured extensions. Explicit -e paths still load.
• --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 regular or fullscreen 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 Provider Authentication 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.