3  Installing & configuring pi

NoteLearning objective

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  --version

If Node is missing, brew install node.

3.2 Install

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

This installs the CLI as the command pi. Verify:

pi --version     # e.g. 1.4.0
pi --help        # full flag reference
NoteWhy --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
TipExercises
  1. Run pi --help and find the flags for non-interactive mode, choosing a provider, and listing models. You will use all three in Chapter 5.
  2. Open docs/usage.md from the bundled docs and skim the “Non-interactive” section.
  3. Inspect ~/.pi/agent/ before and after first run: which files appear?
  1. 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 example pi -p --offline --provider lmstudio --model 'qwen3-coder-30b-a3b-instruct' "...".
  2. The “Non-interactive” section of docs/usage.md documents the same one-shot usage shown here: pass -p/--print with 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.)
  3. Before any run, ~/.pi/agent/ is typically empty or absent. After installing and using pi you will see credential and configuration files appear there, notably auth.json (cloud credentials, not needed for local backends) and, once you create it in Chapter 4, models.json for custom providers and models. For local-only use no auth.json or API key is required.