Phantasm CLI reference

phantasm --help
phm --help
phantasm --version
phm --version
phantasm bootstrap [project-path] [--agent-guidance] [--no-agent-plugin] [--agent-file <path>]
phantasm init [project-path] [--agent-guidance] [--no-agent-plugin] [--agent-file <path>]
phantasm agents --add [project-path] [--agent-file <path>]
phantasm agents-plugin [--target <target>] [--path <dir>] [--dry-run] [--force]
phantasm list [--kind <kind>] [--settled]
phantasm show <id>
phantasm search "query"
phantasm add --kind decision --subject release-process [--text "..."] [--review]
phantasm stats
phantasm status
phantasm dashboard [--port <PORT>] [--no-open] [--profile <PROFILE>]
phantasm handle-request '<json request envelope>'
phantasm handle-request --stdin
phantasm handle-request --file request.json

phm is the shorthand alias for the same CLI. init is an alias for bootstrap. phantasm --help prints a command index. Use phantasm agents-plugin --help, phantasm agents --help, or phantasm help agents for command-specific options.

Common command

phantasm bootstrap is the standard setup command for a project. phantasm init runs the same flow.

phantasm bootstrap
phantasm bootstrap .
phantasm bootstrap /path/to/project

Agent guidance options

phantasm bootstrap --agent-guidance
phantasm bootstrap --agent-guidance --no-agent-plugin
phantasm bootstrap --agent-file AGENTS.md
phantasm bootstrap --agent-file AGENTS.md --agent-file CLAUDE.md
phantasm agents --add
phantasm agents --add --agent-file AGENTS.md --agent-file CLAUDE.md

Use agents --add to add or refresh guidance without bootstrapping again. bootstrap --agent-guidance also installs the bundled phantasm-memory plugin into supported local harness plugin directories; add --no-agent-plugin to skip that. After updating Phantasm, rerun the command to replace the managed block in place; do not delete and re-add it manually. Before Phantasm changes an existing agent file, it creates a timestamped sibling backup, preserves text outside the managed markers, and prompts for confirmation with a y/N question.

Agent plugin installer

phantasm agents-plugin
phantasm agents-plugin --target codex
phantasm agents-plugin --path ~/.codex/plugins
phantasm agents-plugin --dry-run
phantasm agents-plugin --force

The installer copies the bundled harness-agnostic phantasm-memory plugin idempotently. Missing or unsupported auto-discovered harness targets are skipped and reported. Use --path for explicit plugin roots and --force only when replacing a changed existing plugin.

Human memory commands

These commands wrap the same project runtime used by handle-request, but avoid hand-written JSON for routine inspection and simple memory creation.

phantasm list
phantasm list --kind decision
phantasm list --settled
phantasm show rec_example
phantasm search "release process"
phantasm add --kind decision --subject release-process
phantasm add --kind decision --subject release-process --text "Release from main after tests pass." --review
phantasm stats
phantasm status

list and search print compact rows with record id, kind, lifecycle state, subject, and payload summary. show expands one object id. stats prints record counts, lifecycle state counts, scope counts, review queue size, and timestamps. status combines health, counts, schema version, and recommended maintenance. add creates a memory record; use --review when the write should enter review instead of becoming authoritative immediately.

Full MVP runtime operations

The current handle-request surface is the stable operation layer used by agents and wrappers. Run these requests from the bootstrapped project root so Phantasm resolves the correct .phantasm/ runtime. Requests can be passed as one argv JSON string, through --stdin, or from a UTF-8 file with --file <path>.

Every request includes api_version, operation, request_id, client.profile, and params. Mutating operations also require idempotency_key unless the request is a preview-only params.dry_run=true call. resolve_conflict, snapshot import, backup restore, and maintenance run require structured confirmations with approved_by, reason, operation, and a target matching the requested mutation. Dry-run previews skip confirmations because they do not mutate runtime state. The describe operation is the machine-readable discovery surface and can be called in short form when an agent does not know the full envelope yet. JSON strings preserve printable Unicode and accept standard \uXXXX escapes. Complete describe targets also return this CLI and transport contract as machine-readable metadata. Every response includes notices; after an update, the first successful request per project/client profile receives a structured release_update notice.

{
  "api_version": "v1",
  "operation": "health",
  "request_id": "health-1",
  "client": { "profile": "codex" },
  "params": {}
}

Advanced runtime examples

handle-request runs one JSON request against the current project runtime. These examples are intentionally single-line so agents and humans can paste them into a terminal.

printf '%s' '{"operation":"describe","params":{"target":"ingest"}}' | phantasm handle-request --stdin

phantasm handle-request --file request.json

