Chapter 2 · Installation and Quickstart

Chapter goals: Complete pi's installation and first authentication;跑通 the first task in a real project; master高频上手 operations like @ file refs, ! command execution, and session resume.

2.1 Installation

pi distributes as an npm包; the recommended install命令带 --ignore-scripts:

# Official推荐: skip依赖 lifecycle scripts (pi itself不需要安装脚本)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# Alternative: curl installer (internally also走 npm global)
curl -fsSL https://pi.dev/install.sh | sh

Verify and uninstall:

pi --version        # Check version, e.g. 0.84.x

# Uninstall with the包 manager used at install time
npm uninstall -g @earendil-works/pi-coding-agent

Uninstall Does Not Clear Data

Uninstalling the包 only removes the program itself; your settings, credentials, sessions, and installed pi packages all remain in ~/.pi/agent/. To彻底重来 need to手动 delete that directory.

2.2 First Authentication

pi supports两类接入方式, pick either:

Method 1: Subscription login (Claude Pro/Max, ChatGPT Plus/Pro Codex, GitHub Copilot etc.):

$ pi
/login        # Type this command in the interactive界面; follow prompts to select provider and完成 OAuth login

Method 2: API Key environment variable:

export ANTHROPIC_API_KEY=sk-ant-...
pi

You can also /login to select an API-key类 provider and persist the key to ~/.pi/agent/auth.json (permissions 0600); thereafter no need to每次 export. Chapter 3展开 all providers and key parsing rules.

2.3 The First Task

Enter the target project directory and启动:

cd /path/to/project
pi

直接下达自然语言任务 and press Enter:

> Summarize this repo and tell me how to run its checks.

The model uses default read/bash etc. tools to自行浏览 files, execute commands, and汇总 the answer. 注意: pi has真实的文件修改能力 in the current working directory; for重要项目先建立 git state you can rollback to.

2.4 High-Frequency Quickstart Operations Overview

# 1. Fuzzy引用 files with @ (typing @ in the editor触发搜索)
pi @README.md "Summarize this file"
pi @src/app.ts @src/app.test.ts "Review these two together"

# 2. ! prefix executes a shell command and sends the output to the model; !!则不进入模型上下文
!npm run lint
!!ls -la

# 3. Switch model and thinking level
/model          # or快捷键 Ctrl+L to open the model picker
# Shift+Tab to循环切换 thinking level

# 4. Session resume
pi -c           # Continue the most recent session
pi -r           # Browse historical会话列表
pi --name "Refactor auth module"   # Name the session at startup

Add长期 instructions to the project: place an AGENTS.md (or CLAUDE.md) at the repo root; pi auto-loads at启动:

# Project instruction example (AGENTS.md)

- Run `npm run check` after code modifications.
- Do not执行生产环境迁移 locally.
- Keep answers concise.

No need to restart after modifying上下文 files; execute /reload to生效.

2.5 Upgrade and Version Management

npm install -g @earendil-works/pi-coding-agent@latest   # Upgrade to latest
pi --version                                            # Confirm current version
pi changelog                                            # View version history (also可用 /changelog in interactive)

Disable startup联网 check

pi checks for new versions at startup (可 via PI_SKIP_VERSION_CHECK=1关闭); in离线环境加 --offline to disable all startup networkrequests.

2.6 Quickstart Walkthrough Summary

对照官方 quickstart 的动线：install → authenticate → first session → AGENTS.md → 常见玩法（@ 引用 / ! 命令 / 切模型 / 续聊）→ non-interactive mode.建议现在就在一个玩具项目上完整走一遍,再进入下一章了解 provider 与模型的配置细节.

Chapter Summary

• Install with npm i -g --ignore-scripts @earendil-works/pi-coding-agent; data independently stored in ~/.pi/agent/;
• Authentication两条路: /login subscription OAuth, or API Key env var/auth.json;
• Default tools read/write/edit/bash即可 most tasks; git is your rollback保险;
• @ file refs, ! command execution, -c/-r/--name session管理 are四大高频操作;
• Project级 instructions写进 AGENTS.md; changes生效后 /reload.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the官方推荐的 pi install命令?

2. After uninstalling pi, which type of data仍保留?

3. In the editor, to have a command's output "only for yourself to see, not sent to the model", use?

4. After modifying the project's AGENTS.md, the correct做法 to make it生效 is?

🛠️ Hands-on Practice

1. Install pi and complete一次认证 via /login or env var; record your selected provider and理由.
2. In a git repo have pi "summarize the repo and explain how to run tests"; observe which tools it调用 and the order.
3. Write a minimal AGENTS.md for that project (at least 3 conventions); restart pi and verify it complies (e.g.要求 it append "read AGENTS.md" at the end of answers).

Ran through the first task? Proceed to Chapter 3: Providers and Models Config to彻底玩明白 the model layer.