Phantom CLI

phantom connects Claude Code, Codex, pi and other coding agents to Phantom AI, an OpenAI-compatible API. It signs you in, keeps your key on your computer, adds credit and caps what each key can spend.

Docs · npm

Install and set up

You need Node 24 or newer and the coding agent itself.

npm i -g @phantomcodes/cli
phantom setup

With no key saved yet, phantom setup signs you in first, with the same browser approval as phantom login. Then it finds the agents on your computer, shows what it will change in each file, and asks before it writes anything. Restart your agent, or open a new terminal, to use the connection.

With no credit, phantom-1 runs on free models, up to 200 requests a day from a coding agent, and you don't need a card. Free calls leave out web search, which costs money on any model.

If you used pai, this CLI's old name, run phantom setup once after you install. Until then, Claude Code and the shell block that pai wrote still call pai, and phantom prints a reminder.

What setup changes

Setup writes model settings for Claude Code, Codex, opencode, Continue, Goose, Aider, GitHub Copilot CLI, Cline, Gemini CLI, Crush, Qwen Code, Kilo Code, Kimi Code, Droid, Mistral Vibe and Zed. Cursor, VS Code, JetBrains AI Assistant, Warp and Trae keep these settings on their own settings screens, so setup prints the steps for you to follow. pi gets the skill only.

