CLI Reference

This reference is aligned with the executable P.O.W.E.R. v3.6.2 parser.

Synopsis

power [-h] [-v] [--verbose]
      {init,lint,index,ingest,import,search,cache,doctor,connect,memory,handoff,task,sync,rot,archive,status,control-plane,maintenance,migrate-state,cron,heal,markdown-check,suggest-related,synthesize,rename} ...

Global options

Flag	Description
-h, --help	Show help and exit.
-v, --version	Show the installed P.O.W.E.R. version and exit.
--verbose	Enable DEBUG logging. Place it before the subcommand.

Exit behavior

• 0 means the command completed its executable contract.
• 1 is used for command-level failure such as a missing vault, blocking lint issues, an invalid domain registry, or strict index skips/conflicts.
• 2 is emitted by argparse for invalid command-line syntax or choices.
• lint can report non-blocking warnings, such as an orphan note, and still exit 0; inspect the report as well as the code.
• markdown-check, rot, status, and cron are reporting commands and do not currently fail merely because their report contains findings.
• index --strict is the automation-safe index gate: it exits non-zero when invalid notes are skipped or a foreign nested catalog prevents a safe write.

Commands

init

Create a new canonical vault. The target must be new or empty.

power init PATH

Creates canonical folders, 05_Templates/default.md, index.md, and log.md. Folder _index.md files are generated by power index.

lint

Run metadata, internal-link, orphan, and freshness checks.

power lint PATH

Blocking issues produce exit 1; informational warnings can coexist with exit 0.

index

Generate index.md and recursive per-canonical-folder catalog files.

power index PATH [--strict]

Flag	Description
--strict	Exit non-zero when invalid notes were skipped or catalog conflicts were preserved. Recommended for CI and migration gates.

The catalog scope is 00_Inbox, 01_Projects, 02_Areas, 03_Resources, 04_Archive, 06_Daily_Logs, and PROTOCOLS.

Each indexed directory receives an owned _index.md. Nested directories are linked from their parent catalog, and every catalog is paginated at a hard 32 KiB UTF-8 limit as _index.md, _index-2.md, and so on. Generated pages use explicit relative Markdown links and carry an x-generated-by: power marker. Existing unmarked nested _index.md and _index-N.md files are preserved and reported as conflicts. An unmarked top-level _index.md is upgraded only when it has POWER's legacy catalog frontmatter; otherwise it is also preserved. Remove or rename conflicts before using --strict.

ingest

Create a new validated note. This command creates a heading and frontmatter; it does not import an existing note body.

power ingest PATH --type TYPE --title TITLE --description DESCRIPTION
                   [--resource URL] [--tags TAG ...] [--overwrite]
                   [--domain DOMAIN]

Flag	Description
--type, -t	Required: Project, Area, Resource, Daily Log, Archive, or System Guide.
--title	Required note title.
--description	Required non-empty description. Stored descriptions are not truncated; catalog rendering is bounded.
--resource	Optional HTTP(S) source URL.
--tags	Zero or more space-separated tags.
--overwrite	Replace the generated target note if it already exists.
--domain	Explicit domain slug from .power/domains.yaml; otherwise configured rules may route the note.

Without a domain registry, note type determines the canonical target folder. The command uses the closed mutation workflow: it validates the note, updates the catalog and blocking lint, publishes the search generation, appends the operational log when present, and emits a content-free transaction receipt in the history ledger. No separate power sync or power index is required.

import

Preflight and import an existing Markdown tree into a canonical vault folder. The source is never modified. The command scans every source note and builds the complete report before creating a destination file or search index.

power import SOURCE --into VAULT_FOLDER [--path VAULT]
                    [--policy strict|quarantine] [--dry-run]
                    [--allow-partial]

