making the default Pi setup simpler & easier

pi-openrouter-setup.md

Here's the full setup to make Pi use OpenRouter by default, with your API key stored locally inside Pi's own config (no system-wide env var needed):

---

Step 1 — Create Pi's config directory (if it doesn't exist)

mkdir -p ~/.pi/agent

This is where Pi stores all its config. It's scoped entirely to Pi — nothing else on your Mac touches it.

---

Step 2 — Store your OpenRouter API key

Open (or create) the auth file:

nano ~/.pi/agent/auth.json

Add this (replace with your actual key from https://openrouter.ai/keys):

{
  "openrouter": {
    "type": "api_key",
    "key": "sk-or-your-key-here"
  }
}

The format matters — it must have "type": "api_key" and "key", not "apiKey". Pi reads this file before checking environment variables, so you don't need to export anything to your shell profile. Your key stays inside Pi's directory only.

Optional — extra security with macOS Keychain:

If you'd rather not store the key as plaintext in a JSON file, you can store it in macOS Keychain instead:

security add-generic-password -a "openrouter" -s "openrouter" -w "sk-or-your-key-here"

Then reference it in auth.json like this:

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

The ! prefix tells Pi to execute that command and use the output as the key.

---

Step 3 — Set OpenRouter as the default provider

Open (or create) the settings file:

nano ~/.pi/agent/settings.json

Add this:

{
  "defaultProvider": "openrouter",
  "defaultModel": "anthropic/claude-sonnet-4"
}

Replace the model ID with whatever you prefer from https://openrouter.ai/models. The format is always author/model-name.

This means every time you run pi, it automatically uses OpenRouter with your chosen model. No --provider or --model flags needed.

---

Step 4 — Run Pi

pi

That's it. Pi reads your API key from auth.json, uses OpenRouter as the provider, and loads your default model. Just start typing.

---

Quick reference after setup:

• Switch models mid-session: Ctrl+L or /model
• Cycle favorite models: Ctrl+P
• Change thinking level: Shift+Tab
• Continue last session: pi -c
• Browse past sessions: pi -r