It also installs the phantom-ai skill, a file that teaches the agent the phantom commands. To install the skill for one agent and change nothing else, run phantom setup --agent claude (or the agent's name).

• phantom setup --dry-run shows the changes and writes nothing.
• --no-shell, or unticking "Your shell" in the checklist, leaves your shell startup file alone. Setup then prints the lines to add yourself.
• --limit 20 caps what the key can spend each month, and --limit none removes the cap. At a terminal, setup asks once when the key has no cap.
• phantom setup --restore puts back each file setup changed, from the copies it kept. A file you edited after setup keeps your edits: restore takes out only Phantom's own lines and keys, and leaves the copy beside the file. It exits 1 only when a file could not be undone.
• phantom setup --provider off takes Phantom out of an agent and keeps the rest of its settings. In JSON settings files (Claude Code, Qwen Code, Gemini CLI and others), setup records each value it replaces and puts it back.

Claude Code's background calls (titles, summaries and its Explore agent) run on the model you chose with phantom models, so picking phantom-1:zdr covers them too.

Let your agent set it up

Paste this into Claude Code, Codex, Cursor or another agent that can run terminal commands:

Help me set up phantom for AI inference through Phantom AI.

Check that I have Node 24 or newer, then install @phantomcodes/cli if needed.
Run phantom setup --agent <my agent> to install the phantom-ai skill, and read it.
Check for an existing workspace and saved keys before changing anything.
If I need to connect, start phantom login and let me complete the device approval.
Check the workspace balance. Ask which coding agent I use and what budget I want,
then create a named workspace key with that cap.
Ask whether I want to connect my existing agent for future runs or use a temporary
connection for one run. For saved setup, preview the changes with phantom setup --dry-run
and show them to me before applying the setup I approve. Make sure any spending cap
is on the key my agent uses. Ask before adding funds or starting paid inference.
Keep keys and recovery credentials out of chat. Finish with the command to launch
my agent, and explain how to undo any saved setup.

Run an agent for one session

phantom login
phantom fund --amount 10 --card
phantom workspace status
phantom codex

phantom claude, phantom codex and phantom pi start the agent with a connection that lasts for that run, and leave your saved agent settings alone. When the agent exits, phantom prints what the run spent. The agent starts on phantom-1, or on the model you picked with phantom models; pass --model after -- to choose another.

phantom login opens a page in your browser. You check that it shows the same short code as your terminal, approve it, and phantom saves the key on this computer (in the macOS Keychain on a Mac). If you already have a key, phantom login --paste saves it.

Put phantom's own flags before the agent's arguments, with -- between them:

phantom codex --key coding -- exec "explain this repository"

Add credit

phantom fund --amount 10 --card
phantom fund --amount 10 --coin usdc

--card opens Stripe Checkout, where the total includes Stripe's card fee. --coin usdc pays in USDC on Solana, and --coin usdc-base pays in USDC on Base. The credit appears once Stripe confirms the payment. Check it with phantom balance.

Give each agent its own key and cap

Every key in a workspace spends from the same balance. Make one key per agent, each with its own cap:

phantom keys create --save coding --limit 5
phantom claude --key coding
phantom keys list
phantom keys set --id coding --limit 10

phantom keys set changes three caps:

• --limit: the most the key can spend in total.
• --budget: the most it can spend each month, or each --period days.
• --rate: the most it can spend in one minute, in dollars.

Each takes a number of zero or more, or none. phantom refuses a mistyped value such as 5usd and changes nothing. --id takes the key's name, its id, or the first 4 or more characters of its id, as phantom keys list shows them.

Revoking a key turns it off for good; its credit stays in the workspace.

If phantom can't save a new or rotated key on this computer (a locked Keychain over SSH, for example), it prints the key once and exits with an error. Copy the key before you close the terminal.

Choose the model

Phantom has three models of its own. phantom models shows what each can do (chat, images in, embeddings, rerank, images, video, speech, transcription) and the model behind each job:

• phantom-1 does every job. Chat starts each task on the standard tier and moves hard steps to frontier: a failed try, or an image.
• phantom-1:free is chat on free models at $0, with no card.
• phantom-1:zdr is chat (with images) on providers that keep none of your data.

At a terminal, phantom models asks which one your agents should use. To pick without the menu:

phantom models use phantom-1:zdr

phantom claude, phantom codex, phantom pi and the next phantom setup start on the model you pick. Agents you set up earlier keep their model until you run phantom setup again.

Pick the model in each tier

Your key's lineup sets the model phantom-1 runs in each tier, and a fallback model to try when that one fails:

phantom lineup --table
phantom lineup set --frontier <model> --economy-fallback <model>
phantom lineup reset

phantom lineup lists the models each tier can run. Write default in place of a model to put that tier back to its default.

Set rules for auto

A route policy is your key's own rules for which model answers a request for auto. It can prefer cheaper models, and switch models for tool use, reasoning or a budget that is running low:

PHANTOM_KEY_NAME=coding phantom route set --models <model-a>,<model-b>
PHANTOM_KEY_NAME=coding phantom route test --table

A request that names its own model skips the policy, unless you set --applies-to all. phantom route set --sort fast sends each request to the provider that starts answering soonest, and --sort default goes back to cheapest first.

See what you spent

phantom spend --table
phantom spend --from 2026-09-01 --to 2026-09-30
phantom spend --workspace --table

Dates are UTC days, and the default is this month. Without --workspace you see the key you run as; with it, every key in your workspace by name. The "saved" figure compares what phantom-1 cost with the same tokens at the frontier model's price today, so it is an estimate.

Commands by task

Output and exit codes

At a terminal, commands draw a screen, and choices are pickers (arrow keys, Enter, Esc to go back). When scripts and agents run them through a pipe, they print JSON on stdout and errors on stderr. --json prints JSON at a terminal, and --table draws the screen in a pipe. phantom refuses a flag it doesn't know.

phantom claude, phantom codex and phantom pi run in your terminal and print a spending summary on stderr when the agent exits.

Exit codes: 0 for success (and for Esc), 1 for an error, 2 for a rejected key, 130 for Ctrl+C. phantom setup returns 1 when it could only install the skills because there was no key yet ("complete": false). An agent run returns the agent's exit code.

phantom --help shows the main commands. phantom --help --all lists every command and flag.

The older phantom key commands still work. phantom keys list reads the workspace, and phantom keys saved lists the keys saved on this computer. phantom keys show prints a saved key for shell use, as in PHANTOM_API_KEY=$(phantom keys show); keep it out of chat and logs.

The CLI lives in cli/ in the Phantom repo, which uses pnpm. Install once at the repo root, then run the checks from cli/:

pnpm install
cd cli
pnpm typecheck
pnpm test
pnpm build
pnpm coverage

Report a security problem privately to support@phantom.codes, not in a public issue.

phantom is proprietary, under the Phantom Proprietary License. It lets you install and run phantom to use Phantom AI, the hosted API it calls.