Flag	Description
--into	Required vault-relative destination beginning with 00_Inbox, a P.A.R.A. folder, or PROTOCOLS.
--path	Target vault; defaults to POWER_VAULT_DIR, POWER_VAULT_PATH, or the current directory.
--policy	strict (default) rejects foreign known values; explicit quarantine retains status/related values under additive x-status/x-related fields.
--dry-run	Print the deterministic coverage, quarantine, exclusion, and collision report without writing anything.
--allow-partial	Explicitly permit importing valid notes when fatal source notes or collisions remain excluded.

type remains fatal. A successful apply regenerates the hierarchical catalog and builds an FTS index, so imported notes are searchable immediately. Dense embeddings remain an explicit follow-up through power sync PATH.

search

Search the vault with a lifecycle view and one executable retrieval mode.

power search PATH QUERY [--max-results N] [--mode MODE]
                        [--temporal-view VIEW] [--as-of YYYY-MM-DD]
                        [--domain DOMAIN]

Flag	Description
--max-results	Maximum results; default 20.
--mode	auto (default; verified dense or labelled FTS), fts, vector, hybrid, semantic, reranked, or graph_assisted; deprecated alias hybrid_reranked maps to reranked.
--temporal-view	current (default), historical, or all.
--as-of	Inclusive ISO date lifecycle boundary.
--domain	Optional configured domain slug for scoped retrieval.

Dense modes require a compatible full power sync; fts requires at least an FTS sync. reranked is explicit opt-in, not the default.

ONNX-backed embedding and reranking honor POWER_EMBED_DEVICE and POWER_RERANKER_DEVICE (auto, cpu, cuda, rocm, or directml). auto may fall back to CPU; an explicit accelerator mode fails closed if the created session does not bind the requested provider. The actual bound provider is logged during initialization.

memory

Human-governed transactional memory workflow.

power memory context PATH QUERY
power memory propose PATH NOTE_PATH (--content-file FILE | --content-stdin)
power memory apply PATH (--proposal-file FILE | --proposal-stdin) [--approved]
power memory validate PATH
power memory history PATH

propose validates and persists a content-addressed proposal under .power/proposals/<proposal_id>.json; it never writes the target note, index, or search projection. apply does not mutate memory unless the durable proposal is valid and --approved is present. After approval it runs one closed workflow: write the note, regenerate the hierarchical catalog, pass blocking lint, publish a searchable generation, and record a content-free receipt. If any phase fails, the note, generated catalogs, history, and active search projection are restored. A vault with an active dense projection refreshes it; a vault without one publishes FTS and reports search_mode=fts in the receipt. History never returns note content. The proposal and receipt also carry an idempotency_key; replaying the same approved proposal returns the original receipt without duplicating the note or history entry. Proposal content is read from a file or stdin; positional content and proposal JSON are rejected so sensitive data cannot appear in shell history or the process list.

handoff

Compatibility adapter for one durable, content-free Task v2 record. New clients should use power task; POWER records state and approval requirements but never executes the packet's next_action.

power handoff create PATH --task-id ID --objective TEXT --owner OWNER --actor ACTOR
                           [--scope PATH ...] [--authority read-only|propose|apply]
                           [--source-revision SHA] [--next-action TEXT]
                           [--profile standard|maintenance]
                           [--required-approval CLASS] [--idempotency-key KEY]
power handoff list PATH
power handoff show PATH --task-id ID
power handoff {resume,checkpoint,input-required,complete,fail,cancel} PATH
                           --task-id ID --idempotency-key KEY --actor ACTOR
                           [--approved] [--next-action TEXT] [--blocker TEXT]
                           [--required-approval CLASS] [--receipt-id ID]
                           [--changed-artifacts PATH ...] [--open-gates GATE ...]
                           [--phase detect|dry-run|repair|verify|receipt]

resume, checkpoint, and terminal transitions are idempotent by key. input-required records a blocker; resuming it requires explicit approval. The maintenance profile enforces detect → dry-run → repair → verify → receipt, and repair requires explicit approval. Packet fields contain metadata, paths, gate names, and receipt IDs only; retrieved note text remains untrusted data and is never an instruction channel.

task

