Pi Guide

Pi is an extensible terminal coding agent. It supports connecting to Flux through its OpenAI-compatible endpoint by overriding built-in providers.

Installation

Choose an official installation method based on your setup.

Install Pi globally:

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

macOS / Linux

curl -fsSL https://pi.dev/install.sh | sh

After installation, verify the installation in your terminal:

pi --version

Seeing the version number confirms the installation succeeded.

Connect to Flux

1. Create an API Key

Follow Create API Key to generate an API key, selecting a group that supports the OpenAI format.

Model Availability

This guide uses gpt-5.6-terra as an example. For the full list of available models, refer to Models and the models supported by your selected key group.

2. Configure models.json

Pi supports overriding built-in providers via a global models configuration file.

Global configuration path:

• macOS / Linux: ~/.pi/agent/models.json
• Windows: %USERPROFILE%\.pi\agent\models.json

Create or edit this file and add the following configuration:

{
  "providers": {
    "openai": {
      "baseUrl": "https://api.tryflux.net/v1"
    }
  }
}

If models.json already exists, merge the openai entry into your existing providers object instead of overwriting other providers.

3. Log In and Save the API Key

Start Pi and use the built-in /login command to store your credentials:

1. Run pi in your terminal to start interactive mode.
2. Enter /login and press Enter.
3. Select OpenAI from the provider list.
4. Paste your Flux API key.

Pi saves credentials in ~/.pi/agent/auth.json (or %USERPROFILE%\.pi\agent\auth.json on Windows). You do not need to write the key into models.json or manually edit auth.json. The stored credentials match the overridden openai Base URL in models.json.

Launch and Select Models

Check the Model Catalog

Run the following command to check matching models in Pi:

pi --list-models gpt-5.6-terra

Interactive Session

Launch an interactive session by specifying the provider and model:

pi --provider openai --model gpt-5.6-terra

Once Pi is running, you can also switch models inside the session using the /model command or the Ctrl+L shortcut.

Minimal Verification

Run the following minimal command to verify the setup:

pi --provider openai --model gpt-5.6-terra --no-session --no-tools -p "Reply with OK only"

Real Calls and Billing Notice

This verification command makes a real model call to Flux and incurs charges. Receiving an OK reply confirms the integration works.

Troubleshooting and Notes

Model Catalog vs. Group Support

Pi's built-in model catalog may list models not supported by your current Flux group. Seeing a model in the list only indicates that the configuration was loaded; whether it works depends on whether the minimal call succeeds.

Cost Metadata vs. Actual Pricing

The OpenAI cost metadata shown in Pi's footer is based on default preset rates and does not reflect Flux pricing. For actual costs and usage details, refer to Flux Models and your console usage records.

Updating the Model Catalog

To sync Pi's built-in model catalog, run:

pi update --models

Related Pages

• Create API Key - pick a group and generate a key
• API Endpoints - address and protocol format
• Troubleshooting - locate a problem by symptom
• Pi Repository (GitHub) - source code and official documentation
• Pi Website - official homepage