CLI Reference

Every capability in the toolkit is reachable through the single prismor command. This page is the map: it lists every command, what it does, and links to the dedicated deep-dive doc for that capability.

prismor <command> [options...]
prismor <domain> <action> [options...]
prismor --help               # the same map, in your terminal
prismor help                 # browse it interactively: type to filter, enter for details
prismor help <command>       # help for one command (same as prismor <command> --help)
prismor help <word>          # search commands and sub-commands, e.g. prismor help secret

There are two shapes:

• Top-level commands — prismor status, prismor audit, prismor check …
• Domains that take an action — prismor cloak add …, prismor canary plant …

immunity is a deprecated drop-in alias for prismor; it forwards everything unchanged and prints a migration notice. Use prismor.

Quick start

The command map

prismor
│
├─ Get started
│   ├─ setup                  Interactive onboarding wizard (TUI)
│   ├─ status [--all]         Health check (this workspace / all workspaces)
│   ├─ doctor                 Health-check every subsystem (hooks, policy, signature, telemetry)
│   ├─ discover [section]     Sweep host for ungoverned agents, MCP servers, keys (--fix to govern them)
│   ├─ dashboard              Local web dashboard (127.0.0.1:7070, opens browser)
│   ├─ login                  Connect this machine to the Prismor API (hosted judge)
│   ├─ update                 Self-update check / upgrade
│   ├─ docs [name]            Print a bundled doc page, or list them
│   ├─ install-hooks          Wire Prismor hooks into an agent/IDE
│   ├─ uninstall-hooks        Remove hooks
│   └─ surfaces               Which enforcement surfaces (hooks, mirror, gateway) are active
│
├─ Day to day
│   ├─ check                  Pre-check a command or path against policy
│   ├─ approvals              Approve or deny one blocked action, once
│   ├─ allow <rule>           Make an exception to a rule that blocked you
│   ├─ pause / pause-hard     Suspend local enforcement (24h / until resume); observe stays on
│   ├─ resume                 Resume enforcement
│   ├─ unlock / lock          Open/close the agent self-edit window (password)
│   └─ mode <action>          list · explain · apply · show — whole-posture templates
│
├─ Policy & scoping
│   ├─ policy <action>        init · validate · show · export · edit · test
│   ├─ tags <action>          list · set · rm · rules · provenance · edit · lint · test
│   ├─ scope <action>         Session-scoped, task-specific rules
│   ├─ iam <action>           Named agent identities / permission profiles
│   ├─ egress <action>        show · report · test · allow · deny · mode · request — network egress policy
│   ├─ agents <action>        Named agent instances — list · show · set (kill-switch, mode, IAM)
│   └─ learn                  Mine session history for new rules
│
├─ Secrets
│   ├─ cloak <action>         install · add · list · sync · remove · status · run · pattern
│   ├─ sweep                  Find & vault leaked secrets on disk
│   └─ canary <action>        Plant & manage honeytoken tripwires
│
├─ Scanning & audit
│   ├─ audit                  Full posture audit (--fix to remediate)
│   ├─ audit judge            LLM judge reviews a sample of ALLOWED calls after the fact
│   ├─ scan                   Scan MCP servers & skills for risk
│   ├─ deps                   Check project deps vs. threat feed
│   ├─ skills <action>        audit · approve — installed SKILL.md baselines
│   ├─ extensions <action>    list · why · approve · wrap-hooks — what puts instructions or code into the agent
│   ├─ memory <action>        status · trust · verify · scan · approve · sign · unsign — instruction-file integrity
│   ├─ semantic-check         Hybrid LLM prompt-injection guard
│   └─ supplychain <action>   npm/pip/pnpm/uv/cargo/go/gem/composer/mvn install gate · harden
│
├─ Enforcement surfaces
│   ├─ mirror <action>        on · off · status · passthrough — governed built-ins over MCP
│   ├─ mcp-gateway [action]   serve · install · uninstall — one MCP connector in front of all servers
│   ├─ acp -- <agent…>        ACP stdio proxy — agents hosted by Zed, JetBrains and other ACP editors
│   ├─ proxy                  LLM/A2A proxy — screens model traffic and proposed tool calls
│   ├─ elevenlabs <action>    status · connect · disconnect — ElevenLabs voice agents via the proxy
│   ├─ sandbox <action>       status · check · on · off · run — Docker command sandbox
│   ├─ inference-hook <action> serve · test · secret — Claude Inference Hooks AI security server
│   └─ eval-server            HTTP evaluation endpoint for non-Python adapters
│
├─ Sessions & evidence
│   ├─ sessions / session     List / show stored sessions (session <id> --changes: files touched)
│   ├─ analyze                Run the engine over a JSONL session
│   ├─ analyze-history       Reconstruct past agent activity from on-disk transcripts
│   ├─ tokens                 Token usage and estimated cost
│   ├─ trail <action>         verify · show · checkpoint — signed audit trail
│   ├─ attest [verify|coverage]  Evidence bundle + framework coverage
│   ├─ query                  Read-only SQL over the local session store
│   ├─ rca [session]          What went wrong in a session
│   ├─ blame <path[:line]>    Which agent session wrote this file or line
│   └─ friction               Failures that recur across sessions, as AGENTS.md lines
│
└─ Org enrollment
    ├─ enroll <token>         Enroll this machine against your org's control plane
    ├─ enroll-status          Show enrollment + applied policy version
    ├─ workspace <action>     Show/set whether this workspace is org-managed or personal
    ├─ exempt <action>        Request an admin exemption for this repo
    └─ logout                 Un-enroll (remove device identity + cached policy)

