Install Pi and see the surfaces it runs on

You’ve got stash cloned locally, you know the feed-date bug is waiting for you, and there’s no agent on the machine yet. This is the shortest lesson in the module, because the install itself is trivial - the framing matters more than the command.

Getting it onto your machine

The simplest path is the one-line installer:

curl -fsSL https://pi.dev/install.sh | sh

If you’d rather go through npm, the canonical package lives under Earendil’s scope (the company that now stewards Pi’s development, alongside its original author):

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

The --ignore-scripts flag is called out deliberately in Pi’s own docs as a supply-chain precaution - worth keeping even though it’s an extra thing to remember. You’ll also see an older package name, @mariozechner/pi-coding-agent, still published and still updated; it’s the pre-stewardship name and works the same way. Either package needs a reasonably recent Node - the current package wants >=22.19.0, with a legacy-node20 version tag kept around if you’re stuck on an older install.

Once it’s on your PATH, launch it from inside the project - like most agents, Pi reasons about the directory it starts in:

> cd ~/work/stash
> pi

One small core, four front doors

Here’s the framing worth setting before you type anything else. What you just installed isn’t really “a CLI with some extra modes bolted on” - it’s a small agent core (the loop, the tools, the model-facing plumbing) that happens to expose itself through several different surfaces, all sharing the exact same behavior underneath:

• Interactive - the TUI you just launched. This is where you’ll spend this whole module: a live prompt, a running conversation, tool calls rendered as you go.
• Print mode - pi -p "your prompt" fires one prompt, runs the loop to completion, and exits. Built for scripts and pipelines rather than a sitting conversation - you could pipe a log file in and ask Pi to summarize it without ever opening the interactive view.
• JSON event-stream mode - --mode json emits every event of the run (tool calls, results, text) as structured lines instead of rendered TUI output, for anything that wants to consume Pi’s behavior programmatically.
• RPC mode - --mode rpc frames the same events as strict newline-delimited JSON over stdin/stdout, specifically so a non-Node process can drive Pi as a subprocess and talk to it without shelling out to a CLI parser.

You won’t touch the last two in this module - they matter a lot once you start spawning Pi from your own code, much later in the course. What matters now is the framing: every habit you build at the interactive prompt this week - how the loop behaves, what it can see, what it’s allowed to do - is the same agent underneath, not a different tool you’ll have to re-learn later when you script it.

Pi is installed and sitting at a live prompt inside stash. It doesn’t know who’s paying for the model yet, though - and that choice has a real, easy-to-miss consequence. Next: bring your own key.