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 chat opens a text chat with the models you have set up in Prism.
  • Run coding tools on your Prism models. Commands such as prism launch claude and prism launch codex start 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.

  1. 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.
  2. 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.
  3. 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.
  4. Terminal. It is already on your Mac. Press ⌘ Space, type Terminal, and press Return.
  5. 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.

  1. Open Prism, then go to Settings → CLI.
  2. In the Prism CLI section, click Install prism command. Prism puts a prism command in ~/.local/bin and turns on Local Proxy.
  3. If Settings says the command directory is not on your PATH, click Add to PATH. This adds a line to ~/.zprofile.
  4. 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

  1. Open the Prism app and turn on Settings → Local Proxy.
  2. Open Terminal. Press ⌘ Space, type Terminal, and press Return.
  3. Type prism and press Return. A launch menu opens. It lists Prism Chat and the coding tools.
  4. 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.
  5. 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.

  1. Youtype a command in Terminal
  2. Prism CLIstarts your tool and finds the Prism proxy
  3. Local proxyruns inside the Prism app on your Mac, on ports 8080 to 8083
  4. 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.

Main Prism CLI commands
CommandWhat it does
prismOpens the launch menu, with Prism Chat and the coding tools.
prism launchLists every tool you can launch.
prism launch chatOpens 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 --versionShows the installed version. prism -v also works.
prism usageShows how many tokens each model has used through Prism. See Usage statistics.
prism --helpShows built-in help.

Options for prism launch <tool>

Add options after the tool name. Put any name that has spaces in quotes.

Options for prism launch
OptionWhat it does
-m, --model "NAME"Uses this model without asking.
-l, --listShows the models this tool can use, then exits.
-C, --current-configReuses your last tool, model and thinking level. See Choosing a model.
-c, --continueResumes the most recent session for that tool.
-r, --resume IDResumes a session by its ID or name. -s and --session do the same.
--thinking-level LEVELSets 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 NUMBERUses one proxy port instead of searching 8080 to 8083.
--base-url URLUses a full proxy address, such as http://localhost:8080.
-- ARGSPasses 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.

Tools you can launch with Prism CLI
ToolCommandWhat it isInstall first
Prism Chatprism launch chatChat in Terminal with your Prism models.Nothing extra.
Claude Codeprism launch claudeAnthropic's coding agent, with helper agents called subagents.The claude command. Guide: Claude Code docs.
Claude Desktopprism launch claude-desktopThe Claude desktop app, set to use Prism models. macOS only.The Claude app from claude.ai/download.
Codex CLIprism launch codexOpenAI's coding agent for Terminal.Run npm install -g @openai/codex.
Codex Desktopprism launch codex-desktopThe 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 CLIprism launch droidFactory's coding agent.The droid command. Guide: Factory docs.
Clineprism launch clineAn autonomous coding agent for Terminal.Run npm install -g cline.
OpenCodeprism launch opencodeA coding CLI set up to use Prism models.The opencode command. Guide: OpenCode docs.
Piprism launch piA coding agent for Terminal, set up to use Prism models.Run npm install -g --ignore-scripts @earendil-works/pi-coding-agent.
GitHub Copilot CLIprism launch copilotGitHub's Copilot command-line tool.The copilot command. Guide: GitHub docs.
DeepSeek Harnessprism launch dshDeepSeek'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, run prism 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 -l lists 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 -C to 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.

Files Prism CLI creates
File or folderWhat it is for
~/.prism/local-proxy-api-keyThe private key from the Prism app. The CLI reads it to talk to the proxy. Keep it private.
~/.prism/last_launch_model.jsonYour 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.jsonThe models you chose to show in Codex Desktop's picker.
~/.prism/claude-desktop-models.jsonThe 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/prismThe prism command that Settings → CLI installs. It runs the copy of the CLI inside Prism.app.
~/.zprofileGets 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.

Common problems and fixes
What you seeWhat to do
command not found: prismFrom 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.
export PATH="$(npm prefix -g)/bin:$PATH"
A permission error during installRun the one-line install command with sudo, as shown in Install.
Node.js >= 20 is requiredThis 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 directoryCreate the folder with mkdir -p ~/.local/bin, then click Install prism command again.
Settings says Another prism command earlier in PATH will run insteadTwo 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 appPrism was moved or deleted. In Settings → CLI, click Reinstall.
Prism local proxy did not respond or was not found on ports 8080-8083Open 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 disabledThe proxy is running, but Prism says this account cannot use it. Check Settings → Local Proxy and your Prism plan. See Pricing.
Prism returned no modelsPrism has no models to offer. Add a model provider in Prism, then try again.
launch: unknown toolCheck the spelling. Run prism launch to see every tool name.
... was not found on PATHThat 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 modePrism 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 nothingSwitch to a tool-capable model. See Choosing a model.
HTTP 402 or HTTP 401 from a modelFix 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 itRun 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 -m or --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.