Manage the canonical Task v2 record and its append-only event stream. Mutation commands require an actor and idempotency key; transitions also require the current expected revision. Task fields are bounded command-line values; no arbitrary JSON payload is accepted through argv.

power task list PATH [--state STATE] [--owner OWNER] [--assignee ASSIGNEE]
                    [--limit N] [--offset N]
power task read PATH --task-id ID
power task create PATH --task-id ID --title TITLE --actor ACTOR
                       --idempotency-key KEY [options]
power task transition PATH --task-id ID --state STATE
                           --expected-revision N --actor ACTOR
                           --idempotency-key KEY [options]
power task events PATH --task-id ID [--since-sequence N]

list returns a stable, updated-time-ordered page under the items field. events returns events after the supplied sequence, allowing cursor-style resume. Completing a task requires either an existing receipt ID or a verified postcondition plus one or more vault-relative artifact paths.

sync

Build the active search generation atomically.

power sync PATH [--fts-only] [--force] [--strict | --allow-partial]
                [--accept-dense-loss]

Flag	Description
--fts-only	Build the lightweight FTS index and skip embeddings.
--accept-dense-loss	Allow --fts-only to replace an existing dense index. Without it, such a run is refused.
--force	Force a full dense rebuild, for example after a model/dimension change.
--strict	Explicitly select the default fail-closed coverage policy; the command exits non-zero when notes are excluded.
--allow-partial	Explicitly accept excluded notes, continue with a warning, and exit zero with the complete path/reason receipt. Mutually exclusive with --strict.

An --fts-only run publishes a generation with zero chunks. When sources changed, that generation supersedes a dense one and every dense search mode then fails, so --fts-only is refused on a vault that already has an active dense index unless --accept-dense-loss is passed.

Every sync prints scanned, indexed and excluded note counts plus deterministic exclusion reasons. Full sync downloads and validates the pinned embedding assets as needed. It can be resource intensive. The default is fail-closed when any note is excluded; use --allow-partial only when a partial index is deliberate.

rot

Report redundant, outdated, and trivial notes.

power rot PATH [--extended]

--extended enables additional content-deduplication, link-rot, freshness, and usage scoring.

archive

Preview or perform archival of stale/expired notes to 04_Archive.

power archive PATH [--dry-run | --no-dry-run]

Dry run is the default. --no-dry-run performs the mutation.

status

Show vault counts, canonical folder distribution, graph metrics, and health.

power status [PATH]

PATH defaults to the current directory or configured vault environment.

cron

Run the reporting maintenance sequence: lint, hierarchical index, then ROT.

power cron PATH

The command currently returns 0 after the sequence and is not a strict replacement for separately checking power lint and power index --strict.

heal

Preview or repair missing/invalid frontmatter fields.

power heal PATH [--no-dry-run] [--limit N]

Flag	Description
--no-dry-run	Apply changes; default is preview only. Live edits create timestamped backups.
--limit	Heal at most N notes in this run.

The healer can infer canonical-folder type, filename title, first-paragraph description, timestamp, and type casing. Invalid foreign status and related values are retained under additive x-status/x-related keys before cosmetic fixes. It does not repair wikilinks or use an LLM.

Each note is isolated. Read, validation, transformation, backup, and write failures are named in the final report; the original note is left untouched when a live write fails. The command returns exit code 1 if any note fails, including in dry-run mode, and never reports a failed run as “No notes needed healing”.

markdown-check

Report trailing whitespace, inconsistent list markers, heading jumps, and code blocks without a language hint.

power markdown-check PATH

This is currently an informational report and returns 0 even when issues are found.

suggest-related

Suggest graph relations.

power suggest-related PATH [--target NOTE_PATH] [--max-results N] [--v2]

--v2 selects the weighted, explicit-link-aware Graph RAG v2 suggester. The command reports suggestions; it does not automatically write them.

synthesize

Create one session synthesis note with validated metadata, index rebuild, blocking lint, search publication, and log maintenance. The optional graph triplet extraction runs after the core transaction and cannot make a committed Markdown note disappear.