Onboarding & lifecycle

Agent → config matrix and per-agent details: AGENT_INTEGRATIONS.md. Modes (observe vs enforce): Prismor.

Hook health checks are passive: they parse registered agents' hook configurations and inspect recognized launchers for missing interpreters and dispatcher files. By default they never run a configured command. configured does not establish that imports succeed, that the client loaded its hooks, or that a tool call was blocked. Portable/custom launchers and registered plugins remain explicitly unverified. Doctor's JSON ok means no check failed; review warning entries as well. Dispatcher entries under unregistered event names, or without any registered pre-action tool event, fail the wiring check. Recognized generated project launchers must target the inspected workspace (resolved symlinks are accepted). Global and portable launchers are not required to pin that workspace. These checks do not validate every matcher, optional event or client-specific schema.

prismor doctor --self-test additionally runs recognized generated dispatcher scripts through their configured interpreter, with a temporary home and workspace and no inherited Prismor settings or credentials. It verifies imports and synthetic Claude-protocol allow/block responses, with a timeout on each subprocess. The synthetic commands are evaluated, never executed. Modified dispatcher scripts, custom launchers, portable wrappers, and plugins are skipped with a warning. This verifies the shared dispatcher, not each client's protocol or the current workspace policy. Client loading, trust, and actual invocation still require a live client check. Disposable state is not an OS sandbox. The probe uses Python's isolated mode (-I); dependencies available only through user-site packages or PYTHONPATH are excluded and can fail the import probe.

Cursor reinstall and uninstall remove recognized Prismor launchers, not other tools whose command text mentions hook-dispatch. Legacy event keys are removed only when cleanup removes their last entry. Third-party entries and unrelated settings are preserved; custom wrappers that cannot be recognized remain for manual inspection.

Choosing what blocks

observe reports everything and blocks nothing, so setup leaves every rule on.

enforce asks which rules should block, and starts with none of them selected — including the safety floor, which is marked recommended rather than assumed. Nothing blocks until you choose it. Press a on that screen to take the recommended set.

The choice is written to .prismor/policy.yaml as settings.selection: explicit plus one entry per rule, so what blocks is legible in the file rather than implied by the defaults. Scripted installs say the same thing with --recommended or --enforce-rules id1,id2; --mode enforce with neither installs with nothing blocking and tells you so.

Two things the selection does not reach:

• Prismor's self-protection rules always block. They are what stops the agent editing the choices above, so offering them as a checkbox would make every other checkbox decorative.
• Org-managed workspaces keep the full safety floor. selection: explicit is honored only for a locally-authored policy on an unmanaged machine, and is ignored if it arrives in a signed org bundle.

