4  Quickstart

4.1 Installation

Pi is distributed as an npm package. Install it globally:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

The --ignore-scripts flag disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.

On Linux or macOS, you can alternatively use the installer script:

curl -fsSL https://pi.dev/install.sh | sh

4.1.1 Uninstallation

Use the package manager that installed Pi. The curl installer uses npm globally, so curl and npm installs are removed identically:

# curl installer or npm install -g
npm uninstall -g @earendil-works/pi-coding-agent

# pnpm
pnpm remove -g @earendil-works/pi-coding-agent

# Yarn
yarn global remove @earendil-works/pi-coding-agent

# Bun
bun uninstall -g @earendil-works/pi-coding-agent

Uninstalling Pi leaves settings, credentials, sessions, and installed pi packages in ~/.pi/agent/.

4.2 Authentication

Pi can authenticate through subscription providers via OAuth login, or through API key providers via environment variables or the auth file.

4.2.1 Option 1: Subscription Login

Start Pi and run the login command:

/login

Then select a provider. Built-in subscription logins include:

  • Claude Pro/Max — Anthropic subscription auth
  • ChatGPT Plus/Pro (Codex) — OpenAI subscription, officially endorsed by OpenAI
  • GitHub Copilot — including GitHub Enterprise Server
  • xAI (Grok/X subscription) — requires X subscription
  • OpenRouter — OAuth-minted API key billed from OpenRouter credits
  • Radius — dynamic pi-messages gateway

Use /logout to clear credentials. Tokens are stored in ~/.pi/agent/auth.json and auto-refresh when expired.

Note

Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party harness usage draws from extra usage and is billed per token, not against Claude plan limits.

4.2.2 Option 2: API Key

Set an API key before launching Pi:

export ANTHROPIC_API_KEY=sk-ant-...
pi

You can also run /login and select an API-key provider to store the key in ~/.pi/agent/auth.json. See the Providers chapter for all supported providers and environment variables.

4.3 First Session

Once Pi starts, type a request and press Enter:

Summarize this repository and tell me how to run its checks.

By default, Pi gives the model four tools:

  • read — read files
  • write — create or overwrite files
  • edit — patch files
  • bash — run shell commands

Additional built-in read-only tools (grep, find, ls) are available through tool options. Pi runs in your current working directory and can modify files there.

Warning

Use git or another checkpointing workflow if you want easy rollback. Pi modifies files directly with the permissions of your user account.

4.4 Project Instructions

Pi loads context files at startup. Add an AGENTS.md file to tell it how to work in your project:

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

Pi loads context files from these locations:

Location Scope
~/.pi/agent/AGENTS.md Global instructions (all projects)
AGENTS.md or CLAUDE.md in parent directories Walked up from cwd
AGENTS.md or CLAUDE.md in current directory Project-specific

Restart Pi, or run /reload, after changing context files.

4.5 Common Operations

4.5.1 Referencing Files

Type @ in the editor to fuzzy-search project files, or pass files on the command line:

pi @README.md "Summarize this"
pi @src/app.ts @src/app.test.ts "Review these together"

Images or text can be pasted with Ctrl+V (Alt+V on Windows). Images can also be dragged into supported terminals.

4.5.2 Running Shell Commands

In interactive mode, prefix a command with !:

!npm run lint

The command output is sent to the model. Use !!command to run a command without adding its output to the model context.

4.5.3 Switching Models

Use /model or Ctrl+L to choose a model. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.

4.5.4 Continuing Sessions

Sessions are saved automatically:

pi -c                  # Continue most recent session
pi -r                  # Browse previous sessions
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Open a specific session

Inside Pi, use /resume, /new, /tree, /fork, and /clone to manage sessions.

4.6 Non-Interactive Mode

For one-shot prompts:

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"

Use --mode json for JSON event output or --mode rpc for process integration. These modes are covered in detail in later chapters.

Tip

In print mode, Pi also reads piped stdin and merges it into the initial prompt. This makes it easy to chain Pi with other command-line tools.

4.7 Next Steps

Now that you have Pi running, explore these topics:

  • Using Pi — Interactive mode, slash commands, and CLI reference
  • Providers — Authentication and model setup
  • Settings — Global and project configuration
  • Keybindings — Shortcuts and customization
  • Extensions — Custom tools, commands, and events
  • Skills — Reusable capability packages