Commands
Run prism commands and read their results.
Run these commands in a terminal on your Mac. A command that reports a registration or a sign-in does not show that new activity has reached Prism; check Realtime for that.
prism login
Section titled “prism login”prism loginprism login --server <address>Connects this Mac to your Prism account. The terminal prints an address and a code:
Open this URL to approve this device: <address with the code>Or open <address> and enter the code <code>.Check that the code shown there is <code>. Waiting for approval...Prism opens the address in your browser, except when you are connected over SSH. On the Approve device screen, check that the code matches and select Approve. The code is valid for 10 minutes.
On success the terminal prints Logged in. The token is stored in the macOS Keychain. When the Keychain cannot be used, it prints Logged in. The macOS Keychain is unavailable, so the token is stored in <path>., with the token file in the Prism folder (~/.config/optra-prism). The device then appears in Settings → Devices. The Claude Code plugin and the Codex plugin on this computer use the same sign-in, so a computer that signed in here does not sign in again in a plugin, and the other way round.
Without --server, the CLI signs in to the Prism service. --server names another service address; you need it only when the Install guide screen shows it in the sign-in command. The CLI keeps the address for later logins. It must start with https://; http:// is accepted only for this computer.
If you sign in as a different account or to a different service, records that were waiting to be sent under the earlier sign-in are discarded, and sessions recorded before are not sent under the new one.
Common messages:
| Message | Meaning |
|---|---|
Could not reach <server>: <reason>. |
The service did not answer. Check your network and the address. |
The login was denied in the browser. |
You selected Deny, or the request was refused. Run prism login again. |
The login code expired. |
The code was not approved within its validity. Run prism login again. |
The login was approved but not stored: a flusher is still running; try again in a moment. |
A background send was still running. Nothing was changed. Run prism login again. |
prism logout
Section titled “prism logout”prism logoutSigns this device out on the server and deletes the stored token. Because the plugins on this computer share that sign-in, they are signed out too. The terminal prints Logged out.. If the server cannot be reached, it prints Logged out on this computer, but the server could not be told; the device then stays registered on the server until it is removed in Settings → Devices. If you were not signed in, it prints Not logged in.. Records that were waiting to be sent are discarded. Hooks stay registered, but nothing is sent until you sign in again, and what you do in Claude Code while signed out is not sent after you sign in.
prism setup
Section titled “prism setup”prism setupThis is the Record every session choice of the Start recording step. It is optional: you can record per session with prism claude and prism codex instead. Run prism setup in a terminal once, and the sessions you start with claude or codex afterwards are recorded.
It registers Prism hooks for the Claude Code and Codex it finds on your computer. It adds five hooks to Claude Code’s settings file (~/.claude/settings.json, or the file in the directory named by CLAUDE_CONFIG_DIR) and four to Codex’s settings file (~/.codex/config.toml, or the file in the directory named by CODEX_HOME), without changing anything else in them. For each tool the result is one of the following; the Codex lines say Codex where these say Claude Code:
Registered the Prism hooks for Claude Code in <path>.The Prism hooks for Claude Code were already registered in <path>.Claude Code was not found (no configuration directory and no `claude` on PATH); skipped.Codex was not found (no configuration directory and no `codex` on PATH); skipped.
If hooks that an earlier build of the CLI registered are still in the file, prism setup replaces them and prints Removed <n> Prism hook entries of an earlier build from <path>. (entry when there is one; for Codex, Removed the Prism hooks of an earlier build from <path>.).
Codex runs hooks only after they are approved. For a Codex version Prism supports, prism setup asks whether it may record the approval of the four Prism hooks, and after you agree it prints Codex trust records written for Codex <version>; Codex will not ask to approve the Prism hooks. If you decline, or the version is not supported, Codex asks for approval the next time it starts, and nothing is collected from Codex until you approve.
prism setup does not turn a Prism plugin off. A plugin on this computer uses the same sign-in and the same local files as the CLI, and an event that both a CLI hook and a plugin hook receive is recorded once. The output says so: A Prism plugin on this machine uses the same state and sign-in as the CLI; one event of a session is recorded once.
If you are not signed in, it adds You are not logged in. Run `prism login` first; nothing is collected until you do. The output ends with the tools whose hooks are registered and how to add another configuration directory. Running it again changes nothing.
The command signs nothing in and sends nothing. Sessions you start after prism login and prism setup are recorded; a session that was already open is not. prism setup registers in the configuration directory of the environment it runs in and remembers that path. If you switch settings folders, run it once for each folder, for example CLAUDE_CONFIG_DIR=<folder> prism setup or CODEX_HOME=<folder> prism setup. One run applies to one folder.
prism setup remove
Section titled “prism setup remove”prism setup removeRemoves exactly the hooks Prism registered. In Claude Code’s settings file it prints Removed the Prism hooks from <path>.; in Codex’s settings file it removes the hooks together with Prism’s trust records and prints Removed the Prism hooks and trust records from <path>. It prints No Prism hooks were registered in <path>. when there were none. It does not change any plugin. It acts on every configuration directory that prism setup remembered; a directory that no longer exists is reported as Skipped <path>: the directory no longer exists. It is dropped from Prism's list. and removed from the list. After a removal it prints Run `prism setup` to register them again. Your sign-in and local files stay.
prism status
Section titled “prism status”prism statusShows where setup stands, in five groups. The lines look like this:
Account E-mail: you@example.com Device: <device name> Login: logged in Token: valid New sessions are collected under: PersonalHosts Claude Code hooks: registered in <path> Claude Code version: <version> Earlier plugin OTEL values: none Codex hooks: registered in <path> Codex version: <version> Codex trust: approved Claude Code config dirs recorded by setup: 1 <path>: hooks registered Codex homes recorded by setup: 1 <path>: hooks registeredCollection Last trigger: <time> (Stop) Last successful send: <time> Unsent envelopes: 0 (0 B) Last error: none Unclassified records (last 7 days): none Skipped sessions (last 7 days): noneVersion prism <version> Upgrade needed: noServer Address: <address> Connection: ok (collection policy version <n>)What to read:
- Login and Token show whether this Mac is signed in and whether the server accepts the token.
logged inandvalidare the healthy values. - New sessions are collected under shows
Personalororganization <name>, the account context for new sessions. - Claude Code hooks and Codex hooks show
registeredonceprism setuphas run. If you only start sessions withprism claudeorprism codex, they shownot registered, which is expected. Codex trust shows whether Codex approved the Prism hooks; unless it saysapproved, Codex asks for approval, and nothing is collected from Codex until then. - Plugin newer than this CLI appears only when a Prism plugin on the same computer is newer than the CLI. Update the CLI when you see it.
- Earlier plugin OTEL values shows whether the earlier plugin left telemetry values in Claude Code’s settings. If it did,
prism setupcan remove them. - config dirs recorded by setup and homes recorded by setup list the configuration directories that
prism setupremembered, withhooks registered,hooks not registered, ordirectory not foundfor each. - Last trigger and Last successful send show whether the hooks fire and whether a send has succeeded.
none yetandneverare normal before your first session. - Unsent envelopes counts records waiting to be sent. A count that keeps growing means sending is failing; read Last error.
- Connection shows whether the server answered.
When you run the same command from a plugin with /prism:status or $prism:status, Hosts lists only that plugin’s host, as Claude Code collection: this plugin or Codex collection: this plugin. The sign-in, the unsent records, and the connection are the ones the CLI and both plugins share. A Claude Code plugin that signed in automatically with the earlier plugin’s key also shows a Sign-in: through the earlier plugin's key (key exchange) line under Account.
Troubleshooting explains each message. After printing, prism status also gives a background send one chance to run, if none is running.
prism uninstall
Section titled “prism uninstall”prism uninstallprism uninstall --yesRemoves what the CLI put on your Mac: the Claude Code and Codex hooks, the Codex trust records, this device’s sign-in on the server and the stored token, and the files Prism keeps in the Prism folder (~/.config/optra-prism). A plugin that is still installed shares that sign-in, so it is signed out too; sign in again with /prism:setup or $prism:setup to keep recording through it. The command leaves ~/.prism, where the earlier Prism plugin kept its files, alone. It first lists these and prints Unsent envelopes that will be lost: <n>, then asks Continue? [y/N]. Answer y or yes to continue; anything else prints Cancelled. Nothing was removed. --yes skips the question.
A program that was not installed by Prism, for example one from Homebrew, stays in place and the command tells you to run brew uninstall prism. Data that Prism already received is not deleted; see Data collection and visibility.
prism claude
Section titled “prism claude”prism claude [arguments]Starts Claude Code with this version’s Prism hooks attached for that session. Your arguments go to claude unchanged. This is the Record per session choice of the Start recording step, and it works without prism setup. A session started this way is recorded once, even if the hooks from prism setup or the Claude Code plugin are also active; the plugin is turned off for that session. If you ran prism setup, you do not need this command. If claude is not on your PATH, it reports `claude` was not found on PATH. If the server no longer accepts your sign-in, it prints Prism is not sending your sessions because the login is no longer valid. Run `prism login`. and still starts Claude Code.
prism codex
Section titled “prism codex”prism codex [arguments]Starts Codex with the Prism hooks attached for that session. Your arguments go to codex unchanged. For a Codex version Prism supports, the approval of the hooks is passed along too; it applies to that session only and is not saved on disk. This is the Record per session choice of the Start recording step, and it works without prism setup. A session started this way is recorded once, even if the hooks from prism setup or the Codex plugin are also active; the plugin is turned off for that session. If you ran prism setup, you do not need this command. If codex is not on your PATH, it reports `codex` was not found on PATH. If Prism does not know how to approve hooks for your Codex version, it prints Codex <version> is not a version Prism knows how to approve hooks for; Codex may ask you to approve the Prism hooks. and nothing is collected until you approve when Codex asks. The notice about a sign-in the server no longer accepts is the same as for prism claude, and Codex still starts.