Pi Agent Installation

This chapter explains how to install Pi Agent on different platforms and complete the basic environment configuration.

Environment Requirements

Before installing Pi Agent, please make sure your system meets the following requirements:

Dependency	Minimum Version	Description
Node.js	18 LTS or higher recommended	Pi Agent runs on Node.js and requires a runtime environment that supports modern JavaScript features
npm	Bundled with Node.js	Used to install Pi Agent and extension packages
Terminal	Supports True Color	Recommended: iTerm2 (macOS), Windows Terminal, Kitty, WezTerm

Check whether Node.js is installed:

node --version

Output similar to:

v20.11.0

Check whether npm was installed along with it (it comes with Node.js):

npm --version

Output similar to:

10.2.4

If your Node.js version is below 18, please upgrade it first. You can use nvm (Node Version Manager) to manage multiple Node.js versions.

Installation

Method 1: Global Installation via npm

This is the most common and simplest installation method, suitable for macOS, Linux, and Windows:

# 全局安装 Pi Agent
# --ignore-scripts 禁用依赖包的生命周期脚本，提高安装安全性
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Verify the version after installation:

pi --version

After installation,pithe command can be used directly in the terminal.

Method 2: One-Click Script via curl

On Linux or macOS, you can also use the official installation script:

# 使用 curl 下载并执行安装脚本
curl -fsSL https://pi.dev/install.sh | sh

This script automatically detects your system and completes the installation. Essentially, it also installs globally via npm.

Method 3: Other Package Managers

If you use pnpm, Yarn, or Bun, you can also install with the corresponding command:

# 使用 pnpm 安装
pnpm add -g @earendil-works/pi-coding-agent

# 使用 Yarn 安装
yarn global add @earendil-works/pi-coding-agent

# 使用 Bun 安装
bun install -g @earendil-works/pi-coding-agent

Uninstallation Methods

When uninstalling Pi Agent, use the same package manager you used for installation:

# npm 或 curl 安装的用 npm 卸载
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 Agent will not delete your configuration, credentials, or session records. This data is stored in the~/.pi/agent/directory. To completely remove it, you can manually delete that directory.

Terminal Recommendations

Pi Agent uses 24-bit RGB color to render the terminal interface. The following terminals are recommended for the best experience:

Platform	Recommended Terminal	Description
macOS	iTerm2、Kitty、Warp	Native True Color support with good embedded image display
Windows	Windows Terminal、WezTerm	Windows Terminal is the officially recommended modern terminal
Linux	Kitty、WezTerm、Alacritty	Both support True Color and GPU acceleration

For more terminal tools, see:https://www.example.com/w3cnote/terminal-tools.html

Check whether your terminal supports True Color:

$ echo $COLORTERM
truecolor

If the output istruecoloror24bit, your terminal supports full color rendering.

First Run

After installation, enter a project directory and start Pi Agent:

$ cd /path/to/your-project
$ pi

On first launch, you will see the Pi Agent welcome screen.

At this point, no AI provider has been configured yet. You need to complete authentication first—this will be explained in detail in the next chapter.

When Pi Agent starts, it uses the current working directory (cwd) as the project root. It has read and write permissions for files in the directory. It is recommended to use it under git version control so that changes can be easily rolled back.

Updating Pi Agent

Keep Pi Agent updated to the latest version:

# 仅更新 Pi Agent 本身
pi update --self

# 更新 Pi Agent 和所有已安装的扩展包
pi update --all

# 更新模型目录（获取最新的可用模型列表）
pi update --models

Using--self --forceforces a reinstall of Pi Agent, even if it is already the latest version:

$ pi update --self --force

Note that installations managed by installation scripts such as install.sh do not support--force。

When such a managed installation needs to be repaired, simply run the installation script again.

Other Extensions

Reference Favorites