Skip to main content

​
Install Pi

Pi is distributed as an npm package and requires Node.js 20 or later.
1

Install Pi globally

npm install -g @mariozechner/pi-coding-agent
This makes the pi command available system-wide.
2

Set up authentication

Choose one of two authentication methods:
Set an environment variable for your preferred provider:
export ANTHROPIC_API_KEY=sk-ant-...
Add this to your ~/.bashrc or ~/.zshrc to make it permanent.
Supported providers:
  • ANTHROPIC_API_KEY - Anthropic
  • OPENAI_API_KEY - OpenAI
  • GEMINI_API_KEY - Google Gemini
  • GROQ_API_KEY - Groq
  • MISTRAL_API_KEY - Mistral
  • And many more
3

Launch Pi

pi
You’ll see the interactive terminal interface with an editor at the bottom.
4

Start coding

Type your request and press Enter:
List all TypeScript files in this directory
Pi will use the built-in tools (read, write, edit, bash) to fulfill your request.

​
Your First Session

Let’s walk through a typical Pi session: 
# Start Pi in your project directory
cd ~/my-project
pi

# Pi loads and shows the interface
# Type your first message:
"Create a simple HTTP server in Node.js that responds with 'Hello World'"

# Pi will:
# 1. Create a new file (server.js)
# 2. Write the code
# 3. Show you what it did

# Continue the conversation:
"Add a /status endpoint that returns JSON"

# Pi edits the existing file and shows the changes
Sessions auto-save to ~/.pi/agent/sessions/ organized by working directory. Use pi -c to continue your most recent session.

​
Essential Commands

Type / in the editor to see all commands. Here are the most useful:
CommandDescription
/modelSwitch between LLM models
/settingsAdjust thinking level, theme, and more
/treeNavigate session history and branches
/copyCopy last assistant message to clipboard
/hotkeysShow all keyboard shortcuts
/quitExit Pi

​
Essential Keyboard Shortcuts

KeyAction
Ctrl+LOpen model selector
Ctrl+P / Shift+Ctrl+PCycle through models
Shift+TabCycle thinking level (off → minimal → low → medium → high → xhigh)
EscapeCancel current operation
Escape twiceOpen session tree view
Ctrl+CClear editor (press twice to quit)
Ctrl+OCollapse/expand tool output
@Fuzzy-search and reference files
Use Shift+Enter (or Ctrl+Enter on Windows Terminal) for multi-line input.

​
File References

Include files in your messages using the @ symbol: 
@src/server.ts Review this file for security issues
Type @ and start typing to get fuzzy-search suggestions. You can reference multiple files: 
@package.json @README.md Update the dependencies and document the changes

​
Running Bash Commands

Prefix commands with ! to run them and send output to the LLM: 
!ls -la src/
Use !! to run without sending output: 
!!npm install lodash

​
Session Management

pi -c
Resumes the most recent session for the current directory.
pi -r
Opens an interactive picker to select from past sessions.
Inside Pi, press Escape twice to open the session tree. Navigate to any point in history, then:
  • Press Enter to continue from that point
  • Type /fork to create a new session file from that branch
/export my-session.html
Creates a standalone HTML file with your session.
/share
Uploads your session as a private GitHub gist with a shareable HTML link.

​
Switching Models

Pi supports 20+ LLM providers. Switch models at any time:
1

Open model selector

Press Ctrl+L or type /model
2

Choose your model

Use arrow keys and search to find your model. The list shows:
  • Model name and provider
  • Context window size
  • Pricing (input/output tokens)
  • Whether it supports vision and reasoning
3

Continue conversation

Your session continues with the new model. Pi handles cross-provider compatibility automatically.
Use pi --models "claude-*,gpt-4o" to limit Ctrl+P cycling to specific model patterns.

​
Next Steps

Now that you have Pi running, explore these key areas:

Installation Details

Platform-specific setup, API keys, and advanced configuration

Interactive Mode

Master the terminal UI, editor features, and message queue

Providers & Models

Set up multiple providers and understand model selection

Customization

Extend Pi with skills, extensions, and prompt templates

​
Troubleshooting

After installing globally, you may need to restart your terminal or reload your shell:
source ~/.bashrc  # or ~/.zshrc
If that doesn’t work, check your npm global bin directory is in PATH:
npm config get prefix
# Should output a path like /usr/local or ~/.npm-global
If you see authentication errors:
  1. Verify your API key is set correctly: 
    echo $ANTHROPIC_API_KEY
  2. Check the key format matches your provider’s requirements
  3. For OAuth providers, try logging out and back in: 
    pi
/logout
/login
Pi requires bash on Windows. Install Git for Windows which includes Git Bash.See the Windows setup guide for details.
Pi requires Node.js 20 or later. Check your version:
node --version
If needed, install a newer version from nodejs.org or use nvm:
nvm install 20
nvm use 20
For more help, join the Discord community or check the GitHub issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us