$ pi –install

TL;DR. Pi is published as @earendil-works/pi-coding-agent on npm. The recommended path is npm install -g --ignore-scripts @earendil-works/pi-coding-agent; Bun, pnpm, and Yarn all work the same way. v0.84.3 adds an optional powershell tool on Windows that runs through pwsh.exe (-NoProfile -NonInteractive -ExecutionPolicy Bypass) and an experimental installer-managed update flow that stages, verifies, and atomically activates the new release. Updates run with pi update for the CLI itself, pi update --extensions for installed packages, and pi update --all for everything. Pin with pi install npm:pkg@x.y.z or pi install git:host/user/repo@ref, and pin the package manager wrapper with npmCommand in settings.json.

This guide collects every supported install path, the update matrix, and the new v0.84.3 surface (PowerShell tool, managed updates, Windows keybinding defaults). It follows the Quickstart, the Packages documentation, the Windows Setup page, and the v0.84.3 release notes.

Install with npm

Pi is a single npm package. The --ignore-scripts flag disables npm’s install-script hooks, which pi does not need and which can otherwise slow the install:

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

That places pi on the global PATH. pnpm and Yarn work the same way:

pnpm add -g @earendil-works/pi-coding-agent
yarn global add @earendil-works/pi-coding-agent

On Windows, npm installs a pi.cmd shim rather than a directly executable pi binary — see the Windows section below for the implications for extensions and shells that try to launch pi directly.

To uninstall with the same package manager that installed it:

npm uninstall -g @earendil-works/pi-coding-agent
pnpm remove -g @earendil-works/pi-coding-agent
yarn global remove @earendil-works/pi-coding-agent

Uninstalling pi leaves settings, credentials, sessions, and installed pi packages in ~/.pi/agent/ (Windows: %USERPROFILE%\.pi\agent\) so you can reinstall without losing state.

Install with Bun

Bun is supported as a drop-in for npm for the install and uninstall step:

bun install -g @earendil-works/pi-coding-agent
bun uninstall -g @earendil-works/pi-coding-agent

A subtle Bun-specific gotcha landed in v0.84.3: Bun release archives ship the native clipboard binary only inside the wrapper package, not at the top of the install. If you are debugging a missing clipboard on a Bun-installed build, look in the wrapper package’s bin/ rather than next to the binary.

Install on Windows

Windows users install through npm, the same way as on macOS or Linux:

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

npm places a pi.cmd shim on the PATH rather than a directly executable pi binary — this is what npm’s global layout expects, but it has implications for extensions that try to launch pi directly through an absolute path: they need the pi.cmd shim rather than the underlying binary.

For Git on Windows, pi’s default bash tool looks up bash.exe in this order:

Custom path from ~/.pi/agent/settings.json (the shellPath field).
C:\Program Files\Git\bin\bash.exe (Git for Windows).
bash.exe on PATH (Cygwin, MSYS2, WSL).

For most Windows users, “Git for Windows” is sufficient. The official docs flag it as the recommended choice.

The PowerShell tool (v0.84.3)

v0.84.3 ships an optional, native powershell tool on Windows. It runs commands through pwsh.exe when available, falling back to Windows PowerShell. Every invocation passes:

-NoProfile -NonInteractive -ExecutionPolicy Bypass

Administrator-enforced execution policies still take precedence, so on locked-down hosts the tool may surface the same error PowerShell would. The ! and !! editor shell-escape commands still go through Bash, not through this tool — only the model-facing tool surface changes.

Enable it by editing defaultTools in ~/.pi/agent/settings.json (%USERPROFILE%\.pi\agent\settings.json on Windows):

{
  "defaultTools": ["read", "powershell", "edit", "write"]
}

To keep both shells available side-by-side while comparing behavior:

{
  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
}

The Bash default still works without changes; defaultTools only changes which tool the model sees.

Updating pi itself and packages

pi update is the single command family for both CLI and package updates. The bare pi update updates the pi CLI itself; packages and git-ref reconciliation require an explicit flag:

pi update              # update pi itself
pi update --all        # update pi + packages + reconcile pinned git refs
pi update --extensions # update packages and reconcile pinned git refs only
pi update --models     # refresh model catalogs only
pi update --self       # update pi itself (alias for the bare command)
pi update --self --force # reinstall pi even if current
pi update npm:@foo/bar  # update one package
pi update --extension npm:@foo/bar

pi update never prompts for project trust — the update flow runs under your user account without re-prompting.

Managed updates (v0.84.3, experimental)

For experimental installer-managed installations, pi update no longer overwrites the running binary in place. Instead it:

Downloads the target release into a staged, lockfile-backed location.
Verifies the staged release.
Atomically activates the staged release, leaving the current release intact on the disk if activation fails.

This is the same staged-then-activate pattern used by package managers like Nix and Cargo, adapted for a Node-runtime agent. Because verification happens before activation, a corrupt or partial update cannot replace a working binary. Managed installs do not support pi update --self --force; to repair a managed install, re-run the installer that produced it.

The packages documentation notes that managed installs exist but does not currently document the install command that creates one — at the time of writing, npm install -g is the only install method with a documented command. If you already have a managed installation, the staged-update behavior kicks in for every pi update you run.

Pinning versions and refs

Two pinning styles are common:

Pinned to a published version. pi install npm:pkg@1.2.3 records the version in settings.json. Updates through pi update --extensions skip pinned packages; pass --all if you want a reconcile-only operation that does not move the pin.
Pinned to a git ref. pi install git:host/user/repo@ref clones to ~/.pi/agent/git/<host>/<path> (global) or .pi/git/<host>/<path> (project). pi update --extensions and pi update --all reconcile the clone to the configured ref without moving it; to move to a newer ref, run pi install git:host/user/repo@new-ref.

The --all reconcile is useful when a force-push or a rebase has rewritten the pinned commit — pi will reset and clean the clone and run npm install if a package.json is present.

Pinning the package-manager wrapper

When your team standardizes on a non-npm package manager (mise, asdf, volta), pin the wrapper that pi uses for package lookup and install:

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

Without npmCommand, pi shells out to whatever npm is on the PATH at update time — usually fine, occasionally surprising on machines where npm resolves to a different binary than the one that originally installed pi.

Where state lives

After install, all user state lives under ~/.pi/agent/:

Path	Contents
`~/.pi/agent/settings.json`	User-level settings (default tools, providers, trust, npmCommand)
`~/.pi/agent/auth.json`	Resolved provider credentials
`~/.pi/agent/sessions/`	Per-session JSONL history
`~/.pi/agent/extensions/`	User-scope extension packages
`~/.pi/agent/skills/`, `~/.pi/agent/prompts/`, `~/.pi/agent/themes/`	Other user-scope packages
`~/.pi/agent/npm/`, `~/.pi/agent/git/`	Cached installs
`~/.pi/agent/trust.json`	Saved project-trust decisions

For project-local state, the equivalents live under .pi/ next to the project’s package.json (or whichever project root pi was started from). Project installs respect project trust and are gated by defaultProjectTrust plus the --approve / --no-approve flags.

A short pre-deploy checklist

Confirm pi --version matches the version you intended to install.
Decide whether you need a managed install (only available via the experimental installer flow) or a direct npm / Bun install — only the managed path supports staged updates.
On Windows, decide whether to enable the powershell tool via defaultTools; document the choice in your team’s onboarding notes.
Pin runtime versions in CI (pi install npm:@earendil-works/pi-coding-agent@x.y.z) and pin the package wrapper via npmCommand.
Verify SHA-256 checksums of manual binary downloads against the values in the GitHub release’s SHA256SUMS file.

Installing and Updating Pi