Skip to content

pi.md

Latest commit

 

History

History
139 lines (106 loc) · 5.89 KB

pi.md

File metadata and controls

139 lines (106 loc) · 5.89 KB
Raw

Use Pi with CometAPI

Canonical docs: https://apidoc.cometapi.com/integrations/pi

Use this guide to configure Pi with CometAPI by setting the base URL, API key, and model or provider options. Pi is the Pi Agent Harness project. Its @earendil-works/pi-coding-agent package provides an interactive coding agent CLI with file, shell, edit, write, session, print, JSON, RPC, and SDK workflows. Pi can load custom providers from ~/.pi/agent/models.json, so you can add CometAPI as OpenAI-compatible provider entries without changing Pi source code.

Official references:

Note Model availability changes over time. Replace your-model-id with an available model ID from the CometAPI Models page.

Prerequisites

  • Node.js >=22.19.0
  • npm
  • A CometAPI account with an active API key from the dashboard
  • Pi installed from the official npm package

Understand runtime permissions

Pi runs with the permissions of the user and process that launches it. Start Pi in the project directory you want it to work on, keep a rollback path such as git, and use a container or sandbox if you need stronger filesystem, process, network, or credential boundaries.

Configure the provider

Install Pi

Install Pi globally with npm:

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

Confirm that the CLI is available:

pi --version

Set your CometAPI API key

Store your CometAPI API key in the COMETAPI_KEY environment variable:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY

Add the export command to your shell profile if you want it to persist across terminal sessions. Do not commit API keys to version control.

Add CometAPI providers to models.json

Create ~/.pi/agent/models.json if it does not exist. If the file already contains providers, merge the cometapi-responses and cometapi-chat entries into the existing providers object:

{
  "providers": {
    "cometapi-responses": {
      "name": "CometAPI Responses",
      "baseUrl": "https://api.cometapi.com/v1",
      "api": "openai-responses",
      "apiKey": "$COMETAPI_KEY",
      "models": [
        {
          "id": "your-model-id",
          "name": "CometAPI Responses model"
        }
      ]
    },
    "cometapi-chat": {
      "name": "CometAPI Chat Completions",
      "baseUrl": "https://api.cometapi.com/v1",
      "api": "openai-completions",
      "apiKey": "$COMETAPI_KEY",
      "models": [
        {
          "id": "your-model-id",
          "name": "CometAPI Chat model"
        }
      ]
    }
  }
}

Use cometapi-responses for models or workflows that require the OpenAI Responses API. Use cometapi-chat for OpenAI Chat Completions-compatible models. Pi resolves $COMETAPI_KEY at request time. Keep the API key in your environment or in your own secrets workflow.

Verify both providers

List the models that Pi can see for the Responses provider:

pi --list-models cometapi-responses

Run a short one-shot prompt with the Responses provider:

pi --provider cometapi-responses --model your-model-id -p "Reply with one short sentence confirming the Responses connection."

List the models that Pi can see for the Chat Completions provider:

pi --list-models cometapi-chat

Run a short one-shot prompt with the Chat Completions provider:

pi --provider cometapi-chat --model your-model-id -p "Reply with one short sentence confirming the Chat Completions connection."

For interactive use, start Pi in your project and select the CometAPI provider and model with /model. If you edit models.json during an interactive session, open /model again so Pi reloads the custom model entries.

Troubleshooting

Pi does not show the CometAPI model

Confirm that ~/.pi/agent/models.json is valid JSON and that each provider entry is inside the top-level providers object. Run pi --list-models cometapi-responses or pi --list-models cometapi-chat after saving the file.

Pi reports that no API key is available

Confirm that COMETAPI_KEY is set in the same shell session that launches Pi. If you use a shell profile, open a new terminal or source the profile before running Pi.

Requests fail because of the base URL

Use https://api.cometapi.com/v1 as the baseUrl in models.json. Do not point Pi at the dashboard URL or omit the /v1 suffix for OpenAI-compatible routes.

Pi fails before sending a model request

Check your Node.js version with node --version. The Pi package requires Node.js >=22.19.0.

The model works on one route but not the other

Use the provider entry whose api field matches the route your model supports. openai-responses uses the Responses API, while openai-completions uses Chat Completions.

Pi has more access than expected

Pi runs with the permissions of the user and process that launched it. Run Pi inside a container or sandbox when you need stronger boundaries around files, processes, network access, or credentials.

Related resources