Governance modes

Picking six policy axes rule by rule is how a policy ends up subtly wrong. A mode is a named posture that sets all six at once — enforcement fallback, egress allowlist, tool access, tag rules, sandbox ring, and step-up gates — and compiles them into the same .prismor/policy.yaml and .prismor/agents.yaml the engine already reads. There is no separate mode enforcement path.

prismor mode list                    # the three, with coverage and friction
prismor mode explain dev-safe        # the trade — including what it does NOT stop
prismor mode apply dev-safe          # compile it (--dry-run to preview first)
prismor mode apply dev-safe --observe # same posture, nothing blocks
prismor mode show                    # active mode, and whether it has drifted

What each mode covers

Coverage and rule counts are computed from the live ruleset by prismor mode list, not hardcoded here — they move as rules are added. Friction is likewise measured, not estimated: tests/test_modes.py runs a benign corpus of ordinary developer commands through each compiled mode and pins the declared friction_index to the share it interrupts. The figures below are from a 91-rule policy.

Prismor's self-protection rules always enforce in every mode — a mode cannot be used as cover for disabling Prismor.

Axis by axis

The three extras in dev-safe are the supply-chain rules: dependency-confusion, pkg-install-from-url, pkg-suspicious-name. trusted-workspace adds the secret rules on top: secret-access, credential-aggregation, credential-staging, claude-credential-access.

Two things worth knowing before you adopt one.

A rule listed in enforce_extra that declares action: warn becomes a hard block, because contract.VERDICT_RANK reads "enforce + a verdict we do not understand" as stop. That is why installing from a private index URL is denied rather than prompted under both safe modes — deliberate, and stated in each mode's residual risk.

untrusted_content means externally sourced: a web fetch, a search result, an MCP tool result, or a file read from outside the workspace root. Reading a file in your own repository is not untrusted ingest, and a mode that turns tag enforcement on must say so explicitly — compile_mode refuses a mode that enables tool_tags without declaring tool_tags.inference_enabled. Inheriting the default there tags every workspace read as untrusted, which turns untrusted_content then critical_action -> block into "read anything, then do anything" and denies every call after the session's first read.

Containment is opt-in

Adopting a mode does not start routing your shell commands through Docker. dev-safe and trusted-workspace both ship sandbox.enabled: false: they compile a sandbox configuration (ring, network, mounts, limits) and leave it switched off, so the mode changes what may run without changing where it runs.

prismor sandbox on      # containment on, using the settings the mode compiled
prismor sandbox off     # back to running on the host
prismor sandbox status  # what is configured, and whether Docker can back it

Only the field flips, so an off/on round trip keeps the ring, network and limits the mode chose. regulated-airgap is the exception and ships its sandbox on — containment is what that posture is.

Once it is on, a missing container runtime matters. cli.py blocks a shell call outright when an enforcing sandbox has no runtime behind it — it does not silently run unsandboxed — so mode apply preflights and degrades the sandbox axis to observe rather than leaving every command to fail one at a time. The rest of the posture (rules, egress, tag rules) still lands, and mode show re-checks at read time to catch a runtime that disappeared after the mode was applied. regulated-airgap enforces a sandbox but denies the Bash tool, so no shell event ever reaches the sandbox gate and it too runs without Docker.

Known limitation: the sandbox gate is wired for the Claude adapter only. On other agents the sandbox axis is not applied, even though mode explain still describes it.

Previewing a posture

--observe compiles any mode with nothing enforcing — same rules, same findings, no verdict blocks:

prismor mode apply dev-safe --observe

This answers "what would this posture stop?", which is the question worth asking before adopting one. mode show reports a preview build as such and never claims it is the enforcing article. Tool deny/ask lists are skipped in a preview build, because agents.yaml has no observe tier and writing them would enforce the one axis the flag promises not to.

mode explain always prints a residual risk paragraph. dev-safe allows api.github.com, so an injected agent can still paste a .env into a public issue comment; regulated-airgap is tight enough that the realistic failure is somebody running uninstall-hooks to get through the afternoon. A mode that claimed no downside would be the one not to trust.

Applying a mode overwrites .prismor/policy.yaml (keeping a .bak), and refuses outright if that file was not generated by a mode — pass --force once you have looked at what you are replacing. Hand-editing afterwards is fine; mode show then reports drift rather than claiming a posture the file no longer has.

Making exceptions

Often you don't want an exception at all, just "yes, run that, this once". A block carries a request id for exactly that:

prismor approvals                  # what is waiting
prismor approvals approve 4c3e28   # that exact call, once
prismor approvals deny 4c3e28

The approval covers the same agent making the same tool call with the same input in the same session and working directory, even when global and project hooks select different policy workspaces. If the hook omits a session ID or an absolute working directory, approvals remain scoped to its policy workspace. The first call it lets through spends it; another hook screening that same call can reuse it, including when the first hook held the call open. The approval lapses after 30 minutes if nothing uses it. approve tells you whether the agent is still waiting (it carries on by itself) or you have to go back and tell it to retry. Set PRISMOR_APPROVAL_WAIT=30 to make Claude Code and Codex hold the blocked call open for that many seconds (at most 45, which keeps it under the hook timeout). Approving inside that window lets the original call run, with no retry. Not offered for self-protection rules or on org-managed workspaces. approve needs a terminal, so an agent cannot approve its own call, even inside an unlock window.

When a rule blocks something it should not, the block prints the command that fixes it:

prismor allow secret-exfiltration --pattern 'curl -F [email protected]'   # just this case
prismor allow secret-exfiltration --observe                     # keep the rule, stop it blocking
prismor allow secret-exfiltration --off --yes                    # off in this workspace
prismor allow --list                                             # what you have added
prismor allow --undo allow-secret-exfiltration                   # remove one

Add --expires 30m to make an exception temporary — it lapses instead of quietly becoming permanent policy.

These are for the human at the keyboard. An agent that runs them is blocked, along with every other route to Prismor's own config: the policy file, the dashboard's write API, and the unlock credential. To hand the agent that ability for a few minutes, run prismor unlock and enter your password (prismor unlock --set-password if you have not set one). Inside the window the agent can adjust policy; it still cannot touch the self-protection rules or the password itself, and the window closes on its own.

Let your agent create or edit policy

You can have your agent (Claude Code, Codex, Cursor, ...) write a policy for you, or change one, as long as you open the door first:

prismor unlock              # asks for your password; 3 minutes by default
prismor unlock --for 15m    # longer, up to an hour (or your org's cap)

Then ask the agent for what you want ("block curl to anything but our API", "stop flagging git push in this repo"). Inside the window it can edit .prismor/policy.yaml, run prismor policy init to scaffold one, and run prismor allow. Every change is logged. It still cannot relax the self-protection rules, read or change the unlock password, or extend its own window. prismor lock closes the window early; prismor unlock --status shows how long is left. Check the result with prismor policy show.

An unhooked agent — one running through a framework Prismor does not see — is outside all of this, the same as every other Prismor control.

Runtime protection

eval-server

proxy

elevenlabs

inference-hook

prismor inference-hook-server remains as an alias for serve.

Full policy model, rule schema, and the default rule list: Prismor.

chatgpt-logs

Visibility

Secret prevention

Design, setup, best practices, and threat model: Sweep & Cloak.

Identity & scoping

Deep dives: IAM · Scoped Agent · Canary.

Adaptive defense

Deep dive: Learning.

Enterprise / org

Deep dive: Connecting to the platform · Policy layers & exemptions.

Supply chain

Scoring table, IOC feed, ecosystem support: Supply Chain.

Environment variables

See also

• Governance surfaces — hooks vs the MCP mirror, per agent

• Prismor — policy engine, session logs, audit, modes

• Supply Chain — install-time enforcement and scoring

• Network Isolation — egress allowlists, raw-IP detection

• Skill Scanner — MCP + skill risk scanning

• Sweep & Cloak — secret prevention

• Semantic Guard — LLM-assisted injection defense

• Canary · IAM · Scoped Agent · Learning · Dashboard

• Docker & Containers · Architecture