> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Pi with CometAPI

> Use this guide to configure Pi with CometAPI by setting the base URL, API key, and model or provider options.

[Pi](https://github.com/earendil-works/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:

* [Pi repository](https://github.com/earendil-works/pi)
* [Pi quickstart](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md)
* [Pi providers](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md)
* [Pi custom models](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Pi CLI usage](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<Note>
  Model availability changes over time. Replace `your-model-id` with an available model ID from the [CometAPI Models page](/overview/models).
</Note>

## Prerequisites

* Node.js `>=22.19.0`
* npm
* A CometAPI account with an active API key from the [dashboard](https://www.cometapi.com/console/token)
* 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

<Steps>
  <Step title="Install Pi">
    Install Pi globally with npm:

    ```bash theme={null}
    npm install -g --ignore-scripts @earendil-works/pi-coding-agent
    ```

    Confirm that the CLI is available:

    ```bash theme={null}
    pi --version
    ```
  </Step>

  <Step title="Set your CometAPI API key">
    Store your CometAPI API key in the `COMETAPI_KEY` environment variable:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Verify both providers">
    List the models that Pi can see for the Responses provider:

    ```bash theme={null}
    pi --list-models cometapi-responses
    ```

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

    ```bash theme={null}
    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:

    ```bash theme={null}
    pi --list-models cometapi-chat
    ```

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

    ```bash theme={null}
    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.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Pi fails before sending a model request">
    Check your Node.js version with `node --version`. The Pi package requires Node.js `>=22.19.0`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related resources

* [CometAPI quick start](/overview/quick-start)
* [CometAPI Models page](/overview/models)
* [Pi custom models](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Pi CLI usage](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/pi#howto",
        "name": "Use Pi with CometAPI",
        "description": "Use this guide to configure Pi with CometAPI by setting the base URL, API key, and model or provider options.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-1",
            "position": 1,
            "name": "Install Pi",
            "text": "Complete the Install Pi step in the Use Pi with CometAPI guide."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-2",
            "position": 2,
            "name": "Set your CometAPI API key",
            "text": "Store your CometAPI API key in the environment variable or settings field used by the integration."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-3",
            "position": 3,
            "name": "Add CometAPI providers to models.json",
            "text": "Complete the Add CometAPI providers to models.json step in the Use Pi with CometAPI guide."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-4",
            "position": 4,
            "name": "Verify both providers",
            "text": "Complete the Verify both providers step in the Use Pi with CometAPI guide."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "CometAPI Docs",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Integrations",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Use Pi with CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/pi"
          }
        ]
      }
    ]
    }
    `}
</script>