Christian Klotz
25cc5c7bf4
* docs(coding-agent): improve getting started documentation * docs(coding-agent): correct getting started details * docs(coding-agent): clarify SDK entry point * docs(coding-agent): restructure guides and references * docs(coding-agent): improve getting started guides * docs(coding-agent): refresh integration guides * docs(coding-agent): improve terminal and CLI guides * docs(coding-agent): refresh customisation guides * docs(coding-agent): clarify project trust terminology * docs(coding-agent): simplify customisation guidance * docs(coding-agent): improve runtime and reference guidance * Fix settings reference * feat(coding-agent): add Crowdin documentation sync * docs(coding-agent): separate CLI and slash command references * docs(coding-agent): correct compaction reference * docs(coding-agent): streamline package documentation * docs(coding-agent): split RPC reference documentation * Update configuration docs * Shorten config docs * docs(coding-agent): refine configuration references * docs(coding-agent): streamline settings reference * docs(coding-agent): clarify configuration reference * docs(coding-agent): clarify project trust exception * docs(coding-agent): simplify keybindings reference * docs(coding-agent): remove Crowdin integration * docs(coding-agent): turn themes reference into guide * docs(coding-agent): consolidate model and authentication docs * docs(tui): require Component.invalidate() (fixes #9358) * docs(coding-agent): document offline catalog behavior (fixes #8684) * docs(coding-agent): preserve established documentation routes * docs(coding-agent): reorganize documentation navigation * docs(coding-agent): correct audited behavior Clarify provider, session, local-model, Termux, TUI, SDK, debug, and extension behavior. Simplify the documentation audit to report only clear user-visible contradictions. * docs(coding-agent): fix broken documentation links
4.1 KiB
Quickstart
Pi runs in your terminal and works with files on your machine. To use it, you need access to a model through a supported provider. This can be a subscription, an API key, or a local model.
For native Windows setup, read Windows Setup. For Android, read Termux Setup.
1. Install Pi
On macOS or Linux, you can use the installer:
curl -fsSL https://pi.dev/install.sh | sh
Alternatively, install Pi from npm. This requires Node.js 22.19 or newer:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Pi does not require dependency lifecycle scripts for a normal npm installation.
Verify the installation:
pi --version
2. Start Pi
Change to the folder you want Pi to work with, then start it:
cd /path/to/folder
pi
The working folder helps Pi discover relevant files, instructions, and configuration. Pi also uses it to group saved sessions.
The interface shows your conversation, an editor for prompts and commands, and a footer with the current folder, model, and session status. See Use Pi in the terminal to learn how to add files, run commands, direct ongoing work, and manage results.
3. Choose a model
A model generates Pi's responses. A provider is the service or account Pi uses to access that model.
In Pi, run:
/login
Choose a provider, then follow the prompts to use a subscription or store an API key. Run /model afterward if you want to select a different available model.
See Choose a model and provider for supported providers, environment-variable authentication, local models, and custom endpoints.
4. Give Pi a task
Pi shows each file read, search, command, and edit it performs. It does not ask before every tool call.
Enter a task that matches your work, for example:
Summarize @meeting-notes.md and save the action items to action-items.md.
Explain how this repository is structured and how to run its checks.
Compare @previous.csv with @current.csv and summarize the important changes.
Type @ in the editor to search for a file instead of entering its full path. When Pi finishes, review its response and any changed files. Use version control or backups for important work. For untrusted or unattended work, use a container or another sandbox. See Security.
Continue later
Pi saves sessions automatically. Exit Pi, then resume the most recent session for the same working folder with:
pi --continue
Use /resume to choose another saved session. See Continue or branch a session for session naming, branching, compaction, export, and sharing.
Next steps
- Use Pi interactively to learn input, commands, shortcuts, and queued messages.
- Add instructions that Pi should follow whenever it works in a folder.
- Choose a model and provider.
Choose how to customize Pi
Start with the least powerful mechanism that meets your need:
| Need | Start with |
|---|---|
| Give Pi persistent instructions for a folder | AGENTS.md |
Reuse a prompt from the / menu |
Prompt template |
| Add task-specific instructions and supporting files | Skill |
| Add executable tools, commands, or event handlers | Extension |
| Build a custom terminal component | Terminal UI |
| Connect an unsupported model service | Custom provider |
| Install or distribute several resources | Pi package |
Uninstall Pi
If you installed Pi with npm, run:
npm uninstall -g @earendil-works/pi-coding-agent
If you used the installer, run it again and choose Uninstall Pi:
curl -fsSL https://pi.dev/install.sh | sh
Neither method removes configuration, credentials, sessions, or installed Pi packages from ~/.pi/agent/.