@sandzer0/pi-provider-tui

Interactive TUI to manage Pi custom model providers in ~/.pi/agent/models.json.

Requirements

• Node.js 18+
• Pi coding agent installed (to consume the config)

Install

npm install -g @sandzer0/pi-provider-tui

Or run once without global install:

npx @sandzer0/pi-provider-tui

From source:

git clone https://github.com/sandzer0/pi-provider-tui.git
cd pi-provider-tui
npm install
npm run build
npm link

Usage

pi-provider-tui

Override config path:

PI_MODELS_PATH=/tmp/models.json pi-provider-tui

Main menu: List / Add / Edit / Remove / Test connection / Run health checks (doctor) / Undo last write / Quit

Reasoning pre-fill: when models are fetched from a gateway or entered manually, the reasoning flag is pre-filled from id patterns (o-series, gpt-5+, deepseek-r*, qwq/qwen3+, claude 3.7+/4.x, gemini 2.5+, grok 4+, …) — always overridable.

Supported API types:

• openai-completions
• openai-responses
• anthropic-messages
• google-generative-ai

anthropic-messages baseUrl convention: enter the API root without /v1 (e.g. https://api.anthropic.com or https://proxy.example.com) — pi appends /v1/... itself when talking to the Anthropic SDK. This tool follows the same rule for model fetching and connection tests, and doctor flags entries that end with /v1.

Edit → models supports: list, add (manual or from gateway), edit one, remove, replace all. Edit → provider also covers custom request headers and pi's compat overrides (common fields as tri-state prompts plus a raw-JSON editor for advanced routing options). Editing a model preserves fields this tool does not manage (samplingParams, model-level compat, …).

Secrets: apiKey accepts pi's value-resolution forms — a literal (sk-...), an environment reference ($MY_KEY or ${MY_KEY}), or a command (!op read ...). References are resolved at request time by pi and by this tool when testing; the raw value is stored in models.json untouched.

Test connection has two modes:

• Endpoint + auth check — GET {baseUrl}/models, no tokens used
• Full request — tiny completion per API type (may cost tokens)

After saving, verify:

pi --list-models

Non-interactive CLI

Every common operation is also scriptable:

pi-provider-tui add --id my-gw --base-url https://gw.example.com/v1 \
    --api openai-completions --key '$MY_KEY' --models foo,bar -y
pi-provider-tui list [--json]
pi-provider-tui get --id my-gw
pi-provider-tui remove --id my-gw -y
pi-provider-tui test --id my-gw [--model foo] [--mode endpoint|full] [--json]
pi-provider-tui doctor [--json]
pi-provider-tui undo -y
pi-provider-tui version

PI_MODELS_PATH overrides the config path for all commands. Exit codes: 0 ok, 1 operation failed, 2 usage error.

Merging fetched models that already exist locally asks whether to keep your local settings or overwrite them. Lists longer than 15 models offer a keyword filter before selection; every model list (pickers and read-only views) is shown in a scrollable viewport or paginated so huge gateway catalogs stay usable.

Security

API keys are stored in plaintext in models.json by design. The tool sets file mode 0600 on write. Do not use on shared machines without additional secret management.

Backup

Every write rotates a rolling history of the previous file versions: models.json.bak.1 (most recent) through models.json.bak.5. The main menu's Undo last write restores .bak.1 and steps back through history; on corrupt JSON at startup the TUI offers restore from the most recent backup (legacy single-file models.json.bak is still honored).

Health checks

Run health checks (doctor) scans the config for common mistakes: missing baseUrl/api on custom providers, unknown API types, unset environment variables referenced by apiKey, duplicate endpoints or model ids, invalid limits/costs, and thinkingLevelMap entries pi would ignore.

Development

npm install
npm test
npm run typecheck
npm run dev

License

MIT