@gonkagate/pi-setup

Configure Pi Coding Agent to use GonkaGate as an OpenAI-compatible custom provider with one npx command.

npx -y @gonkagate/pi-setup@latest

@gonkagate/pi-setup is the onboarding CLI for developers who use Pi Coding Agent and want to route models through the GonkaGate API without hand-editing Pi's provider, auth, or default-model config.

What It Does

• Writes a providers.gonkagate entry to ~/.pi/agent/models.json.
• Preserves unrelated Pi providers and top-level config.
• Reads your API key from GONKAGATE_API_KEY, --api-key-stdin, or a hidden prompt.
• Writes a Pi-compatible gonkagate API-key entry to ~/.pi/agent/auth.json.
• Sets defaultProvider and defaultModel in ~/.pi/agent/settings.json.
• Creates sibling backups before replacing existing managed files.
• Installs the curated GonkaGate model catalog for Pi Coding Agent.
• Does not accept a plain --api-key flag and never prints gp-... keys.

Setup success means configured: GonkaGate config and Pi auth/default settings were written or already matched. It does not mean verified; default setup does not make a live GonkaGate API call.

Quick Start

npx -y @gonkagate/pi-setup@latest
pi

For automation, avoid shell history by using stdin:

printf '%s' "$GONKAGATE_API_KEY" | npx -y @gonkagate/pi-setup@latest --yes --api-key-stdin

Preview the generated config without writing:

npx -y @gonkagate/pi-setup@latest --dry-run

Use a custom config path during testing:

npx -y @gonkagate/pi-setup@latest --config ./models.json

Restore from a backup by copying the generated models.json.backup-* file back over ~/.pi/agent/models.json. Auth and settings backups use the same sibling pattern beside auth.json and settings.json.

Limits

The setup is local-file-only and network-free. It does not mutate shell profiles, generate .env files, accept --api-key, support arbitrary custom base URLs, support arbitrary custom model ids, claim concurrent-writer safety, or run default live GonkaGate/Pi verification.

Deferred features require the evidence gates in docs/specs/pi-setup-prd/spec.md before implementation.

Platform Proof

CI is configured for Ubuntu and native Windows. WSL remains a manual smoke target; do not claim WSL-specific proof until the checklist in the PRD has been run inside WSL.

Development

npm install
npm run ci

Product requirements live in docs/specs/pi-setup-prd/spec.md.

The package is intentionally small. It configures Pi's documented custom provider, API-key auth, and default-model settings surfaces.