Installation

Requirements

Node.js

Version 20.0.0 or later requiredCheck version: node --version

Bash Shell

Required for executing bash tool commandsBuilt-in on macOS/Linux. Git Bash on Windows.

Install Pi

npm (Global)
npm (Local)
From Source

Install Pi globally to use the pi command anywhere:

npm install -g @mariozechner/pi-coding-agent

Verify installation:

pi --version

Install Pi locally in a specific project:

npm install @mariozechner/pi-coding-agent

Run using npx:

npx pi

Clone the repository and build from source:

git clone https://github.com/badlogic/pi-mono.git
cd pi-mono
npm install
npm run build
./pi-test.sh

This runs Pi from the built source instead of the globally installed version.

Platform-Specific Setup

macOS

Pi works out of the box on macOS with Node.js 20+ installed.Install Node.js:

# Using Homebrew
brew install node

# Or download from nodejs.org

Install Pi:

npm install -g @mariozechner/pi-coding-agent
pi

For clipboard support with images, the @mariozechner/clipboard optional dependency is automatically installed.

Linux

Pi requires Node.js 20+ and a bash shell (usually pre-installed).Install Node.js:

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Or using package manager
# Ubuntu/Debian:
sudo apt update
sudo apt install nodejs npm

# Fedora:
sudo dnf install nodejs npm

Install Pi:

npm install -g @mariozechner/pi-coding-agent
pi

Windows

Pi requires a bash shell on Windows. The easiest option is Git Bash from Git for Windows.

Install Git for Windows

Download and install from git-scm.comThis includes Git Bash at C:\Program Files\Git\bin\bash.exe

Install Node.js

Download and install from nodejs.orgVerify installation in Git Bash:

node --version

Install Pi

In Git Bash or PowerShell:

npm install -g @mariozechner/pi-coding-agent
pi

Custom Shell Path:If you use Cygwin, MSYS2, or WSL, specify the bash path in ~/.pi/agent/settings.json:

{
  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
}

Windows Terminal Note:In Windows Terminal, use Ctrl+Enter for multi-line input instead of Shift+Enter.

See the Windows setup guide for more details.

Termux (Android)

Pi runs on Android through Termux, a Linux terminal emulator.

Install Termux

Download from GitHub or F-Droid (NOT Google Play)

Install Termux:API

Install Termux:API for clipboard support

Install dependencies

pkg update && pkg upgrade
pkg install nodejs termux-api git

Install Pi

npm install -g @mariozechner/pi-coding-agent
mkdir -p ~/.pi/agent
pi

Termux Limitations:

No image clipboard (text only)
Some native dependencies unavailable on ARM64
Storage access requires termux-setup-storage

See the Termux setup guide for a complete AGENTS.md example.

API Key Setup

API Key Providers

Most providers use API keys set via environment variables:

export ANTHROPIC_API_KEY=sk-ant-...
pi

All Supported API Key Providers:

Provider	Environment Variable
Anthropic	`ANTHROPIC_API_KEY`
OpenAI	`OPENAI_API_KEY`
Google Gemini	`GEMINI_API_KEY`
Mistral	`MISTRAL_API_KEY`
Groq	`GROQ_API_KEY`
Cerebras	`CEREBRAS_API_KEY`
xAI	`XAI_API_KEY`
OpenRouter	`OPENROUTER_API_KEY`
Vercel AI Gateway	`AI_GATEWAY_API_KEY`
ZAI	`ZAI_API_KEY`
OpenCode Zen	`OPENCODE_API_KEY`
Hugging Face	`HF_TOKEN`
Kimi For Coding	`KIMI_API_KEY`
MiniMax	`MINIMAX_API_KEY`
MiniMax China	`MINIMAX_CN_API_KEY`

Making API Keys Permanent

Add to your shell configuration file:

Bash
Zsh
Fish

Add to ~/.bashrc:

echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc
source ~/.bashrc

Add to ~/.zshrc:

echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
source ~/.zshrc

set -Ux ANTHROPIC_API_KEY sk-ant-...

Using Auth File

Store credentials in ~/.pi/agent/auth.json instead of environment variables:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." }
}

The auth file is created with 0600 permissions (user read/write only). Advanced: Key Resolution The key field supports three formats:

{
  "anthropic": {
    "type": "api_key",
    "key": "!security find-generic-password -ws 'anthropic'"
  }
}

Cloud Provider Setup

Azure OpenAI

Azure OpenAI uses the Responses API. Set these environment variables:

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
# OR use resource name instead:
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# Optional:
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

Then run:

pi --provider azure-openai-responses --model gpt-4o

Amazon Bedrock

Bedrock supports multiple authentication methods:Option 1: AWS Profile

export AWS_PROFILE=your-profile

Option 2: IAM Keys

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

Option 3: Bearer Token

export AWS_BEARER_TOKEN_BEDROCK=...

Optional region (defaults to us-east-1):

export AWS_REGION=us-west-2

Using Bedrock:

pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

Bedrock Proxy Configuration:If connecting through a proxy:

export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock
export AWS_BEDROCK_SKIP_AUTH=1  # If proxy doesn't require auth
export AWS_BEDROCK_FORCE_HTTP1=1  # If proxy only supports HTTP/1.1

Google Vertex AI

Vertex AI uses Application Default Credentials (ADC):Local Development:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

Production/CI:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

Using Vertex:

pi --provider google-vertex --model gemini-2.5-flash

OAuth Provider Setup

Several providers require OAuth authentication for subscription-based access:

Launch Pi

pi

Start login

/login

Select your provider:

Claude Pro/Max - Anthropic subscription
ChatGPT Plus/Pro - OpenAI Codex models
GitHub Copilot - Copilot subscription
Google Gemini CLI - Free or paid Cloud Code Assist
Google Antigravity - Free Gemini 3, Claude, GPT-OSS

Complete authentication

Follow the browser prompts. Credentials save to ~/.pi/agent/auth.json and auto-refresh.

Provider-Specific Notes:

GitHub Copilot

Press Enter for github.com, or enter your GitHub Enterprise Server domain
If you get “model not supported”, enable it in VS Code:
1. Open Copilot Chat
2. Click model selector
3. Select the model (warning icon)
4. Click “Enable”

Google Providers

Gemini CLI:

Standard Gemini models via Cloud Code Assist
Free tier or paid subscription
For paid: set GOOGLE_CLOUD_PROJECT env var

Antigravity:

Free sandbox with Gemini 3, Claude, GPT-OSS
Any Google account, subject to rate limits

OpenAI Codex

Requires ChatGPT Plus or Pro subscription
Access to GPT-5.x Codex models with extended context
Personal use only; for production, use OpenAI Platform API

Custom Providers

OpenAI-Compatible
Custom Extensions

Use any OpenAI-compatible API (Ollama, vLLM, LM Studio) via models.json:Create ~/.pi/agent/models.json:

{
  "providers": {
    "ollama": {
      "name": "Ollama",
      "api": "openai-completions",
      "baseUrl": "http://localhost:11434/v1",
      "models": [
        {
          "id": "llama-3.1-8b",
          "name": "Llama 3.1 8B",
          "contextWindow": 128000,
          "maxTokens": 32000
        }
      ]
    }
  }
}

Use the model:

pi --provider ollama --model llama-3.1-8b

Environment Variables

Pi supports several environment variables for configuration:

Variable	Description
`PI_CODING_AGENT_DIR`	Override config directory (default: `~/.pi/agent`)
`PI_PACKAGE_DIR`	Override package directory (for Nix/Guix)
`PI_SKIP_VERSION_CHECK`	Skip version check at startup
`PI_CACHE_RETENTION`	Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h)
`VISUAL` or `EDITOR`	External editor for Ctrl+G

Configuration Directories

Pi uses these directories:

~/.pi/agent/
├── auth.json              # OAuth tokens and API keys
├── settings.json          # Global settings
├── keybindings.json       # Custom keybindings
├── models.json            # Custom provider models
├── sessions/              # Session history (JSONL files)
├── extensions/            # Global extensions
├── skills/                # Global skills
├── prompts/               # Global prompt templates
├── themes/                # Global themes
└── AGENTS.md              # Global agent instructions

Project-local configuration:

.pi/
├── settings.json          # Project settings (override global)
├── extensions/            # Project extensions
├── skills/                # Project skills
├── prompts/               # Project prompt templates
├── themes/                # Project themes
└── SYSTEM.md              # Custom system prompt

Verify Installation

Test your installation:

# Check version
pi --version

# List available models
pi --list-models

# Test with a simple prompt (non-interactive)
pi -p "What is 2+2?"

# Start interactive mode
pi

Next Steps

Interactive Mode

Learn the terminal UI, commands, and keyboard shortcuts

Providers & Models

Detailed provider setup and model selection

Settings

Configure thinking levels, themes, and behavior

Customization

Extend Pi with skills, extensions, and packages

Troubleshooting

Permission denied on npm install

If you get permission errors during global install:Option 1: Use nvm (recommended)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
npm install -g @mariozechner/pi-coding-agent

Option 2: Change npm’s default directory

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @mariozechner/pi-coding-agent

Cannot find module errors

If you see module errors after installation:

npm cache clean --force
npm install -g @mariozechner/pi-coding-agent

Bash not found (Windows)

Pi requires bash on Windows. Install Git for Windows:

Download from git-scm.com
Install with default options
Restart your terminal
Run pi again

For other bash environments (Cygwin, MSYS2, WSL), set shellPath in ~/.pi/agent/settings.json.

For more help, visit the Discord community or check GitHub issues.

Get Started

Core Concepts

Guides

Installation

Requirements

Node.js

Bash Shell

Install Pi

Platform-Specific Setup

API Key Setup

API Key Providers

Making API Keys Permanent

Using Auth File

Cloud Provider Setup

OAuth Provider Setup

Custom Providers

Environment Variables

Configuration Directories

Verify Installation

Next Steps

Interactive Mode

Providers & Models

Settings

Customization

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Requirements

Node.js

Bash Shell

​Install Pi

​Platform-Specific Setup

​API Key Setup

​API Key Providers

​Making API Keys Permanent

​Using Auth File

​Cloud Provider Setup

​OAuth Provider Setup

​Custom Providers

​Environment Variables

​Configuration Directories

​Verify Installation

​Next Steps

Interactive Mode

Providers & Models

Settings

Customization

​Troubleshooting

Build docs developers (and LLMs) love

Requirements

Install Pi

Platform-Specific Setup

API Key Setup

API Key Providers

Making API Keys Permanent

Using Auth File

Cloud Provider Setup

OAuth Provider Setup

Custom Providers

Environment Variables

Configuration Directories

Verify Installation

Next Steps

Troubleshooting