Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This guide walks through using the Pi coding agent CLI to interact with an LLM. You’ll:
  1. Install the coding agent
  2. Authenticate with a provider
  3. Run your first interactive session
  4. Try file operations and bash commands
  5. Explore customization options
Time to Complete: 5 minutes
Prerequisites: Node.js 20+, API key or OAuth subscription

​
Installation

Install the coding agent globally: 
npm install -g @mariozechner/pi-coding-agent
Verify installation: 
pi --version
# Output: 0.55.3 (or latest version)

​
Authentication

Choose your authentication method:
Set an environment variable for your provider:
# Anthropic (recommended for getting started)
export ANTHROPIC_API_KEY=sk-ant-...

# Or OpenAI
export OPENAI_API_KEY=sk-...

# Or any other provider - see full list
pi --list-models
Don’t have an API key? Get one from:
  • Anthropic - Free credits available
  • OpenAI - Pay as you go
  • Groq - Free tier with fast inference

​
Your First Session

1

Start Pi

Launch the interactive interface:
pi
You’ll see the Pi interface with:
  • Header: Keyboard shortcuts and loaded configuration
  • Messages area: Conversation history
  • Editor: Where you type (bottom of screen)
  • Footer: Working directory, session, tokens, cost, model
Pi Interactive Mode
2

Send a Message

Type in the editor and press Enter:
Hello! Can you help me understand what you can do?
The model will respond with its capabilities. Watch the footer to see:
  • Tokens used (input + output)
  • Cost (accumulated for session)
  • Context usage (how full the context window is)
3

Try File Operations

Pi has built-in tools: read, write, edit, and bash. Try:
Create a simple Python hello world script in hello.py
You’ll see:
  1. The model calls the write tool
  2. Tool execution creates hello.py
  3. Model responds confirming creation
Verify the file was created:
Show me what's in hello.py
4

Execute Commands

Run the script you just created:
Run the hello.py script
The model will use the bash tool to execute:
python hello.py
You can also run bash commands directly from the editor:
  • !python hello.py - Runs command and sends output to LLM
  • !!ls -la - Runs command without sending output to LLM

​
Editor Features

The Pi editor has several helpful features:
Press Shift+Enter (or Ctrl+Enter on Windows Terminal) for new lines:
Create a function that:
- Takes a list of numbers
- Returns the average
- Handles empty lists gracefully
Type @ to fuzzy-search and reference files:
Review @src/main.ts and suggest improvements
The file content will be included in the message automatically.
Paste images with Ctrl+V (or Alt+V on Windows) or drag onto terminal:
What's in this screenshot?
Only works with vision-capable models like GPT-4o, Claude Sonnet, or Gemini.
Execute commands directly from the editor:
  • !ls -la - Run and send output to model
  • !!git status - Run without sending output
Useful for checking state before asking questions:
!git diff
Explain these changes and suggest a commit message

​
Essential Keyboard Shortcuts

Navigation
  • Ctrl+L - Switch model
  • Shift+Tab - Cycle thinking level
  • Ctrl+P / Shift+Ctrl+P - Cycle models
Control
  • Escape - Cancel/abort
  • Escape twice - Open session tree
  • Ctrl+C - Clear editor
  • Ctrl+C twice - Quit Pi
View
  • Ctrl+O - Toggle tool output
  • Ctrl+T - Toggle thinking blocks
Session
  • /tree - Navigate session history
  • /new - Start new session
  • /resume - Load previous session
Type /hotkeys in the editor to see the complete list of keyboard shortcuts.

​
Commands

Type / in the editor to see available commands: 
/model              # Switch LLM model
/scoped-models      # Choose which models appear in Ctrl+P
/settings           # Configure thinking, theme, transport

​
Non-Interactive Usage

Run Pi without the interactive interface: 
# Get response and exit
pi -p "Explain how async/await works"

# With files
pi -p @README.md "Summarize this documentation"

# With images
pi -p @screenshot.png "What's in this image?"

​
Programmatic Usage (SDK)

For building custom applications: 
import { getModel, stream } from '@mariozechner/pi-ai';

const model = getModel('anthropic', 'claude-sonnet-4-20250514');

const s = stream(model, {
  messages: [{ role: 'user', content: 'Hello!' }]
}, {
  apiKey: process.env.ANTHROPIC_API_KEY
});

for await (const event of s) {
  if (event.type === 'text_delta') {
    process.stdout.write(event.delta);
  }
}

​
Next Steps

Interactive Mode Guide

Master keyboard shortcuts, commands, and the message queue

Sessions & Branching

Learn session management and the tree view for exploring conversation branches

Customization

Add extensions, skills, prompt templates, and themes

LLM Providers

Connect to 15+ providers and configure custom models

Building Extensions

Extend Pi with custom tools, commands, and UI

API Reference

Explore the complete programmatic API

​
Common Questions

Press Ctrl+L in the interactive mode, or use /model.To cycle through favorite models, use Ctrl+P and Shift+Ctrl+P. Configure which models appear with /scoped-models.
Sessions auto-save to ~/.pi/agent/sessions/ organized by working directory.Continue the most recent session with pi -c or browse all sessions with pi -r.
Set API keys for multiple providers in your environment:
export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...
export GROQ_API_KEY=...
Switch between them with Ctrl+L or /model command.
Yes, create .pi/SYSTEM.md (project-specific) or ~/.pi/agent/SYSTEM.md (global).Or append without replacing via APPEND_SYSTEM.md.
Create a TypeScript extension in ~/.pi/agent/extensions/ or .pi/extensions/:
export default function(pi) {
  pi.registerTool({
    name: 'my_tool',
    description: 'Does something useful',
    parameters: Type.Object({ ... }),
    execute: async (params) => { ... }
  });
}
See Building Extensions for details.
Extensions are TypeScript modules that add tools, commands, UI, and event handlers. They have full access to the Pi API.Skills are Markdown files that provide on-demand instructions to the model. They follow the Agent Skills standard.Use extensions for functionality, skills for guidance.

​
Troubleshooting

The global install path isn’t in your PATH. Either:
  1. Use npx: npx @mariozechner/pi-coding-agent
  2. Or fix npm global path: 
    npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
Verify the environment variable:
echo $ANTHROPIC_API_KEY  # Should output your key
Or pass it explicitly:
pi --api-key sk-ant-... "Hello"
Ensure your terminal supports 256 colors and Unicode:
echo $TERM  # Should be xterm-256color or similar
For Windows, use Windows Terminal instead of cmd.exe.See terminal setup guide.
Long sessions may exceed the model’s context window. Pi handles this with automatic compaction:
  • Manual: /compact or /compact <custom instructions>
  • Automatic: Enabled by default in /settings
Or start a fresh session with /new.

​
Learn More

Core Concepts

Understand the architecture

LLM Tools

Function calling and validation

Agent Events

Event-driven agent architecture

SDK Guide

Build custom applications

Examples

Browse code examples

Community

Join the Discord

Build docs developers (and LLMs) love

Get started for freeTalk to us