power synthesize PATH --name NAME --title TITLE --description DESCRIPTION
                      --content CONTENT [--note-type TYPE]
                      [--tags TAG ...] [--related PATH ...] [--owner OWNER]

--note-type defaults to Daily Log. The caller supplies classification and content; the command does not ask an LLM to invent them.

rename

Preview or perform a note move and update exact matches in OKF related paths.

power rename PATH --old OLD_RELATIVE_PATH --new NEW_RELATIVE_PATH
                  [--no-dry-run]

Dry run is the default. Live mode uses os.replace() for the physical move, including destination overwrite semantics on Windows. The propagation step is limited to related metadata and is not a complete wikilink/Markdown-link rewriter.

Vault path environment

CLI commands with an optional path resolve POWER_VAULT_DIR first. The legacy POWER_VAULT_PATH alias is accepted by the implementation, but new configurations should use POWER_VAULT_DIR, which is also the canonical MCP boundary.

cache

Inspect or prune the per-vault cache namespaces under the user cache directory. They hold the search generations, not vault content.

power cache list
power cache prune [--no-dry-run] [--include-unknown]

Flag	Description
--no-dry-run	Actually delete; the default is a preview only.
--include-unknown	Also remove namespaces with no source record.

Each namespace records the vault it belongs to, so prune removes only those whose vault is provably gone or has been re-identified. A namespace written before that record existed is reported as unknown and kept, because absence of a record is not evidence that the vault is gone; --include-unknown opts into removing those as well.

cache list prints every namespace with its verdict and size, which is the only way to see what a prune would target before running it.

doctor

Run a read-only diagnostic pass for the runtime and, optionally, one vault.

control-plane

Preview the human-visible POWER_STATUS.md control view. Add --apply to materialize it; the default is read-only and manual files are never overwritten. Add --obsidian-base to preview the optional POWER Control.base asset, or combine it with --apply to materialize both views. The generated Base has Active Work, Needs Human Decision, Stale Evidence, and Recent Changes tables; the Markdown view remains the fallback outside Obsidian. Uninstalling the Base is limited to the marked generated file and never removes notes.

power control-plane PATH --obsidian-base
power control-plane PATH --apply --obsidian-base

migrate-state

Print a content-free, read-only inventory of the source, control, runtime, and evidence planes. The plan includes exact file hashes, a disk budget, and a rollback boundary. Applying a state move is intentionally disabled until the cross-platform upgrade matrix is accepted.

power migrate-state PATH

maintenance

Print a deterministic, hash-bound maintenance plan. Add --apply to apply only reversible safe_auto actions; retention and archive candidates remain plan-only. The command does not create a vault identity, cache namespace, search database, or model files. The embedding probe uses only an already-cached pinned model; otherwise the report says that binding is not verified and recommends running power sync separately.

power doctor [PATH] [--json]

The report distinguishes compiled ONNX providers from the provider bound by a real embedding session. With --json, stdout contains the versioned report contract doctor-report-v1.json, including the complete excluded_notes ledger and stable issue codes for agents and CI. Human-readable output is a summary of the same report.

Exit 0 means the requested diagnostics are healthy. Exit 1 means the runtime, binding, vault, index, or coverage state is unavailable or degraded; an uncached model and excluded notes are therefore visible failures, not silent successes. Use power sync PATH --strict as the repair gate.

connect

Plan or apply a local stdio MCP connection for Codex, OpenCode, Gemini, or Claude. Planning is read-only and emits only hashes, paths, and status. Apply requires both a previously inspected plan and explicit approval.

power connect PATH [--client auto|codex|opencode|gemini|claude]
                    [--config CONFIG] [--executable PYTHON]
                    [--remove] [--apply --approved]
                    [--plan-file PLAN.json] [--plan-output PLAN.json]

The transaction refuses symlinked, malformed, commented JSONC, or foreign power entries for manual review. An approved update is bound to the exact pre-image hash, writes atomically, and creates a .power-backups copy before changing an existing config. A stale plan must be regenerated; the command never starts a client or contacts a network service.