Installation

✓ Fresh · 2026-02-24

Complete guide to installing Pi Coding Agent, configuring LLM providers, and managing API keys.

Prerequisites

• Node.js 18+ (LTS recommended)
• npm 9+ (comes with Node.js)
• A shell environment (bash, zsh, PowerShell, etc.)

Install Pi

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

After installation, launch Pi by typing:

pi

Authentication: Two Paths

Pi supports two authentication methods: OAuth subscriptions and API keys.

OAuth Subscriptions

Use your existing subscription to a provider:

pi
/login   # select a provider from the interactive list

Supported OAuth providers:

Provider	Subscription Tier
Anthropic	Claude Pro / Claude Max
OpenAI	ChatGPT Plus / ChatGPT Pro
GitHub	Copilot
Google	Gemini CLI
Google	Antigravity

API Keys

Set environment variables before launching Pi:

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Google Gemini
export GEMINI_API_KEY=AIza...

# OpenRouter
export OPENROUTER_API_KEY=sk-or-...

# Then launch
pi

Full list of API key providers:

Provider	Environment Variable
Anthropic	ANTHROPIC_API_KEY
OpenAI	OPENAI_API_KEY
Azure OpenAI	AZURE_OPENAI_API_KEY
Google Gemini	GEMINI_API_KEY
Google Vertex	GOOGLE_VERTEX_*
Amazon Bedrock	AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
Mistral	MISTRAL_API_KEY
Groq	GROQ_API_KEY
Cerebras	CEREBRAS_API_KEY
xAI	XAI_API_KEY
OpenRouter	OPENROUTER_API_KEY
Vercel AI Gateway	VERCEL_AI_GATEWAY_*
ZAI	ZAI_API_KEY
OpenCode Zen	OPENCODE_ZEN_API_KEY
Hugging Face	HUGGINGFACE_API_KEY
Kimi	KIMI_API_KEY
MiniMax	MINIMAX_API_KEY

.env File Handling

IMPORTANT

Pi does NOT auto-load .env files. API keys must be in the shell environment before launching Pi.

Three approaches to manage this:

1. Manual Source

source .env && pi

2. Shell Alias

Add to your ~/.bashrc or ~/.zshrc:

alias pi='source $(pwd)/.env && pi'

3. Just Task Runner

If you use just, it auto-loads .env files:

# justfile
default:
    pi

ext name:
    pi -e extensions/{{name}}.ts

just        # launches pi with .env loaded
just ext minimal   # loads extension with .env

Platform Notes

Windows

• Use PowerShell or Git Bash
• Set environment variables with $env:ANTHROPIC_API_KEY = "sk-ant-..."
• Or use a .env file with the alias approach above in Git Bash

macOS / Linux

• Works natively in any terminal
• For persistent keys, add exports to ~/.bashrc, ~/.zshrc, or ~/.profile

Docker / Containers

Pass API keys via -e flags:

docker run -it -e ANTHROPIC_API_KEY=sk-ant-... pi-image

Verify Installation

pi --version

Launch and confirm you can interact:

pi
# Type: What files are in the current directory?

If Pi responds with a file listing, installation is complete.

Updating

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

Uninstalling

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

To remove all configuration:

rm -rf ~/.pi