pi-cliproxyapi-provider

pi-cliproxyapi-provider registers one CLIProxyAPI instance as a pi model provider. It discovers models from CLIProxyAPI's OpenAI-compatible /v1/models endpoint and enriches them with metadata from models.dev.

Install

Install from npm:

pi install npm:pi-cliproxyapi-provider

Or install from GitHub:

pi install git:github.com/0xRichardH/pi-cliproxyapi-provider@master

You can omit @master, but pinning a branch, tag, or commit makes Git installs reproducible:

pi install git:github.com/0xRichardH/pi-cliproxyapi-provider@a28f326

Restart pi after installing, then run:

/cliproxyapi config
/login cpa
/model

Install for local testing

From this repository:

pi -e .

List models without installing:

CLIPROXYAPI_BASE_URL=http://localhost:8317/v1 \
CLIPROXYAPI_API_KEY=your-key \
pi -e . --list-models cpa

Configure

Run the interactive command:

/cliproxyapi config

It writes global connection/auth config to:

~/.pi/agent/pi-cliproxyapi-provider/config.json

Environment variables override config:

CLIPROXYAPI_BASE_URL
CLIPROXYAPI_PROVIDER_NAME
CLIPROXYAPI_AUTH_REQUIRED
CLIPROXYAPI_AUTH_HEADER
CLIPROXYAPI_MODELS_DEV_ENABLED

Project config only supports metadata aliases. Connection and auth settings such as baseUrl, providerName, authRequired, authHeader, and headers must be set in global config or environment variables.

Authenticate

Use pi's normal API-key login flow:

/login cpa

If you changed the provider name, use that name instead:

/login 0xdev

For non-interactive runs, set:

export CLIPROXYAPI_API_KEY=your-key

Commands

/cliproxyapi config             # interactive setup
/cliproxyapi status             # show snapshots, capabilities, and enrichment counts
/cliproxyapi refresh            # refresh models and metadata, then update pi immediately
/cliproxyapi refresh models     # refresh CLIProxyAPI availability only
/cliproxyapi refresh metadata   # refresh models.dev metadata only
/cliproxyapi aliases            # show unmatched model IDs for metadata aliases

Metadata aliases

Aliases affect metadata only. The package still sends the original CLIProxyAPI model ID to the proxy.

Add global aliases to:

~/.pi/agent/pi-cliproxyapi-provider/config.json

Add project aliases manually to:

.pi/pi-cliproxyapi-provider/config.json

Project config only reads modelAliases; other fields are ignored.

{
  "modelAliases": {
    "claude-opus-4-6-thinking": "anthropic/claude-opus-4-6"
  }
}

Snapshots and startup

CPA /v1/models:      local snapshot at startup, then a background refresh
models.dev metadata: persistent local snapshot, refreshed manually

Snapshots live under:

~/.cache/pi-cliproxyapi-provider/

Startup registers the provider immediately from the last-known-good local snapshots. It then refreshes CLIProxyAPI availability in the background with a short timeout and updates the provider dynamically if the model list changed. On a first run, Pi registers a placeholder until background discovery succeeds. Startup never fetches models.dev; it uses the persistent local metadata snapshot or data/models-dev-fallback.json when no snapshot exists.

Manual refreshes update the running provider immediately; /reload is not required. Failed refreshes retain the last-known-good data independently for each source.

A scheduled GitHub Actions workflow checks the bundled fallback catalog daily. When it changes, the workflow validates the package, bumps the patch version, commits the update, and starts the normal release workflow. Maintainers can also update the catalog locally with:

npm run update:models-dev

Test

npm test

Release

Changing the package.json version on master automatically creates a matching Git tag and GitHub Release, generates release notes, and publishes the package to npm. Changed daily models.dev catalogs also produce automatic patch releases through the same workflow. See RELEASING.md for authentication, versioning, verification, and troubleshooting.