phantasm handle-request '{"operation":"describe","params":{"target":"all"}}'

phantasm handle-request '{"operation":"describe","params":{"target":"*"}}'

phantasm handle-request '{"operation":"describe","params":{"target":"ingest"}}'

phantasm handle-request '{"api_version":"v1","operation":"templates","request_id":"templates-1","client":{"profile":"codex"},"params":{}}'

phantasm handle-request '{"api_version":"v1","operation":"health","request_id":"health-1","client":{"profile":"codex"},"params":{}}'

phantasm handle-request '{"api_version":"v1","operation":"search","request_id":"search-auth-timeout","client":{"profile":"codex"},"params":{"query":"auth timeout","filters":{"include_conflicts":true,"review_augmented_view":true}}}'

phantasm handle-request '{"api_version":"v1","operation":"compile","request_id":"compile-auth-timeout","client":{"profile":"codex"},"params":{"token_budget":1200,"focus_subjects":["auth.timeout"],"explain":true}}'

phantasm handle-request '{"api_version":"v1","operation":"ingest","request_id":"ingest-auth-timeout","client":{"profile":"codex"},"idempotency_key":"ingest-auth-timeout-v1","params":{"record_kind":"decision","subject_key":"auth.timeout","payload":{"text":"Auth tokens expire after 15 minutes."},"provenance":{"source":"agent","reason":"captured during implementation"}}}'

phantasm handle-request '{"api_version":"v1","operation":"ingest","request_id":"ingest-review-auth-timeout","client":{"profile":"codex"},"idempotency_key":"ingest-review-auth-timeout-v1","params":{"record_kind":"decision","subject_key":"auth.timeout","payload":{"text":"Auth tokens expire after 15 minutes."},"review_required":true}}'

phantasm handle-request '{"api_version":"v1","operation":"ingest_many","request_id":"ingest-auth-batch","client":{"profile":"codex"},"idempotency_key":"ingest-auth-batch-v1","params":{"items":[{"idempotency_key":"ingest-auth-timeout-v1","record_kind":"decision","subject_key":"auth.timeout","payload":{"text":"Auth tokens expire after 15 minutes."}},{"idempotency_key":"ingest-auth-issuer-v1","record_kind":"constraint","subject_key":"auth.issuer","payload":{"text":"Issuer validation is required."}}]}}'

phantasm handle-request '{"api_version":"v1","operation":"ingest","request_id":"ingest-auth-timeout-preview","client":{"profile":"codex"},"params":{"record_kind":"decision","subject_key":"auth.timeout","payload":{"text":"Auth tokens expire after 15 minutes."},"dry_run":true}}'

phantasm handle-request '{"api_version":"v1","operation":"inspect","request_id":"inspect-summary","client":{"profile":"codex"},"params":{}}'

phantasm handle-request '{"api_version":"v1","operation":"inspect","request_id":"inspect-1","client":{"profile":"codex"},"params":{"record_id":"rec_example"}}'

phantasm handle-request '{"api_version":"v1","operation":"stale_review","request_id":"stale-1","client":{"profile":"codex"},"params":{"max_age_days":30,"changed_files":["src/api.rs"]}}'

phantasm handle-request '{"api_version":"v1","operation":"duplicate_review","request_id":"dupes-1","client":{"profile":"codex"},"params":{"min_similarity":60}}'

phantasm handle-request '{"api_version":"v1","operation":"memory_export","request_id":"memory-export-1","client":{"profile":"codex"},"idempotency_key":"memory-export-1","params":{"path":"memory/phantasm.json","format":"json"}}'

Operation reference

describe is the important agent discovery operation. It returns machine-readable API schema, response schema, operation params, safety rules, and runnable examples. Optional param: target; use all, *, api, or an operation name such as ingest. all, *, and api return the complete catalog/schema plus cli, request_transport, and notices metadata. Short form is supported: {"operation":"describe","params":{"target":"ingest"}}.

bootstrap initializes or verifies .phantasm/. Humans usually use the top-level phantasm bootstrap command. Optional preview param: dry_run.

templates returns built-in templates for common memory record kinds such as project identity, architectural decision, operational constraint, known issue, release procedure, environment setup, and deferred task. Optional param: template_id. It is read-only and does not require a bootstrapped runtime.

ingest creates new memory. Trusted profiles create authoritative records; untrusted profiles create suggestions and review items. Trusted callers can set review_required=true to force suggestion/review behavior. Use revise, not ingest, to update an existing record; duplicate subject_key ingests are refused while a live record exists and return the existing record id. Required params: record_kind, payload. Common optional params include scope, subject_key, provenance, quality, sensitivity, raw_evidence, dry_run, and review_required. Quality carries confidence, source, verification, expiration, revalidation, and author metadata. Dry runs return no-write preview output including write_mode, would_create, or would_update.

ingest_many creates multiple memory records in one request. Required param: items. Each items[] entry requires idempotency_key, record_kind, and payload, and may include scope, subject_key, provenance, sensitivity, raw_evidence, dry_run, and review_required. Successful items are not rolled back when another item fails, and the batch response reports results, ok_count, error_count, and replayed_count.

revise creates a successor and supersedes a target record. Required params: target_record_id, payload. Optional preview param: dry_run.

tombstone retires invalid truth. Required params: record_id. Optional preview param: dry_run.

tombstone_many retires multiple records in one request. Required param: items. Each items[] entry requires idempotency_key and record_id, and may include reason and dry_run. Successful items are not rolled back when another item fails, and replay safety is tracked per item.

archive keeps memory for audit while excluding it from ordinary search and compile. Required params: record_id. Optional preview param: dry_run.

promote promotes scoped memory into project truth. Required params: source_record_id. Optional preview param: dry_run.

resolve_conflict chooses a winning record and retires losers. Required params: winner_record_id, loser_record_ids. Optional loser_state defaults to superseded. Requires structured confirmations whose target matches the winner, losers, and resolved loser state. Optional preview param: dry_run; dry-run previews do not require confirmations.

accept_suggestion converts a suggestion into authoritative memory. Required params: suggestion_id. Optional preview param: dry_run.

reject_suggestion rejects a suggestion without creating authoritative memory. Required params: suggestion_id. Optional preview param: dry_run.

defer_review defers a review item. Required params: review_item_id, wake_condition. Optional preview param: dry_run.

resolve_review marks a review item resolved. Required params: review_item_id. Optional preview param: dry_run.

search finds records by optional query, optional match_mode (tokens default, exact, or fuzzy), optional rank_by (deterministic or relevance), optional group_by=record_kind, and filters. Supported filters include lifecycle, scope, payload, and quality fields: quality_confidence, quality_source_type, verification and expiration bounds, and quality_author.

compile builds deterministic context using optional token_budget, focus_subjects, explain, and search-style filters. When explain=true, the response includes selection_diagnostics for selected and omitted candidates.

duplicate_review is read-only semantic-overlap review. Optional min_similarity, limit, include_cross_kind, and filters control duplicate groups; each group includes a preferred canonical record and consolidation actions.

inspect expands IDs returned by other operations. Params can include record_id(s), suggestion_id(s), review_item_id(s), operation_id(s), or evidence_id(s). With empty params, it returns a default memory summary with live records, scopes, lifecycle states, conflicts, and timestamps.

audit lists operation history and effects. Params: optional actor, object_id, operation_name, limit.

review_queue lists open and deferred review items.

stale_review is read-only freshness and changed-file impact review. It accepts optional max_age_days, as_of, changed_files, include_missing_verified_at, and filters, then returns reasons and suggested actions.

health reports runtime health, conflicts, review count, failed maintenance, diagnostics, recommendations, and first-call release notices after binary updates. Current runtimes also repair older v1 SQLite stores that are missing records.quality_json or suggestions.quality_json.

snapshot_export writes a full runtime snapshot bundle. Param: optional export_name. Optional preview param: dry_run.

snapshot_import restores a snapshot bundle after creating a safety backup. Required param: bundle_path. Optional mode is replace or merge. Requires structured confirmations whose target matches the bundle path and resolved mode. Optional preview param: dry_run; dry-run previews do not require confirmations.

memory_export writes Git-reviewable memory to a relative project path. Canonical json is importable; markdown is review-only. Sensitive records need explicit inclusion plus an export-capable profile.

memory_import additively reads a reviewed canonical phantasm.memory.v1 JSON file from a relative project path. Markdown is intentionally not importable, and duplicate live subject keys retain normal revise guidance.

backup_list lists registered backups and manifests.

backup_restore restores a registered backup by ID after creating a safety backup. Required param: backup_id. Requires structured confirmations whose target matches the backup ID. Optional preview param: dry_run; dry-run previews do not require confirmations.

maintenance_plan dry-runs recommended maintenance and required backup actions.

maintenance_run executes explicit maintenance operations. Optional operations defaults to ["reparse_client_profiles"]. Requires structured confirmations whose target matches the resolved operations list. Optional preview param: dry_run; dry-run previews do not require confirmations.

Configuration files after bootstrap

For the current post-bootstrap config surface, including every key in phantasm.toml and clients.toml, see configuration.html.

More detail

For the repository docs version of this reference, see docs/commands-and-usage.md.