/setup

name: setup
description: Guides the user through configuring pi — provider, model, base URL, and API key. Use when the user asks to "setup pi", "configure pi", "pi setup", "set up pi provider", "pi config", "change pi model", or invokes /pi:setup. Only run this skill when the user explicitly requests pi setup — never auto-invoke.
user-invocable: true
disable-model-invocation: true
argument-hint: "[--endpoint NAME] [--provider PROVIDER] [--model MODEL] [--base-url URL] [--api-key KEY] | --edit-config | --list-models | --test | --doctor"
allowed-tools: ["Bash(pi:*)", "Bash(jq:*)", "Bash(cat:*)", "Bash(mkdir:*)", "Bash(mv:*)", "Bash(echo:*)", "Bash(command -v:*)", "Bash(ls:*)", "Bash(vi:*)", "Read", "Write"]

CRITICAL: User setup only — do not auto-invoke

This skill is for **human-only** setup. Never invoke it automatically. Only run when the user explicitly calls `/pi:setup`. Configure pi's provider, model, and endpoint so `/pi:delegate` and `/pi:review` can use them without repeating flags.

Before Execution: Check Installation

command -v pi >/dev/null 2>&1

If not installed, guide the user:

npm install -g @earendil-works/pi-coding-agent

Or via the standalone installer:

curl -fsSL https://pi.dev/install.sh | sh

Then stop — do not proceed without pi installed.

Settings File

Both `/pi:delegate` and `/pi:review` read from the same settings chain:

1. **CLI flag** (from `$ARGUMENTS`) 2. **`.claude/pi.local.json`** — project-specific overrides, gitignored 3. **`.claude/pi.json`** — project shared defaults, committed 4. **`~/.claude/pi.local.json`** — global user-wide defaults 5. **pi's own defaults** (pi decides its own default provider and model)

This skill writes to `~/.claude/pi.local.json` (global, takes effect for all projects).

Settings file format

The settings file uses the **named-endpoint format** shared by `/pi:delegate` and `/pi:review`. All fields are optional — only override what you want to change.

Values can reference environment variables using `$VAR` or `${VAR}` syntax — they are resolved at read time by `/pi:delegate` and `/pi:review`. This is useful for API keys: `"apiKey": "$MY_API_KEY"` reads from the environment variable at runtime.

{
  "endpoints": {
    "local-proxy": {
      "provider": "openai",
      "baseUrl": "http://10.10.0.195:8317/v1",
      "models": ["gemini-3.6-flash-high", "gemini-3.6-pro"]
    }
  },
  "defaultEndpoint": "local-proxy",
  "defaultModel": "gemini-3.6-flash-high",
  "thinking": "max",
  "withPackages": false
}

Each endpoint key has:

• `provider` (required) — pi's known provider name (`openai`, `anthropic`, `google`, etc.)
• `baseUrl` (optional) — custom API endpoint; when present it is written to `~/.pi/agent/models.json` at runtime
• `apiKey` (optional) — API key or `$ENV_VAR` reference
• `models` — array of model IDs available via this endpoint

Top-level `withPackages` (default false) is the clean-mode escape hatch: when true, `/pi:delegate` and `/pi:review` load packages/skills/extensions from the **pi CLI home** (`~/.pi`, configured via `pi install` / `pi list` — not Claude Code plugins). Leave it false unless you intentionally want bridge tasks to inherit that interactive pi configuration.

Legacy flat fields (`provider`/`model`/`baseUrl`/`apiKey`) are still honored by the delegate skill as a fallback when no `defaultEndpoint` is set, but new setups should use the endpoint format.

`--list-models` flag

When `$ARGUMENTS` is exactly `--list-models`, read the current settings and show the effective configuration:

echo "=== Current pi configuration ==="
echo "Settings file: $HOME/.claude/pi.local.json"
if [ -f "$HOME/.claude/pi.local.json" ]; then
  cat "$HOME/.claude/pi.local.json"
else
  echo "(not configured — pi uses its defaults)"
fi
echo ""
echo "To configure, run: /pi:setup --endpoint <name> --provider <name> --model <id> [--base-url <url>]"
echo "Or use interactive mode: /pi:setup --edit-config"

Then stop — do not proceed to setup.

`--test` flag

When `$ARGUMENTS` includes `--test`, run a quick connectivity test. Build the command as an array so each flag is a distinct argument under both bash and zsh (zsh does not word-split an unquoted `${PROVIDER:+--provider ...}` expansion):

CMD=(pi -p)
# Provider: use the resolved PROVIDER; else if a custom BASE_URL is set, use the
# models.json key (PROVIDER_KEY, default openai) so the probe reaches the custom endpoint.
if [ -n "$PROVIDER" ]; then
  CMD+=(--provider "$PROVIDER")
elif [ -n "$BASE_URL" ]; then
  CMD+=(--provider "${PROVIDER_KEY:-openai}")
fi
# Only pass --model when set — an empty --model is silently accepted by pi but the
# probe then runs without the intended model (setup never resolves MODEL itself).
[ -n "$MODEL" ] && CMD+=(--model "$MODEL")
CMD+=(--thinking low --no-session --no-context-files --approve --no-extensions --no-skills "Reply with exactly: OK. Model: <model-name>")
# </dev/null: pi -p hangs on a terminal/pipe stdin (mis-detects interactive) — force non-interactive.
"${CMD[@]}" </dev/null

Report the result: "pi responded successfully with model <name>" on exit 0, or the error on failure.

Setup Process

Step 1: Detect current state

Show the user their current configuration:

echo "=== Current pi configuration ==="
if [ -f "$HOME/.claude/pi.local.json" ]; then
  cat "$HOME/.claude/pi.local.json"
else
  echo "No configuration file found."
fi

Step 2: Collect configuration from CLI flags or interactive

If `$ARGUMENTS` contains flags, parse them directly:

| Flag | Description | |------|-------------| | `--endpoint` | Endpoint key name (default `local-proxy`) | | `--provider` | LLM provider name (`openai`, `anthropic`, `google`, etc.) | | `--model` | Model ID (e.g. `gemini-3.6-flash-high`, `claude-sonnet-4-20250514`) | | `--base-url` | Custom API endpoint URL (OpenAI-compatible) | | `--api-key` | API key for the provider (stor