3 Installing & configuring pi
You can install the pi command-line interface (CLI) from npm, verify it runs, and find your way around its help, configuration directory, and bundled documentation.
3.1 Prerequisites
pi is a Node.js CLI, so you need a recent Node and npm:
node --version # e.g. v26.x (Node 20+ is fine)
npm --versionIf Node is missing, brew install node.
3.2 Install
npm install -g --ignore-scripts @earendil-works/pi-coding-agentThis installs the CLI as the command pi. Verify:
pi --version # e.g. 1.4.0
pi --help # full flag reference--ignore-scripts?
--ignore-scripts skips any package lifecycle scripts during install. It is a sensible default hardening step for any globally installed CLI (pi does not require post-install scripts to function), and it is the install line pi’s own documentation shows.
A note on naming history: pi was originally published under @mariozechner/… in the badlogic/pi-mono repository; it now lives at earendil-works/pi (Zechner 2026) and publishes the @earendil-works/pi-coding-agent package. If you find older blog posts referencing the @mariozechner package, they describe the same tool.
3.3 What you just installed
The package is a small monorepo of four parts; as a user you mostly care about the last one.
| Package | Role |
|---|---|
pi-ai |
Unified API (application programming interface) over Anthropic / OpenAI / Google / any OpenAI-compatible endpoint |
pi-agent-core |
The agent loop: tool calls, state, streaming |
pi-tui |
The terminal user interface (UI) |
pi-coding-agent |
The pi CLI you run |
3.4 The configuration directory
pi keeps global configuration under ~/.pi/agent/:
ls ~/.pi/agent/
# auth.json ← credentials for cloud providers (not needed for local backends)
# models.json ← custom providers/models (we create this in the next chapter)You will create ~/.pi/agent/models.json in Chapter 4. For local-only use you do not need auth.json or any API key.
3.5 The bundled documentation
A real advantage of pi is that its full docs ship inside the package: handy offline and always matched to your installed version. Find them with:
ls "$(npm root -g)/@earendil-works/pi-coding-agent/docs"
# models.md custom-provider.md providers.md usage.md rpc.md sessions.md …docs/models.md and docs/custom-provider.md are the authoritative reference for the configuration in the next chapter.
3.6 Keeping pi up to date
pi update self # update the pi CLI itself
pi update --all # update pi and any installed extensions- Run
pi --helpand find the flags for non-interactive mode, choosing a provider, and listing models. You will use all three in Chapter 5. - Open
docs/usage.mdfrom the bundled docs and skim the “Non-interactive” section. - Inspect
~/.pi/agent/before and after first run: which files appear?
- Non-interactive mode is
-p/--print(process the prompt and exit); the provider is chosen with--provider(e.g.--provider lmstudio); models are listed with--list-models. These are the three flags combined throughout Chapter 5, for examplepi -p --offline --provider lmstudio --model 'qwen3-coder-30b-a3b-instruct' "...". - The “Non-interactive” section of
docs/usage.mddocuments the same one-shot usage shown here: pass-p/--printwith a prompt string so pi runs the request and exits, which is the mode used for scripting and quick trials. (Exact wording depends on your installed version, since the docs ship matched to the package.) - Before any run,
~/.pi/agent/is typically empty or absent. After installing and using pi you will see credential and configuration files appear there, notablyauth.json(cloud credentials, not needed for local backends) and, once you create it in Chapter 4,models.jsonfor custom providers and models. For local-only use noauth.jsonor API key is required.