Perseus CLI Reference

Run perseus <command> --help for full flags and options.

Command Surface

Command	What it does
perseus render <file>	Resolve all directives in a source document and print rendered output. Add --output <path> to write to disk. --format json for structured output with metadata, directive details, and integrity report — consumable by agents and CI pipelines. Custom format plugins in ~/.perseus/formats/<name>.py.
perseus scan <file> [--pii] [--json] [--report-only]	Security build gate. Render the context (with redaction off, in-memory) and scan the resolved output for secret shapes (and, with --pii, emails/SSNs/phone numbers/Luhn-valid cards). Prints a masked report and exits non-zero on findings so CI can block a leaking context. --report-only reports without failing.
perseus compress <file> [--output FILE] [--json] [--strip-comments]	Render then deterministically compress the context (trim trailing whitespace, collapse blank-line runs, drop adjacent duplicate lines, optional comment strip; fenced code preserved verbatim) and report a citable token-reduction percent. Dependency-free and reproducible — a build can assert on the number.
perseus graph <file> [--json]	Build a static directive graph without executing directives; foundation for predictive prefetching.
perseus prefetch <file> [--json]	Apply configured prefetch.rules to the static graph and warm directive caches.
perseus synthesize <question> --source FILE [--json]	Build a cited-synthesis prompt (sources + citation scaffolding) for the host agent to answer. Perseus runs no inference of its own.
perseus pack {validate,show} [--json]	Inspect and validate .perseus/pack.yaml context pack manifests.
perseus watch [--source FILE] [--output FILE] [--interval N]	Poll context sources and refresh render outputs without platform scheduler dependencies.
perseus validate --schema SCHEMA [payload|-] [--json]	Validate YAML/JSON payloads against Perseus schemas; omit payload or pass - to read stdin.
perseus checkpoint --task ... --status ... --next ...	Write a YAML waypoint to ~/.perseus/checkpoints/. Auto-updates Perseus Vault narrative.
perseus diff [--from FILE] [--to FILE]	Show diff between two checkpoints (default: latest two).
perseus recover [--workspace PATH]	Print the latest checkpoint for the workspace.
perseus agora [--status open|in_progress|completed]	Live task board from tasks/*.md.
perseus suggest <prompt>	Guide tool oracle — ranks skills against a prompt and prints the prompt for the host agent to answer, with transparent outcome-weight hints when data exists.
perseus memory {update,compact,show,status,query,federation}	Perseus Vault narrative project memory + cross-workspace federation.
perseus memory index {rebuild,stats,search}	Perseus Vault v2 FTS5 vault index management. rebuild re-indexes all .md files in ~/.perseus/memory/vault/. stats shows document count and index size. search --query "..." --k 5 runs a BM25 search against the vault.
perseus inbox {send,list,read,unread,mark-read}	Point-to-point messages between agents.
perseus health	Maintenance report — stale skills, large narrative, Guide log volume.
perseus oracle {accept,reject,log,export,infer-labels,outcomes,drift}	Daedalus Guide log management, inferred labels, outcome signals, and drift checks.
perseus init [--template name | --profile name] <workspace>	Scaffold .perseus/context.md; profiles also write .perseus/pack.yaml.
perseus serve [--port N] [--host H] [--generate-token]	Read-only HTTP view of workspace state on http://127.0.0.1:7991/; optional static bearer auth via serve.auth_token.
perseus serve --lsp --stdio|--tcp PORT [--allow-lsp-mutations]	Run as a Language Server Protocol server for editor integration. Mutation commands are opt-in.
perseus cron create SOURCE --output FILE [--every N] [--install]	POSIX crontab entry generator/installer for macOS, Linux, and BSD cron.
perseus systemd create SOURCE --output FILE [--interval 5m] [--install] [--enable]	Linux-only systemd --user service + timer scaffolder.
perseus launchd create SOURCE --output FILE [--interval 300] [--label LABEL] [--force]	macOS-only LaunchAgent plist scaffolder.
perseus schtasks create SOURCE --output FILE [--every N] [--install]	Windows Task Scheduler entry generator/installer.
perseus install --target {claude-code,cursor,gemini-cli,copilot} [--workspace PATH] [--dry-run]	Install Perseus hooks into an AI assistant.
perseus update [--apply] [--check] [--auto on|off]	Check for and apply Perseus updates from git.
perseus mcp {serve,config,register}	Run Perseus as an MCP server — expose directives as tools for any MCP-compatible assistant.
perseus doctor [--workspace PATH] [--json]	Run readiness checks against workspace and config (10 checks: config, context file, render settings, checkpoint age, Perseus Vault narrative, federation, Guide log, serve endpoint, directive registry, version).
`perseus context-inspector [INPUT.json] [--view summary	breakdown
perseus memory-efficiency [--output FILE]	Emit the offline Vault memory-injection efficiency report (#929): deterministic, hash-only token-savings evidence.
perseus skills {mine,list,approve,reject,telemetry}	Transcript mining → procedural skill synthesis (#932). mine scans session transcripts (assistant.sessions_dir) and stages candidate procedural skills (trigger, steps, pitfalls, evidence) in skills.candidates_dir — deterministic, no model. list [--status …] [--json] reviews them. approve <name> is the human/operator review gate: promotes a candidate into the live skills dir where @skills/@auto-skill see it. reject <name> tombstones it so re-mining never re-suggests it. telemetry [--output FILE] emits the #929-line context-token impact report for @skill-candidates surfacing. Mining never writes AGENTS.md/CLAUDE.md — surfacing is opt-in via the @skill-candidates directive in your context source.
perseus trust [--json] {profile,audit}	Show effective permission profile and trust posture; audit recent access decisions.

Context inspector

The inspector consumes existing context/DAG/evidence/quality and Vault selection artifacts without changing ranking or authority state. Its report schema is schemas/context-inspector.schema.yaml. The rendered ledger deliberately keeps retrieved, eligible, selected, delivered, omitted, saved, and provider-billed tokens separate; rendered estimates are not provider-billed savings. Candidate detail is commitment-first and does not copy raw prompts, tool payloads, credentials, or unredacted memory bodies.

perseus context-inspector .perseus/context-run.json --view summary
perseus context-inspector .perseus/context-run.json --view detail --json
perseus context-inspector --list-scenarios
perseus context-inspector --scenario evidence_verification --json

JSON Surfaces

Agent-readable --json contracts for synthesis, oracle, memory, federation, and drift commands are documented in Agent JSON Surfaces.

Quick Start

python -m pip install perseus-ctx==1.0.26
perseus init /workspace/myproject
perseus render /workspace/myproject/.perseus/context.md --output CLAUDE.md

See also: Directives Reference, Quickstart, Integration Guide