Skip to content
NoviaHub Docs

Command-line agents

Pi

Add NoviaHub to Pi as a compatible endpoint in models.json, then verify the setup and switch models.

Pi (pi.dev) is an agent that runs in your terminal and can read and write files and run commands on your machine. Besides its built-in providers, it lets you add OpenAI-, Anthropic- or Google-compatible endpoints in its models.json config file, which is how you connect it to NoviaHub.

Prerequisites

Section titled “Prerequisites”
  • A NoviaHub API key (see API keys) and a positive balance (see Wallet and top-ups).
  • Node.js 22.19 or newer if you install with npm.

Install

Section titled “Install”
终端窗口
curl -fsSL https://pi.dev/install.sh | sh

Run pi --version to check the install.

Configure NoviaHub

Section titled “Configure NoviaHub”

  1. Store your API key in the environment variable NOVIAHUB_API_KEY.

    终端窗口
    # macOS uses zsh by default; with bash on Linux, use ~/.bashrc instead of ~/.zshrc
    echo 'export NOVIAHUB_API_KEY="sk-..."' >> ~/.zshrc
    source ~/.zshrc

  2. Edit the config file ~/.pi/agent/models.json (create it if it doesn’t exist) and add:

    ~/.pi/agent/models.json
    {
      "providers": {
        "noviahub": {
          "baseUrl": "https://noviahub.com/v1",
          "api": "openai-completions",
          "apiKey": "${NOVIAHUB_API_KEY}",
          "models": [
            {
              "id": "deepseek-v4-flash",
              "name": "deepseek-v4-flash",
              "contextWindow": 1000000,
              "maxTokens": 384000
            },
            {
              "id": "gpt-6-sol",
              "name": "gpt-6-sol",
              "contextWindow": 1050000,
              "maxTokens": 128000
            }
          ]
        }
      }
    }

    What each field means:

    Field Meaning
    noviahub The provider ID. Any name works; you select models as noviahub/<model ID>.
    baseUrl With openai-completions or openai-responses, use https://noviahub.com/v1 (with /v1).
    api The protocol. openai-completions is OpenAI Chat Completions, which every text model on NoviaHub supported on 2026-09-28.
    apiKey ${NOVIAHUB_API_KEY} reads the key from the environment variable; $NOVIAHUB_API_KEY also works.
    models The models you want. id is the NoviaHub model ID and must match Models & Pricing exactly; name is the display name.
    contextWindow / maxTokens The model’s context length and maximum output. You can leave them out, but then Pi assumes 128,000 and 16,384 (see Pi’s source), while many NoviaHub models have far more context than 128,000, so set them. The values above come from Models & Pricing on 2026-09-28; use the Context and Max output figures shown there.
    input Optional and not used above. Without it Pi treats the model as text-only; to send images, add "input": ["text", "image"] to models whose Input types include images.

  3. Go to your project folder and run:

    终端窗口
    pi --model noviahub/deepseek-v4-flash

Calling Claude models over the Anthropic protocol (optional)

Section titled “Calling Claude models over the Anthropic protocol (optional)”

openai-completions can call Claude models too, but the request goes through protocol conversion and some features are lost; see Protocol conversion. To send Claude models over Anthropic Messages, add a second provider, noviahub-claude, under providers. Its baseUrl has no /v1, because Pi’s Anthropic client adds /v1/messages itself. The complete file then looks like this:

~/.pi/agent/models.json
{
  "providers": {
    "noviahub": {
      "baseUrl": "https://noviahub.com/v1",
      "api": "openai-completions",
      "apiKey": "${NOVIAHUB_API_KEY}",
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "deepseek-v4-flash",
          "contextWindow": 1000000,
          "maxTokens": 384000
        },
        {
          "id": "gpt-6-sol",
          "name": "gpt-6-sol",
          "contextWindow": 1050000,
          "maxTokens": 128000
        }
      ]
    },
    "noviahub-claude": {
      "baseUrl": "https://noviahub.com",
      "api": "anthropic-messages",
      "apiKey": "${NOVIAHUB_API_KEY}",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "claude-sonnet-5",
          "contextWindow": 1000000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

Then start Pi with pi --model noviahub-claude/claude-sonnet-5. This only works for models whose details show the Anthropic endpoint label.

Verify

Section titled “Verify”
终端窗口
# List available models, optionally filtered by a search term
pi --list-models deepseek

Once the models under noviahub appear, start Pi and ask a question. If you get an answer and the call shows up in NoviaHub’s Usage Logs, the setup works.

Switch models

Section titled “Switch models”
  • Type /model in Pi to search and pick a model; press Ctrl+S on a model to save it as the default for new sessions.
  • Press Ctrl+P to cycle through available models.
  • Choose at start-up: pi --model noviahub/gpt-6-sol.

Add new models to the models list in models.json first. Pi reloads models.json when you open /model, so no restart is needed.

Troubleshooting

Section titled “Troubleshooting”

Models from models.json don’t appear in /model According to the docs, custom models only appear in /model once Pi can resolve their credentials, and environment variables must be set in the process that starts Pi. Run echo $NOVIAHUB_API_KEY in the same terminal (echo $env:NOVIAHUB_API_KEY in PowerShell) and check that it prints the key.

It works in one terminal but not another Same cause: the new terminal doesn’t have the variable. Add it to ~/.zshrc / ~/.bashrc as in step 1 of Configure NoviaHub, or store it permanently with setx on Windows.

401 Invalid token The key is wrong, or it is disabled, expired or out of quota. Check its status on the API Keys page; see The four statuses.

403 insufficient_user_quota Your account balance has run out. Top up first.

References

Section titled “References”

Checked on 2026-09-28 and 2026-09-29: