Skip to content

CLI reference

Run prism without arguments to list every command, including tooling that is not described here.

Most commands read config.toml in the current directory. Only serve, update, plugins, secrets, backup and identity accept --config PATH, and config check takes the path as an argument. Run the others from the directory that holds the config: ~/.prism after the installer, /etc/prism with the Debian package.

Starts Prism in the foreground. Exit status 0 means Prism was stopped, 75 means a restart was requested (from the console or an update) and the supervisor should start it again, 1 means it failed.

Usage: prism serve [--config PATH]

prism config check validates a config file and the environment variables it names without opening ports or the database. It lists the providers Prism would start with and, once settings live in the console, which config.toml edits the next start imports or ignores.

Usage: prism config check [PATH] [--config PATH] [--json] [--strict]

Prints the web console address and the owner token.

Usage: prism console
Print the web console URL and the admin token a browser needs. The token comes
from PRISM_ADMIN_TOKEN, or from the token file Prism minted on first start
([console] admin_token_file, by default <storage.dir>/console-token). Run it on
the host: it reads local configuration and starts nothing.

Asks for a provider name and API key and stores the key in the macOS keychain, or in the sealed provider vault under [storage] dir on Linux and Windows — the same records the web console writes for provider connections. prism setup --local-embeddings with --artifact-url=, --artifact-sha256=, --artifact-signature= and --artifact-public-key= provisions the local embeddings runtime.

Prints the release version, operating system and architecture. Needs no config.

Also available as prism --version.

Prints the third-party license notices built into the binary.

Also available as prism licences.

Usage: prism licenses [NAME | --all]
List the third-party notices built into this binary, print one by name, or print all.

Prints the running server’s status snapshot (GET /prism/status) as JSON. Sends PRISM_ADMIN_TOKEN when it is set.

Asks the running server to rediscover provider models now, for all providers or one. Needs PRISM_ADMIN_TOKEN.

Usage: prism refresh [--provider=NAME] [--config PATH]
Run provider model discovery now on the running server (POST /prism/control action
refresh_discovery) so a newly released model shows up in /v1/models without restarting
prism serve or waiting for the catalog_refresh_hours tick. Without --provider every
configured provider is refreshed in configuration order, followed by one local fleet sweep
when [discovery.local_fleet] is enabled; --provider may also name a live fleet member. Reads [server] host/port from the configuration file
(--config PATH, PRISM_CONFIG, ./config.toml) and the admin token from
PRISM_ADMIN_TOKEN or <storage.dir>/console-token. Prints the control result as JSON;
exit 1 when any provider did not return a usable model list (it keeps its previous entries).

Asks the running server to reload model prices. Needs PRISM_ADMIN_TOKEN.

Usage: prism refresh-prices [--config PATH]
Ask the running server to refresh model pricing now (POST /prism/control action
refresh_pricing): the source is re-read and the live price table is reloaded, so a
changed price takes effect without restarting prism serve. Unlike `prism update-prices`,
which only rewrites the pricing file on disk, this reaches the process that is serving
requests. Reads the control address from [server] control_bind in the configuration file
(--config PATH, PRISM_CONFIG, ./config.toml) and the admin token from
PRISM_ADMIN_TOKEN or <storage.dir>/console-token. Prints the control result as JSON;
exit 1 when the refresh ran and failed, when the server is already refreshing, or when
one ran moments ago (the server rate-limits them).

Prints the running server’s description of itself for an agent’s system context.

Usage: prism agent-context [--format=markdown|json]
Print the agent-facing description of this Prism deployment (how to select a model,
how to read route attribution, which endpoints exist), fetched from the running
server so it always matches the live configuration. Redirect it into a file to
inject it as an agent's system context.

Prints the route facts of one request by its request id.

Usage: prism request-route <request_id>
Print request-exact route facts from GET /prism/requests/{id}/route on the
running server. Uses the admin token from PRISM_ADMIN_TOKEN, or the console token
file Prism minted on first start.

Checks and reloads provider keys stored as 1Password references (api_key_ref).

Usage: prism secrets <check|reload|status> [--config PATH]
check read every [[providers]] api_key_ref now with this host's 1Password
CLI and service account; print one line per reference; exit 1 when
any cannot be read. Values are never printed. Needs no running Prism.
reload ask the running Prism to re-read every reference now (control
action reload_secrets; admin token from PRISM_ADMIN_TOKEN or the
console token file).
status print the running Prism's reference states (GET /prism/secrets/status).

Checks for, installs and verifies Prism releases from the release channel.

Usage:
prism update check [--json] [--config PATH] [--url URL]
prism update install [--version vX.Y.Z] [--yes] [--json] [--timeout 10m] [--config PATH] [--url URL]
prism update status [--json] [--config PATH] [--url URL]
prism update verify --archive FILE --sums SHA256SUMS --signature SHA256SUMS.sig
check, install and status talk to the running Prism server: its address comes from
[server] host/port in --config (default config.toml) or from --url, and the owner token
from PRISM_ADMIN_TOKEN, else [console] admin_token_file, else <storage.dir>/console-token.
check exits 10 when a newer release is available and 0 when up to date. install installs
the latest release of the configured channel, or exactly --version, then follows the job
through the restart; it asks for confirmation unless --yes (required without a terminal).
Exit codes: 0 success, 1 failure (including a rollback), 2 usage error.

Lists, trusts, installs, probes, rolls back and removes plugin packages.

Usage:
prism plugins list [--json] [--config PATH] [--url URL]
prism plugins trust --key-id ID --public-key FILE --namespace DOMAIN [common flags]
prism plugins install --archive FILE [--development] [common flags]
prism plugins probe|rollback|remove --package ID [common flags]
prism plugins enable --package ID [--settings FILE] [--migration FILE] [common flags]
prism plugins disable|restart|rollback-active|state --package ID [common flags]
prism plugins retire --package ID --delete-data [common flags]
prism plugins call --package ID --method METHOD --id LOCAL_ID [--payload FILE]
[--state-revision N --idempotency-key KEY] [common flags]
prism plugins compat --storage DIR
Management uses the running owner's API and PRISM_ADMIN_TOKEN or the console
token file, just like prism update. Each mutation reads and compares the current
inventory revision. Commands never retry a mutation automatically.
install verifies a signed package and retains the previous artifact for rollback.
Unsigned packages require explicit --development; they cannot replace a signed
identity. probe starts and stops a staged worker without production grants.
disable keeps a package's settings and data, so remove refuses a package that
was ever enabled. retire deletes the disabled package's settings and data for
good and needs --delete-data to say so; remove then succeeds.
Installed packages do not yet contribute models, routing hooks or UI panels.
compat is the core updater's read-only local compatibility check; it executes no
plugin code. It checks --storage, or the storage directory named by --config when
--storage is absent. Exit codes: 0 success, 1 rejection/failure, 2 invalid arguments.

Prints a cost report from the local routing records; no running server needed.

Usage: prism cost [--days=N] [--group-by=provider|model|app|task_type]
Print cost report from local routing records.

Downloads the current model price catalog into pricing.json in the storage directory. Takes no flags; reads config.toml in the current directory.

prism backup create [--config PATH | --storage DIR] [--output FILE] [--include-secrets] writes an archive of the state directory; prism backup verify ARCHIVE checks one. Stop Prism before restoring an archive.

Shows or replaces this instance’s identity key.

Usage: prism identity <show|reset> [--config PATH|--storage DIR] [--yes]
show print this instance's fingerprint, or why the identity is unusable.
reset replace the instance key pair with a new one. Use it only when the
identity is damaged (instance_identity_invalid) and no backup with
secrets holds the old key. A reset instance is a new instance: it holds
no Teams binding, its enterprise-state.json is removed, and the
owner must bind the subscription again in the console (Upgrade plan).
Stop Prism first. Requires --yes.

prism local-embeddings-status [--self-check] prints the provisioning state of the local embeddings runtime.

prism local-embeddings-verify [--strict] [--json] re-checks the installed local embeddings artifact and endpoint. Exit status 2 means a readiness failure, 3 integrity, 4 probe, 5 several.

Runs a Model Context Protocol server on stdio with read-only Prism facts, or with operator tools for an operator token.

Usage: prism mcp [--operator]
Without flags, start the read-only Prism facts MCP server on stdio (protocol 2026-07-28).
Requires PRISM_FACT_BASE_URL and PRISM_ROUTE_READ_TOKEN.
--operator exposes only tools authorized by an operator-mcp credential.
Requires PRISM_OPERATOR_BASE_URL and PRISM_OPERATOR_TOKEN.
Provider/admin/deterministic-outcome credentials must not be present in the environment.

Writes a model manifest for an agent harness from the running server’s model catalog.

Usage of manifest:
-allow-defaults
include positive default and peer limits
-base-url string
Prism OpenAI-compatible base URL (default "http://127.0.0.1:18000/v1")
-out string
output file (default stdout)
-target string
harness target (prime-agent) (default "prime-agent")