What Prism CLI is
Prism CLI is a small program you run from Terminal, the text-based app on your Mac. You type a short command, press Return, and it starts something useful. It has two main jobs:
- Chat in Terminal.
prism launch chatopens a text chat with the models you have set up in Prism. - Run coding tools on your Prism models. Commands such as
prism launch claudeandprism launch codexstart a coding tool and send its requests through Prism, so the tool uses the models in your Prism app.
The CLI has no AI models or accounts of its own. It uses what you have already set up in the Prism app, so the Prism app needs to be open while you work. It comes built into the Prism app, so you can add it to Terminal from Settings.
The short version: (1) Install Prism and turn on Settings → Local
Proxy. (2) Open Settings → CLI and click Install prism command.
(3) Open Terminal, type prism, and press
Return.
What you need
Check this list before you install anything.
- A Mac with the Prism app. Prism CLI comes built into the Prism macOS app. Keep the app open and turn on Settings → Local Proxy. Local proxy access is included with paid Prism plans. See Pricing.
- At least one model in Prism. Add a model provider in the Prism app first, for example GitHub Copilot, Gemini or Ollama. The CLI can only use models that Prism has.
- Node.js 20 or newer, only for the npm or one-line install. The copy built into Prism includes its own Node.js. Node.js is a free program that runs tools like this one. If you install with npm, get the LTS version from nodejs.org.
- Terminal. It is already on your Mac. Press ⌘ Space,
type
Terminal, and press Return. - Optional: the coding tool you want to launch. Tools such as Claude Code or Codex are separate programs. Install the ones you want, as described in Tools you can launch. Prism CLI does not install most of them for you.
Install
Prism CLI comes built into the Prism app, so most people only need Option A. You do this once.
Option A (recommended): install from the Prism app
The app includes its own copy of the CLI and the Node.js runtime it needs. You do not install anything else.
- Open Prism, then go to Settings → CLI.
- In the Prism CLI section, click Install prism command. Prism puts a
prismcommand in~/.local/binand turns on Local Proxy. - If Settings says the command directory is not on your PATH, click Add to PATH. This adds a line to
~/.zprofile. - Open a new Terminal window and check that it works:
prism --version
A version number means it worked. Next, go to Your first launch.
The command updates when you update Prism. If you move or delete Prism, Settings says the command is stale. Click Reinstall to repair it. To remove the command, click Remove in Settings → CLI.
Option B: install with npm or the one-line script
Use this if you prefer npm, or if you already manage Node.js on your Mac. It needs Node.js 20 or newer.
Step 1: Check Node.js
Open Terminal and run:
node --version
You should see a version such as v20.11.0. Any number 20 or higher works. If you see
command not found, or a lower number, install Node.js from nodejs.org, open a new
Terminal window, and check again.
Step 2: Install Prism CLI
The quickest option is one command. It checks Node.js, installs the prism command, and
falls back to GitHub releases if the npm install does not work.
curl -fsSL https://prism-app.tech/install-cli.sh | bash
Prefer npm? This installs the same package:
npm install -g @gl-aarav/prism-cli@latest
If you see a permission error, run the one-line command with sudo
before bash. Your Mac will ask for your login password.
curl -fsSL https://prism-app.tech/install-cli.sh | sudo bash
Step 3: Check that it works
Run:
prism --version
A version number means the install worked. If you see command not found, go to
Troubleshooting.
Update or remove the npm install
To update, run the npm command from Step 2 again. It installs the latest version. To remove it, run:
npm uninstall -g @gl-aarav/prism-cli
Your first launch
- Open the Prism app and turn on Settings → Local Proxy.
- Open Terminal. Press ⌘ Space, type
Terminal, and press Return. - Type
prismand press Return. A launch menu opens. It lists Prism Chat and the coding tools. - Move with the ↑ and ↓ arrow keys. Press Return to start the highlighted item. Press → to change its settings first, such as the model. Press Esc to quit the menu.
- Choose Prism Chat to try it. If Prism asks you to pick a model, use the arrow keys and press Return. Then type a question and press Return.
Prefer to skip the menu? Type prism launch chat instead.
Nothing opens, or you see a proxy error? The Prism app is probably closed, or Local Proxy is off. See Troubleshooting.
How it works
This is the path a request takes. You do not manage these steps yourself. The picture helps when something goes wrong.
- Youtype a command in Terminal
- Prism CLIstarts your tool and finds the Prism proxy
- Local proxyruns inside the Prism app on your Mac, on ports 8080 to 8083
- Your modelsset up in Prism, such as GitHub Copilot or Ollama
The CLI connects to the proxy on your own Mac. When Prism turns the proxy on, it saves a private
key at ~/.prism/local-proxy-api-key. The CLI sends that key with each request.
Treat it like a password: do not paste it into chats, screenshots or support requests.
Command reference
Every command starts with prism. These are the ones most people need.
| Command | What it does |
|---|---|
prism | Opens the launch menu, with Prism Chat and the coding tools. |
prism launch | Lists every tool you can launch. |
prism launch chat | Opens Prism Chat in Terminal. |
prism launch <tool> | Starts a tool through Prism. Replace <tool> with a name from Tools you can launch, such as claude. |
prism --version | Shows the installed version. prism -v also works. |
prism usage | Shows how many tokens each model has used through Prism. See Usage statistics. |
prism --help | Shows built-in help. |
Options for prism launch <tool>
Add options after the tool name. Put any name that has spaces in quotes.
| Option | What it does |
|---|---|
-m, --model "NAME" | Uses this model without asking. |
-l, --list | Shows the models this tool can use, then exits. |
-C, --current-config | Reuses your last tool, model and thinking level. See Choosing a model. |
-c, --continue | Resumes the most recent session for that tool. |
-r, --resume ID | Resumes a session by its ID or name. -s and --session do the same. |
--thinking-level LEVEL | Sets how much the model reasons before it answers. The choices depend on the model. |
--fast-model "NAME" | Uses a cheaper, faster model for background work in Claude Code. |
--subagent-model "NAME" | Uses one model for every Claude Code subagent. |
-p, --port NUMBER | Uses one proxy port instead of searching 8080 to 8083. |
--base-url URL | Uses a full proxy address, such as http://localhost:8080. |
-- ARGS | Passes everything after -- to the tool itself. |
Here are some examples. Model names depend on what you have set up in Prism, so run
prism launch claude -l to see yours.
prism launch claude
prism launch claude -m "GPT 5.4 (GitHub Copilot)"
prism launch claude -l
prism launch claude -C
prism launch claude -c
prism launch dsh -- --profile headless "run the tests"
Codex Desktop and Claude Desktop also accept --add-model, --remove-model,
--clear-models, --manage-models and --published. These
choose which models appear in the desktop app's model picker. Claude Desktop also accepts
--restore, which puts back its original settings.
Usage statistics
prism usage shows how many tokens each model has used through the Prism proxy. Like
prism launch, it needs the proxy turned on. By default it covers the last 30 days.
prism usage
prism usage --window 7d
prism usage --all --model sonnet
prism usage --daily
prism usage --json
Use --window with 24h, 7d, 30d or all
to change the period. --model matches part of a model name. --daily adds a
per-day breakdown. --json prints the raw data, which is useful for scripts.
Tools you can launch
Each tool has its own command. Most are separate programs that you install once. If the CLI says a
command was not found on PATH, the tool is not installed yet.
| Tool | Command | What it is | Install first |
|---|---|---|---|
| Prism Chat | prism launch chat | Chat in Terminal with your Prism models. | Nothing extra. |
| Claude Code | prism launch claude | Anthropic's coding agent, with helper agents called subagents. | The claude command. Guide: Claude Code docs. |
| Claude Desktop | prism launch claude-desktop | The Claude desktop app, set to use Prism models. macOS only. | The Claude app from claude.ai/download. |
| Codex CLI | prism launch codex | OpenAI's coding agent for Terminal. | Run npm install -g @openai/codex. |
| Codex Desktop | prism launch codex-desktop | The official Codex desktop app, set to use Prism models. | The Codex app. With the Codex CLI installed, codex app opens it, or opens the installer if the app is missing. |
| Droid CLI | prism launch droid | Factory's coding agent. | The droid command. Guide: Factory docs. |
| Cline | prism launch cline | An autonomous coding agent for Terminal. | Run npm install -g cline. |
| OpenCode | prism launch opencode | A coding CLI set up to use Prism models. | The opencode command. Guide: OpenCode docs. |
| Pi | prism launch pi | A coding agent for Terminal, set up to use Prism models. | Run npm install -g --ignore-scripts @earendil-works/pi-coding-agent. |
| GitHub Copilot CLI | prism launch copilot | GitHub's Copilot command-line tool. | The copilot command. Guide: GitHub docs. |
| DeepSeek Harness | prism launch dsh | DeepSeek's open-source agent harness, called dsh. | Run npm install -g @deepseek-ai/dsh. If it is missing, Prism runs it with npx instead. |
Notes on specific tools
- Claude Desktop changes settings while it runs. When you launch it, Prism quits
Claude Desktop if it is open, saves your current settings to
~/.prism/claude-desktop-backup/, and opens the app on Prism models. When you press Ctrl C or quit the app, Prism puts your original settings back. If the CLI was stopped before it could do that, runprism launch claude-desktop --restore. - Codex Desktop restarts on every launch. This makes the model you chose take effect. Save your work in the app first. Its chat history is separate from your normal Codex history. Built-in GPT models still use your own Codex sign-in.
- DeepSeek Harness opens its web page. With no extra options, it starts its
web interface at
http://127.0.0.1:3080. To pass options, add them after--. - Claude Code subagents need a tool-capable model. Subagents work by reading files and running commands. A text-only model can make them look like they do nothing. See Choosing a model.
Choosing a model
A model is the AI system that writes the replies. Prism CLI can only use the models you have set up in Prism.
- See your options.
prism launch claude -llists the models a tool can use. Copy the exact name into-m. - Pick from the menu. Type to search, use ↑ and ↓ to move, press Return to choose, and press Esc to cancel. The left and right arrows change the thinking level for models that support it.
- Use a tool-capable model. Coding agents work by reading files, editing code and running commands. A model that only returns text may reply, but it will not change your files.
- Remember your choice. The launch menu saves what you picked. Next time, add
-Cto reuse it. - Check the provider's account. If a provider rejects a request, for example
with
HTTP 402: Insufficient credits, the problem is in that provider's account, not in the CLI. Add credits or a payment method there, or pick a different model.
Files on your Mac
Prism CLI keeps most of its files in a hidden folder called .prism in your home folder.
~ means your home folder. You do not need to edit these files.
| File or folder | What it is for |
|---|---|
~/.prism/local-proxy-api-key | The private key from the Prism app. The CLI reads it to talk to the proxy. Keep it private. |
~/.prism/last_launch_model.json | Your last launch choices. The -C option reads it. |
~/.prism/codex-desktop-home/ | Settings and chat history for Codex Desktop when it is launched through Prism. Prism never edits your own ~/.codex/config.toml. |
~/.prism/codex-desktop-models.json | The models you chose to show in Codex Desktop's picker. |
~/.prism/claude-desktop-models.json | The models you chose to show in Claude Desktop's picker. |
~/.prism/claude-desktop-backup/ | Your Claude Desktop settings, saved so Prism can put them back. |
~/.local/bin/prism | The prism command that Settings → CLI installs. It runs the copy of the CLI inside Prism.app. |
~/.zprofile | Gets a PATH line when you click Add to PATH, so Terminal can find the command. |
Troubleshooting
Find the message you see, then follow the fix. Messages are shown as the CLI prints them.
| What you see | What to do |
|---|---|
command not found: prism | From Settings: open Settings → CLI and click Add to PATH, then open a new Terminal window. From npm: the folder that holds npm's commands is missing from your PATH. Find it with npm prefix -g, add the line below to ~/.zshrc, then open a new Terminal window. |
| A permission error during install | Run the one-line install command with sudo, as shown in Install. |
Node.js >= 20 is required | This appears only with the npm or one-line install. Install Node.js 20 or newer from nodejs.org, or use Option A in Install, which does not need Node.js. |
Settings says No writable command directory | Create the folder with mkdir -p ~/.local/bin, then click Install prism command again. |
Settings says Another prism command earlier in PATH will run instead | Two copies are installed. Keep one. If the other one came from npm, run npm uninstall -g @gl-aarav/prism-cli. |
Settings says The installed command points to a missing Prism app | Prism was moved or deleted. In Settings → CLI, click Reinstall. |
Prism local proxy did not respond or was not found on ports 8080-8083 | Open the Prism app, go to Settings → Local Proxy, and turn it on. If you use a custom port, pass it with -p or --base-url. |
responded ... but access is disabled | The proxy is running, but Prism says this account cannot use it. Check Settings → Local Proxy and your Prism plan. See Pricing. |
Prism returned no models | Prism has no models to offer. Add a model provider in Prism, then try again. |
launch: unknown tool | Check the spelling. Run prism launch to see every tool name. |
... was not found on PATH | That tool is not installed. Install it (see Tools you can launch), open a new Terminal window, and try again. |
no longer supports one-shot/agent mode | Prism CLI no longer runs single prompts such as prism -p "...", and it does not read piped input. Use prism, prism launch chat or prism launch <tool> instead. Update any scripts that used the old options. |
| The tool replies but does not change your files, or subagents do nothing | Switch to a tool-capable model. See Choosing a model. |
HTTP 402 or HTTP 401 from a model | Fix the credits, payment method or sign-in on that model's provider account. Or pick a different model. |
| Claude Desktop still shows Prism settings after you closed it | Run prism launch claude-desktop --restore to put your original settings back. |
Still stuck? Visit the Support page or ask in the
Prism Discord. Include
the output of prism --version, your macOS version, and the exact message you saw.
Glossary
New to these words? Here is what they mean in this guide.
- Terminal
- The Mac app where you type commands. Find it with ⌘ Space.
- Command
- Text you type in Terminal, then send by pressing Return. For example,
prism --version. - Node.js
- A free program that runs tools written in JavaScript. Prism CLI needs version 20 or newer.
- npm
- The installer that comes with Node.js. It downloads and installs tools for you.
- Global install (
-g) - Installing a tool so you can run it from any folder.
- PATH
- The list of folders where Terminal looks for commands. A "command not found" error often means a folder is missing from PATH.
- sudo
- Runs one command with administrator rights. Your Mac asks for your password.
- Prism app
- The Mac app where you set up your models and settings. Prism CLI works with it.
- Local proxy
- A small service inside the Prism app. The CLI and the tools it launches send their requests to it, and it passes them on to your models.
- Model
- The AI system that writes the replies, such as a GPT, Claude or Gemini model.
- Provider
- The company or service that runs a model, such as GitHub Copilot or Ollama.
- Coding agent
- An AI tool that can read your project files, edit code and run commands.
- Tool-capable model
- A model that can take actions inside a coding agent, such as reading files or running commands.
- Subagent
- A helper agent that a coding tool starts to handle a smaller job.
- Session
- A saved conversation with a coding tool. You can resume it later.
- Thinking level
- How much a model reasons before it answers. Higher levels can be slower.
- Flag (option)
- An extra setting after a command, such as
-mor--model. - API key
- A secret string that proves who you are to a service. Keep it private.
FAQ
Do I need to know how to code?
No. You do need to be comfortable typing a command and pressing Return. Every command in this guide is explained.
Do I need a separate AI account for Prism CLI?
No. It uses the models you have already set up in Prism. Local proxy access requires a paid Prism plan. See Pricing.
Can I use it without the Prism app?
No. The local proxy runs inside the Prism app, so the app must be open with Local Proxy turned on.
Does it work on Windows or Linux?
Prism CLI comes with the Prism macOS app, and this guide assumes a Mac. Launching Claude Desktop works only on macOS.
Can I use it in scripts or automated jobs?
Not in the old way. Prism CLI now opens menus and interactive chats. Single-prompt mode, such as prism -p, has been removed.
Do the tools use their own API keys?
Launched tools send their requests through Prism, so they use the models you have set up there rather than their own provider settings. Some official desktop apps keep their own sign-in for built-in models. For example, the Codex app keeps your ChatGPT sign-in for its GPT models.
How do I update Prism CLI?
If you installed the command through Settings, update Prism and the command updates with it. If you installed with npm, run npm install -g @gl-aarav/prism-cli@latest again. See the changelog for what changed.
Where do I report a bug or ask for a feature?
Use the Support page, or ask in the Prism Discord.