vaultspec-core

vaultspec-core CLI referenceLink to vaultspec-core CLI reference

Complete command-line interface (CLI) reference for vaultspec-core. See the framework manual for workflows and concepts.

ContentsLink to Contents

Entry pointsLink to Entry points

  • vaultspec-core - Workspace management, vault operations, resource sync.

  • vaultspec-core-mcp - Console script that launches the stdio Model Context Protocol (MCP) server.

  • uv run --no-sync python -m vaultspec_core.mcp_server.app - Module invocation of the MCP server (avoids binary locking on Windows; --no-sync keeps a client connect from mutating the environment). See MCP reference.

Global optionsLink to Global options

These options apply at the top level unless noted. --debug and --version are top-level only. --target is accepted by target-aware workspace commands, vaultspec-core vault ..., vaultspec-core spec ..., and vaultspec-core migrations .... --json is command-specific and appears only on commands that support JavaScript Object Notation (JSON) output.

  • --target DIR (-t, default cwd) - Target workspace directory. Overrides VAULTSPEC_TARGET_DIR. Defaults to the current working directory if neither is set.

  • --debug (-d, default off) - Enable DEBUG-level logging (top-level flag).

  • --version (-V) - Print version and exit (top-level flag).

Outcome vocabularyLink to Outcome vocabulary

Commands that change files report what happened to each one with the same set of words, so results read the same no matter which command ran. The sync-style commands - vaultspec-core install, vaultspec-core sync, the vaultspec-core spec <resource> sync commands, and vaultspec-core migrations run - print one line per file, each marked with its glyph, then a count of each outcome. With --json, those per-file outcomes appear under data.items, and the envelope’s top-level status is the outcome for the whole run.

  • created (+) - A new file or directory was written.

  • updated (~) - An existing file was changed.

  • unchanged (=) - The file already matched its source, so nothing was written.

  • removed (-) - An existing file was deleted.

  • restored (*) - A file was reset to its original version.

  • skipped (s) - A file was left untouched because a rule or precondition excluded it; the reason is always reported.

  • failed (x) - A write was attempted and failed.

A --json status of mixed means one run produced more than one outcome. unchanged is a successful no-op, not a failure. Only failed stops a pipeline.

JSON output envelopeLink to JSON output envelope

Every command that accepts --json emits one uniform envelope, so a consumer parses one shape regardless of which command produced it:

Captured output

{
  "schema": "vaultspec.<command>.v1",
  "status": "<outcome word>",
  "data": { },
  "hints": { }
}

  • schema (required) - Namespaced identifier of the command plus a monotonic version integer.

  • status (required) - The canonical outcome word for the whole invocation (one of the seven words above, or mixed).

  • data (required) - The command-specific payload. Read-only commands report their content here under stable keys.

  • hints (optional) - Structured next-step guidance. Absent when no hint applies; its presence never changes status.

The schema value follows the convention vaultspec.<dotted-command-path>.v1 - for example vaultspec.sync.v1, vaultspec.vault.stats.v1, or vaultspec.spec.rules.add.v1. Every schema is at version v1 except vaultspec.vault.graph.v2, documented with vaultspec-core vault graph below. Adding new keys under data is additive and does not bump the version; renaming or removing a key bumps the integer (v2, …). Schema bumps are recorded in the release notes.

Failures under --json emit the same envelope with the fixed schema vaultspec.error.v1 and status set to failed; data.message carries the human-readable reason and data.hint carries remediation guidance when one is available. A status of failed always pairs with a non-zero exit code.

Under --json, stdout contains only the envelope; diagnostics go to stderr. Output is compact by default. For indentation, see environment variables. Use the top-level status field to check success.

Surface provenanceLink to Surface provenance

This reference is generated from the branch it ships on, which is ahead of the latest release between publications. The block below says by how much: what it lists exists here and is not yet installable. It is generated from the recorded surface of that release, so it covers every affected command rather than the ones somebody remembered, and it empties itself when the next release ships. Run vaultspec-core spec reference generate to refresh it and vaultspec-core spec reference snapshot to move the release it is measured against; do not hand-edit between the markers.

The latest published release is 0.2.4, and every command, flag, and tool documented here is in it.

Command indexLink to Command index

Every vaultspec-core command with its arguments. Run any command with --help for its full options.

Top-level commandsLink to Command index, Top-level commands

VaultLink to Command index, Vault

FeatureLink to Vault, Feature

CheckLink to Vault, Check

SanitizeLink to Vault, Sanitize

RuleLink to Vault, Rule

AdrLink to Vault, Adr

PlanLink to Vault, Plan

ExecLink to Vault, Exec

ArchiveLink to Vault, Archive

SpecLink to Command index, Spec

RulesLink to Spec, Rules

SkillsLink to Spec, Skills

AgentsLink to Spec, Agents

SystemLink to Spec, System

HooksLink to Spec, Hooks

TriggersLink to Spec, Triggers

PrecommitLink to Spec, Precommit

GitignoreLink to Spec, Gitignore

GitattributesLink to Spec, Gitattributes

McpsLink to Spec, Mcps

ReferenceLink to Spec, Reference

MigrationsLink to Command index, Migrations

ConfigLink to Command index, Config

Workspace commandsLink to Workspace commands

installLink to Workspace commands, install

Usage synopsis

vaultspec-core install [OPTIONS] [PROVIDER]

Deploy the vaultspec framework into the target directory.

ArgumentsLink to install, Arguments

  • PROVIDER (default all) - all, core, claude, gemini, antigravity, codex.

OptionsLink to install, Options

  • --upgrade (default off) - Re-sync builtins without re-scaffolding.

  • --dry-run (default off) - Preview without writing.

  • --force (default off) - Overwrite existing installation.

  • --skip (default []) - Skip specific sync passes (repeatable).

  • --mode (default auto) - Select generated hook and MCP launchers: tool uses uvx; dependency and dev use uv run --no-sync. Selection order: explicit --mode, saved mode in .vaultspec/workspace.json, dependency detection in pyproject.toml, then tool. This option doesn’t change package dependency declarations.

  • --no-hints (default off) - Suppress next-step advisory hints.

  • --json (default off) - Emit machine-readable output.

core installs .vaultspec/ only, without any provider config.

ExamplesLink to install, Examples

  • Install the framework for all supported provider layers in the current directory:

    Command

    vaultspec-core install all

uninstallLink to Workspace commands, uninstall

Usage synopsis

vaultspec-core uninstall [OPTIONS] [PROVIDER]

Remove the vaultspec framework from the target directory.

ArgumentsLink to uninstall, Arguments

  • PROVIDER (default all) - all, core, claude, gemini, antigravity, codex.

OptionsLink to uninstall, Options

  • --remove-vault (default off) - Also remove .vault/.

  • --dry-run (default off) - Preview without deleting.

  • --force (default off) - Required to execute (uninstall is destructive).

  • --skip (default []) - Skip specific removal passes (repeatable).

  • --json (default off) - Emit machine-readable output.

.vault/ is preserved by default. --remove-vault deletes it; commit or back up its records first.

ExamplesLink to uninstall, Examples

  • Preview removal while keeping feature records:

    Command

    vaultspec-core uninstall all --dry-run

  • After reviewing the preview, remove the harness and keep feature records:

    Command

    vaultspec-core uninstall all --force

syncLink to Workspace commands, sync

Usage synopsis

vaultspec-core sync [OPTIONS] [PROVIDER]

Authoritative complete sync from .vaultspec/ to enrolled provider outputs: rules, skills, agents, system prompts, provider config stubs, and MCP entries. After editing or adding framework source files, this is the normal propagation command.

ArgumentsLink to sync, Arguments

  • PROVIDER (default all) - all, claude, gemini, antigravity, codex.

core is not a valid sync target because sync reads from .vaultspec/. Use vaultspec-core install --upgrade or vaultspec-core install --force for framework/provider scaffolding repair, not as the normal propagation path after source edits.

OptionsLink to sync, Options

  • --dry-run (default off) - Preview changes without writing.

  • --force (default off) - Prune stale files and overwrite user-authored content.

  • --skip (default []) - Skip specific sync passes (repeatable).

  • --json (default off) - Emit machine-readable output.

ExamplesLink to sync, Examples

  • Synchronize modified rule and agent source files to all provider workspaces:

    Command

    vaultspec-core sync all

doctorLink to Workspace commands, doctor

Usage synopsis

vaultspec-core doctor [OPTIONS]

Diagnose overall workspace and vault health. This is the single health command: it runs the workspace diagnosis of vaultspec-core spec doctor and the full vault sweep of vaultspec-core vault check all, then reports both under one exit code. Reach for it when you want a yes-or-no answer about the whole project; reach for the two narrower commands when you already know which half you are investigating.

OptionsLink to doctor, Options

  • --target DIR (-t, default cwd) - Diagnose a directory other than the current one.

  • --json (default off) - Output as JSON.

Exit codes: 0 = all ok, 1 = warnings, 2 = errors.

Not every line the diagnosis prints is weighed. The tool-server configuration line, the process registry, and stale package seeds are reported for your attention and do not raise the code, so a run can print warn and still exit 0. Do not infer failure from the word warn in the output: read the exit code, or read status under --json. The conditions that do raise it are the framework layout, the provider directories, the builtins, .gitignore and .gitattributes, migrations, the pre-commit hooks, rename integrity, vault content, and an install-mode or version-floor mismatch on any declared package.

ExamplesLink to doctor, Examples

  • Check the health of the whole project, framework and vault together:

    Command

    vaultspec-core doctor

  • Diagnose another checkout and capture the result for a script:

    Command

    vaultspec-core doctor --target ../other-project --json

Vault commandsLink to Vault commands

Group command: vaultspec-core vault [OPTIONS] COMMAND [ARGS]...

vaultspec-core vault addLink to Vault commands, vaultspec-core vault add

Usage synopsis

vaultspec-core vault add [OPTIONS] DOC_TYPE

Create a new .vault/ document from a template.

ArgumentsLink to vaultspec-core vault add, Arguments

  • DOC_TYPE - adr, audit, exec, plan, reference, research.

OptionsLink to vaultspec-core vault add, Options

  • --feature TAG (-f) - Feature tag (kebab-case, lowercase letters, digits, hyphens). Required.

  • --date DATE (default today) - Override date (ISO 8601, e.g., YYYY-MM-DD).

  • --title TITLE - Document title.

  • --topic TOPIC - Kebab-case filename infix that distinguishes a second document of the same type for one feature, producing {date}-{feature}-{topic}-{type}.md. Only valid for adr, audit, reference, and research.

  • --related DOC (-r) - Related document(s). Accepts path, filename, stem, or [[wiki-link]]. Repeatable.

  • --tags TAG - Accepts only the document’s required directory and feature tags. Repeatable; duplicates are ignored. Other tags are rejected before writing, including with --force or --dry-run. Omit this option for ordinary creation.

  • --force (default off) - Overwrite an existing document at the resolved path.

  • --dry-run (default off) - Preview without writing files.

  • --json (default off) - Emit machine-readable JSON output in standard envelope.

  • --tier TIER (default L1) - Plan tier (L1, L2, L3, L4). Ignored for non-plan types.

  • --no-hints (default off) - Suppress next-step advisory hints.

exec is not a scaffold type. vaultspec-core vault add exec exits 1 with the message “execution is logged with vault exec log”; the ledger is the only execution artifact and vaultspec-core vault exec log its only writer.

vaultspec-core vault editLink to Vault commands, vaultspec-core vault edit

Usage synopsis

vaultspec-core vault edit [OPTIONS] REF

Set body and/or frontmatter in one atomic write. This is the primary editing surface for a scaffolded document: the body channel (--body-file or --body-stdin) and the frontmatter flags are applied together in a single write with a single validation pass, so a document never lands on disk with new prose and stale metadata. At least one edit - a body channel or a frontmatter flag - must be supplied.

--expected-blob-hash requires the full 40-character hash of the document version you reviewed. Compute it with git hash-object --no-filters <document-path>. The write is refused if the file’s raw bytes have changed. After a conflict, reread the document before computing a new hash.

ArgumentsLink to vaultspec-core vault edit, Arguments

  • REF - Document to edit. Accepts stem, filename, path, or [[wiki-link]]. Required.

OptionsLink to vaultspec-core vault edit, Options

  • --body-file FILE - Read the new body text from this file.

  • --body-stdin (default off) - Read the new body text from stdin.

  • --date DATE - Set the date field (YYYY-MM-DD).

  • --tags TAG - Set the tags list. Repeatable; replaces the whole list.

  • --related DOC (-r) - Set the related list. Repeatable; replaces the whole list. Each input is resolved to [[wiki-link]] form.

  • --expected-blob-hash HASH - Refuse the write unless the on-disk blob OID matches.

  • --check / --no-check (default --check) - Run conformance checks before writing.

  • --dry-run (default off) - Preview without writing.

  • --json (default off) - Output as JSON.

  • --target DIR (-t, default cwd) - Target directory.

ExamplesLink to vaultspec-core vault edit, Examples

  • Replace a document’s prose and relink it in one write:

    Command

    vaultspec-core vault edit 2026-05-17-test-feature-research --body-file draft.md --related 2026-05-17-test-feature-adr

  • Pipe generated prose in and preview the result before committing to it:

    Command

    cat draft.md | vaultspec-core vault edit 2026-05-17-test-feature-research --body-stdin --dry-run

vaultspec-core vault set-bodyLink to Vault commands, vaultspec-core vault set-body

Usage synopsis

vaultspec-core vault set-body [OPTIONS] REF

Replace a document’s body prose and update modified and body_hash. With --check (the default), the proposed content is validated first and the write is refused if any diagnostic is an error.

Use this when the metadata is already right and you only want to swap the prose; use vaultspec-core vault edit when the same change also touches frontmatter.

ArgumentsLink to vaultspec-core vault set-body, Arguments

  • REF - Document to edit. Accepts stem, filename, path, or [[wiki-link]]. Required.

OptionsLink to vaultspec-core vault set-body, Options

  • --body-file FILE - Read the new body text from this file.

  • --body-stdin (default off) - Read the new body text from stdin.

  • --expected-blob-hash HASH - Refuse the write unless the on-disk blob OID matches.

  • --check / --no-check (default --check) - Run conformance checks before writing.

  • --dry-run (default off) - Preview without writing.

  • --json (default off) - Output as JSON.

  • --target DIR (-t, default cwd) - Target directory.

ExamplesLink to vaultspec-core vault set-body, Examples

  • Swap in a rewritten body from a file:

    Command

    vaultspec-core vault set-body 2026-05-17-test-feature-research --body-file rewrite.md

To reject stale writes, use --expected-blob-hash.

vaultspec-core vault set-frontmatterLink to Vault commands, vaultspec-core vault set-frontmatter

Usage synopsis

vaultspec-core vault set-frontmatter [OPTIONS] REF

Edit selected frontmatter fields, keeping the body byte for byte. Only the fields you pass are changed and every other key is preserved. The proposed metadata is validated before writing and the write is refused on any violation, so a malformed tag set or date never reaches disk. The modified: stamp is refreshed automatically.

There is no --title flag: a document’s title is its body heading, not a frontmatter field. Both --tags and --related replace the whole list rather than appending, so pass every value you want to keep. To add or drop a single edge instead, use vaultspec-core vault link add and vaultspec-core vault link remove.

ArgumentsLink to vaultspec-core vault set-frontmatter, Arguments

  • REF - Document to edit. Accepts stem, filename, path, or [[wiki-link]]. Required.

OptionsLink to vaultspec-core vault set-frontmatter, Options

  • --date DATE - Set the date field (YYYY-MM-DD).

  • --tags TAG - Set the tags list. Repeatable; replaces the whole list.

  • --related DOC (-r) - Set the related list. Repeatable; replaces the whole list. Each input is resolved to [[wiki-link]] form.

  • --expected-blob-hash HASH - Refuse the write unless the on-disk blob OID matches.

  • --dry-run (default off) - Preview without writing.

  • --json (default off) - Output as JSON.

  • --target DIR (-t, default cwd) - Target directory.

ExamplesLink to vaultspec-core vault set-frontmatter, Examples

  • Repoint a document’s related list at its governing decision record:

    Command

    vaultspec-core vault set-frontmatter 2026-05-17-test-feature-plan --related 2026-05-17-test-feature-adr

  • Correct a document’s date without touching a word of its prose:

    Command

    vaultspec-core vault set-frontmatter 2026-05-17-test-feature-plan --date 2026-05-18

vaultspec-core vault renameLink to Vault commands, vaultspec-core vault rename

Usage synopsis

vaultspec-core vault rename [OPTIONS] REF

Rename a document’s file and re-point incoming references. The document is renamed to <--to>.md in the same directory, every other document’s related: [[old-stem]] entry is rewritten to the new stem, and the modified: stamp is refreshed. Pre-checks for blob hash, stem grammar, and filename collision run before anything is written, and the renamed document’s conformance diagnostics come back with the result.

This renames one document. To rename a whole feature - its documents, its exec folder, its tags, and its index - use vaultspec-core vault feature rename.

ArgumentsLink to vaultspec-core vault rename, Arguments

  • REF - Document to rename. Accepts stem, filename, path, or [[wiki-link]]. Required.

OptionsLink to vaultspec-core vault rename, Options

  • --to STEM - New identity-bearing stem (filename without .md). Required.

  • --expected-blob-hash HASH - Refuse the rename unless the on-disk blob OID matches.

  • --check / --no-check (default --check) - Report conformance checks on the renamed document.

  • --dry-run (default off) - Preview without writing.

  • --json (default off) - Output as JSON.

  • --target DIR (-t, default cwd) - Target directory.

ExamplesLink to vaultspec-core vault rename, Examples

  • Give a document a clearer stem and fix every link that pointed at it:

    Command

    vaultspec-core vault rename 2026-05-17-test-feature-research --to 2026-05-17-test-feature-intake-research

  • See which documents a rename would rewrite before running it:

    Command

    vaultspec-core vault rename 2026-05-17-test-feature-research --to 2026-05-17-test-feature-intake-research --dry-run

vaultspec-core statusLink to Vault commands, vaultspec-core status

Usage synopsis

vaultspec-core status [OPTIONS] [TARGET]

Orient in a vaultspec vault: rollup or a grounding trace for a target. This is the top-level zeroth move. Read-only - it never writes and produces no artifact.

Rollup mode (no TARGET): reports plans in flight, each with a one-line overview (tier, completed waves and phases, step completion, and the next open step); plans recently completed; recent changes grouped by type with ledgers collapsed per feature; active features; and vault totals. Outcome semantics: always unchanged (read-only verb). Advisory hints point at the targeted form and at vaultspec-core spec doctor for framework health.

Targeted mode (TARGET is a plan stem, plan path, or feature handle): renders the grounding trace - a plan-line header, then each step (display path, checkbox state, a cursor on the next open step) mapped to its evidence: ledger N rows plus the last verify: result for a step with ledger rows, no rows for an open step without any, or unlinked for a closed step without any. Exec documents that reference the plan but name no step are listed as unlinked records. Grounding documents are grouped by type beneath the step list. A feature handle traces every plan under that feature.

vaultspec-core status is orientation, not auditing: it describes what exists without judging conformance. Use vaultspec-core vault check to audit and vaultspec-core spec doctor for framework health.

OptionsLink to vaultspec-core status, Options

  • --limit N (default 10) - Recently modified documents to show, per type.

  • --since N - Show documents modified within the last N days.

  • --paths (default off) - Show each referenced document’s path (targeted mode).

  • --verbose-exec (default off) - List ledgers instead of collapsing them per feature.

  • --json (default off) - Emit machine-readable output (vaultspec.vault.status.v1).

  • --no-hints (default off) - Suppress next-step advisory hints.

--limit and --since apply only in rollup mode. --since switches from a last-N count to a day-window query.

ExamplesLink to vaultspec-core status, Examples

  • Get a vault-wide orientation rollup (in-flight plans and recent changes):

    Command

    vaultspec-core status

  • Trace a specific plan to its ledger rows and grounding documents:

    Command

    vaultspec-core status 2026-05-17-test-feature-plan

  • Show only documents modified in the last 7 days:

    Command

    vaultspec-core status --since 7

vaultspec-core vault listLink to Vault commands, vaultspec-core vault list

Usage synopsis

vaultspec-core vault list [OPTIONS] [DOC_TYPE]

List vault documents.

ArgumentsLink to vaultspec-core vault list, Arguments

  • DOC_TYPE - Filter by document type.

OptionsLink to vaultspec-core vault list, Options

  • --feature TAG (-f) - Filter by feature tag.

  • --date DATE - Filter by date.

  • --json (default off) - Emit machine-readable output.

  • --limit N (default 50) - Maximum documents to return.

  • --offset N (default 0) - Documents to skip, for paging.

ExamplesLink to vaultspec-core vault list, Examples

  • List all plans in the vault for a specific feature:

    Command

    vaultspec-core vault list plan --feature test-feature

vaultspec-core vault statsLink to Vault commands, vaultspec-core vault stats

Usage synopsis

vaultspec-core vault stats [OPTIONS]

Show vault statistics and document counts.

OptionsLink to vaultspec-core vault stats, Options

  • --feature TAG (-f) - Filter by feature tag.

  • --date DATE - Filter by date.

  • --type TYPE - Filter by document type.

  • --invalid (default off) - Show only documents with invalid links.

  • --orphaned (default off) - Show only orphaned documents.

  • --json (default off) - Emit machine-readable output.

ExamplesLink to vaultspec-core vault stats, Examples

  • Display vault-wide statistics with details for orphaned and invalid-link documents:

    Command

    vaultspec-core vault stats --invalid --orphaned

vaultspec-core vault graphLink to Vault commands, vaultspec-core vault graph

Usage synopsis

vaultspec-core vault graph [OPTIONS]

Outputs a hierarchical tree grouped by feature and type.

OptionsLink to vaultspec-core vault graph, Options

  • --feature TAG (-f) - Scope to a single feature.

  • --json (default off) - Output as networkx node-link JSON.

  • --metrics (-m, default off) - Show aggregate graph metrics.

  • --ascii (default off) - Render ASCII topology.

  • --body (default off) - Include document body in JSON output.

  • --node STEM - Scope JSON to a node’s local (ego) neighbourhood.

  • --depth N (default 1) - Ego-graph radius in hops; only used with –node.

  • --derived/--no-derived (default off) - Include the derived relatedness edge set in JSON.

  • --derived-limit N (default none) - Maximum derived edges to return. The per-node fan-out cap bounds edges per node, not the total.

  • --derived-offset N (default 0) - Derived edges to skip, for paging.

  • --ref REF - Read the vault corpus from this git ref (branch, tag, or commit) through the object database, without checking it out into the working tree.

The --json payload (schema vaultspec.vault.graph.v2) carries typed weighted explicit edges (kind, multiplicity, weight), node-size hints (pagerank, in_degree), and a separate derived_edges array of implicit relatedness edges kept out of the canonical edges array. A missing --node stem exits 1 with a failed envelope.

ExamplesLink to vaultspec-core vault graph, Examples

  • Visualize the vault hierarchy and structure as an ASCII tree scoped to a feature:

    Command

    vaultspec-core vault graph --feature test-feature --ascii

vaultspec-core vault repairLink to Vault commands, vaultspec-core vault repair

Usage synopsis

vaultspec-core vault repair [OPTIONS]

Run the operator repair pipeline for .vault/ content. This is the guided recovery surface for degraded vaults. It reports preflight and migration state, runs the health checks, applies supported mechanical fixes unless --dry-run is set, refreshes generated feature indexes unless --no-index is set, rebuilds graph state, and runs a postcheck pass.

vaultspec-core vault repair is broader than vaultspec-core vault check all --fix. The check-level fixer remains available for compatibility, but it does not own generated index refresh, post-fix graph rebuild, root-cause grouping, or final delta reporting. It also strips standalone annotation comments during the fix phase. Inline HTML comments embedded in prose are preserved.

OptionsLink to vaultspec-core vault repair, Options

  • --dry-run (default off) - Preview repair actions without writing.

  • --include-index/--no-index (default on) - Refresh generated feature indexes during repair.

  • --feature TAG (-f) - Scope repair and index refresh to one feature.

  • --verbose (-v, default off) - Show INFO-level diagnostics and detailed paths.

  • --json (default off) - Emit machine-readable phase and summary payloads.

PhasesLink to vaultspec-core vault repair, Phases

  • preflight - Report migration status and platform path behavior, name every document the pending migrations are about to remove, then apply them.

  • check - Run the current vault health suite without mutation.

  • fix - Apply supported safe check-level fixes, or report planned fixes.

  • index - Refresh or preview generated .vault/index/<feature>.index.md files.

  • postcheck - Rebuild graph state and rerun checks after mutation.

  • summary - Report changed files, generated indexes, unresolved work, root causes.

Dry-run mode never writes generated indexes or check fixes. If migrations are pending, dry-run reports that state rather than entering the index-refresh path, which converges the workspace before it writes.

The preflight phase lists the documents pending migrations would remove before it runs them, and reports where their copies went afterwards. See where deleted documents go: a repair on a stale workspace is the run with the most pending destructive entries, and every document it removes is copied to .vault/.trash/ first.

ExamplesLink to vaultspec-core vault repair, Examples

  • Scan and apply all safe automatic repairs to a degraded vault:

    Command

    vaultspec-core vault repair

vaultspec-core vault sanitize annotationsLink to Vault commands, vaultspec-core vault sanitize annotations

Usage synopsis

vaultspec-core vault sanitize annotations [OPTIONS]

Strip generated template annotations from .vault/ documents. Template hydration keeps agent-facing instructions in newly created documents; this command removes those instructions only when explicitly requested. Use --dry-run to see which files would be stripped without mutating the vault. The sanitizer removes YAML frontmatter comment directives, standalone HTML comment blocks, and malformed standalone <-- ... --> annotation blocks. It preserves fenced examples, inline HTML comments embedded in prose, and machine-owned comments such as retired plan markers.

OptionsLink to vaultspec-core vault sanitize annotations, Options

  • --feature TAG (-f) - Sanitize documents for one feature.

  • --dry-run (default off) - Preview annotation removals.

  • --verbose (-v, default off) - Show stripped files.

  • --json (default off) - Emit machine-readable check payloads.

  • --limit N (default 50) - Maximum findings to return.

  • --offset N (default 0) - Findings to skip, for paging.

ExamplesLink to vaultspec-core vault sanitize annotations, Examples

  • Strip all default template instructions and annotations from a feature’s documents:

    Command

    vaultspec-core vault sanitize annotations --feature test-feature

vaultspec-core vault feature listLink to Vault commands, vaultspec-core vault feature list

Usage synopsis

vaultspec-core vault feature list [OPTIONS]

List all feature tags in the vault.

OptionsLink to vaultspec-core vault feature list, Options

  • --date DATE - Filter by date.

  • --orphaned (default off) - Show only features with no incoming links.

  • --type TYPE - Filter by document type.

  • --stale-days N - Show only features whose latest activity is older than N days.

  • --json (default off) - Emit machine-readable output.

  • --limit N (default 50) - Maximum features to return.

  • --offset N (default 0) - Features to skip, for paging.

ExamplesLink to vaultspec-core vault feature list, Examples

  • List all active feature tags in the vault:

    Command

    vaultspec-core vault feature list

vaultspec-core vault feature indexLink to Vault commands, vaultspec-core vault feature index

Usage synopsis

vaultspec-core vault feature index [OPTIONS]

Generate or update <feature>.index.md files in .vault/index/. Each index links to every document sharing that feature tag, making implicit feature clusters explicit in the graph. Indexes carry the #index directory tag plus the feature tag and are auto-managed.

OptionsLink to vaultspec-core vault feature index, Options

  • --feature TAG (-f) - Generate index for a specific feature.

  • --json (default off) - Emit machine-readable output.

ExamplesLink to vaultspec-core vault feature index, Examples

  • Rebuild or generate the index document for a specific feature:

    Command

    vaultspec-core vault feature index --feature test-feature

vaultspec-core vault feature archiveLink to Vault commands, vaultspec-core vault feature archive

Usage synopsis

vaultspec-core vault feature archive [OPTIONS] FEATURE_TAG

Move all documents for a feature tag to the archive.

OptionsLink to vaultspec-core vault feature archive, Options

  • --dry-run (default off) - Preview planned changes.

  • --no-hints (default off) - Suppress next-step advisory hints.

  • --json (default off) - Emit machine-readable output.

  • --target (-t) - Target directory (defaults to current working directory).

ExamplesLink to vaultspec-core vault feature archive, Examples

  • Archive all documents for a completed feature tag:

    Command

    vaultspec-core vault feature archive test-feature

vaultspec-core vault feature unarchiveLink to Vault commands, vaultspec-core vault feature unarchive

Usage synopsis

vaultspec-core vault feature unarchive [OPTIONS] FEATURE_TAG

Restore all archived documents for a feature tag.

OptionsLink to vaultspec-core vault feature unarchive, Options

  • --dry-run (default off) - Preview planned changes.

  • --json (default off) - Emit machine-readable output.

  • --target (-t) - Target directory (defaults to current working directory).

ExamplesLink to vaultspec-core vault feature unarchive, Examples

  • Restore and unarchive all documents for a previously archived feature:

    Command

    vaultspec-core vault feature unarchive test-feature

vaultspec-core vault archive documentsLink to Vault commands, vaultspec-core vault archive documents

Usage synopsis

vaultspec-core vault archive documents [OPTIONS]

Archive exactly the live vault documents listed in a UTF-8 manifest. Each line must be a repository-relative .vault/*.md path. The command validates every source and destination before it moves anything, so a bad line cannot produce a partial archive.

OptionsLink to vaultspec-core vault archive documents, Options

  • --manifest PATH - Required UTF-8 manifest of repository-relative vault Markdown paths, one per line.

  • --dry-run (default off) - Validate and show the archive destinations without writing.

  • --json (default off) - Emit the standard machine-readable result envelope.

ExamplesLink to vaultspec-core vault archive documents, Examples

  • Preview the archival of explicitly selected historical records:

    Command

    vaultspec-core vault archive documents --manifest .vault/archive-manifest.txt --dry-run

vaultspec-core vault archive restoreLink to Vault commands, vaultspec-core vault archive restore

Usage synopsis

vaultspec-core vault archive restore [OPTIONS]

Bring archived documents back into the live vault. Each manifest line must be a repository-relative .vault/_archive/*.md path. This is the inverse of vaultspec-core vault archive documents: every source and destination is validated before anything moves, so a bad line cannot produce a partial restore.

OptionsLink to vaultspec-core vault archive restore, Options

  • --manifest PATH - Required UTF-8 manifest of repository-relative archived Markdown paths, one per line.

  • --dry-run (default off) - Validate and show the restore destinations without writing.

  • --deduplicate-identical (default off) - When an archived document already has a live counterpart with byte-identical content, drop the archived copy instead of failing on the collision. Documents whose contents differ are still reported as conflicts.

  • --json (default off) - Emit the standard machine-readable result envelope.

ExamplesLink to vaultspec-core vault archive restore, Examples

  • Preview restoring a set of archived records:

    Command

    vaultspec-core vault archive restore --manifest .vault/restore-manifest.txt --dry-run

  • Restore, clearing archived copies that already match the live document:

    Command

    vaultspec-core vault archive restore --manifest .vault/restore-manifest.txt --deduplicate-identical

vaultspec-core vault exec retireLink to Vault commands, vaultspec-core vault exec retire

Usage synopsis

vaultspec-core vault exec retire [OPTIONS]

Archive one execution record only when its current Step is retired by its parent plan.

OptionsLink to vaultspec-core vault exec retire, Options

  • --record PATH - Required live execution-record path.

  • --dry-run (default off) - Preview the recovery without writing.

  • --json (default off) - Emit the standard machine-readable result envelope.

vaultspec-core vault exec detachLink to Vault commands, vaultspec-core vault exec detach

Usage synopsis

vaultspec-core vault exec detach [OPTIONS]

Remove one record’s Step claim only when it resolves to neither a live nor a retired Step.

OptionsLink to vaultspec-core vault exec detach, Options

  • --record PATH - Required live execution-record path.

  • --dry-run (default off) - Preview the recovery without writing.

  • --json (default off) - Emit the standard machine-readable result envelope.

vaultspec-core vault exec foldLink to Vault commands, vaultspec-core vault exec fold

Usage synopsis

vaultspec-core vault exec fold [OPTIONS]

Fold a feature’s per-Step execution records, from before 0.1.74, into its plan’s ledger. The folded records are removed once the ledger carrying their content is on disk; the upgrade migration runs the same fold on its own.

A body-v1 record’s ## Scope paths become rows carrying the T (touched) operation, because that schema never recorded whether a path was added, modified, or deleted and none is invented; T stays distinguishable from a natively logged A/M/D/R. A body-v2 record’s ## Changes rows fold with their operations and verify: line intact, and its ## Notes lines are carried under the Step id. A flat <date>-<feature>-exec.md record carrying a step_id folds too. Other prose is discarded; it is recoverable from the commit preceding the fold, since .vault/ is tracked, but no forward command undoes it.

A Phase Summary is removed once every Step of its Phase has rows in the ledger, and left intact otherwise. A record with no step_id cannot be attributed to a Step and is left intact.

OptionsLink to vaultspec-core vault exec fold, Options

  • --feature FEATURE - Required feature tag, with or without a leading #.

  • --dry-run (default off) - Report the fold plan without writing.

  • --force (default off) - Required to apply; the fold removes records.

  • --json (default off) - Emit the standard machine-readable result envelope.

vaultspec-core vault exec logLink to Vault commands, vaultspec-core vault exec log

Usage synopsis

vaultspec-core vault exec log [OPTIONS]

Append one Step’s rows to its plan’s ledger, creating the ledger on first use. The ledger is one document per plan and the only execution artifact; it is append-only: existing rows are never rewritten, and re-logging an identical row is idempotent rather than duplicating it. Concurrent appends to one ledger are serialised by an advisory lock, and the managed .gitattributes block declares merge=union on ledgers so two branches appending different Steps merge without a conflict.

OptionsLink to vaultspec-core vault exec log, Options

  • --feature FEATURE - Required feature tag, with or without a leading #.

  • --related PLAN_STEM - Required stem of the parent plan this ledger records.

  • --step STEP - Required canonical Step identifier or display path being logged.

  • --row SPEC - Row to append, repeatable. A:path added, M:path modified, D:path deleted, R:old->new renamed. The verb never infers an operation from disk state.

  • --verify SPEC - A check that ran, as <command>=pass or <command>=fail; written as a verify: row.

  • --by PERSONA - The persona that closed the Step; written as a by: row.

  • --note TEXT - Exception note, repeatable; written as a ## Notes line under the Step id, the section created on first use.

  • --dry-run (default off) - Resolve and report the target ledger without writing.

  • --json (default off) - Emit the standard machine-readable result envelope.

vaultspec-core vault feature renameLink to Vault commands, vaultspec-core vault feature rename

Usage synopsis

vaultspec-core vault feature rename [OPTIONS] OLD_FEATURE NEW_FEATURE

Atomically rename a feature tag across every vault surface. The rename rewrites document filenames, the exec folder and the execution-record filenames inside it, the #feature frontmatter tag, related: wiki-links, and the regenerated feature index. Free-form body prose is never touched, so a sentence that happens to mention the old name stays as you wrote it.

The apply phase keeps a reverse journal. If anything fails part way through, the changes made so far are rolled back to the pre-rename state, so the vault is never left half renamed. By default the command refuses when the target feature already exists; --force merges the source feature into it, and per-file path collisions still refuse. Preview first with --dry-run - this command touches many files at once.

ArgumentsLink to vaultspec-core vault feature rename, Arguments

  • OLD_FEATURE - Current feature tag to rename. Required.

  • NEW_FEATURE - New feature tag name. Required.

OptionsLink to vaultspec-core vault feature rename, Options

  • --dry-run (default off) - Preview planned changes without writing.

  • --force (default off) - Merge the source into an existing target feature.

  • --json (default off) - Output as JSON.

  • --no-hints (default off) - Suppress next-step advisory hints.

  • --target DIR (-t, default cwd) - Target directory.

ExamplesLink to vaultspec-core vault feature rename, Examples

  • Preview the full set of files a feature rename would rewrite:

    Command

    vaultspec-core vault feature rename test-feature editor-demo --dry-run

  • Fold one feature’s documents into another existing feature:

    Command

    vaultspec-core vault feature rename test-feature editor-demo --force

vaultspec-core vault adr supersedeLink to Vault commands, vaultspec-core vault adr supersede

Usage synopsis

vaultspec-core vault adr supersede [OPTIONS] OLD_ADR

Supersede an old ADR with a new ADR.

ArgumentsLink to vaultspec-core vault adr supersede, Arguments

  • OLD_ADR - Old ADR stem to supersede.

OptionsLink to vaultspec-core vault adr supersede, Options

  • --by - New ADR stem that supersedes the old one.

  • --dry-run (default off) - Preview without writing.

  • --json (default off) - Output as JSON.

  • --target (-t) - Target directory (defaults to current working directory).

ExamplesLink to vaultspec-core vault adr supersede, Examples

  • Supersede an outdated ADR with a newly created one:

    Command

    vaultspec-core vault adr supersede 2026-05-17-old-adr-stem --by 2026-05-26-new-adr-stem

vaultspec-core vault rule promoteLink to Vault commands, vaultspec-core vault rule promote

Usage synopsis

vaultspec-core vault rule promote [OPTIONS]

Promote an audit finding to a project-level rule.

OptionsLink to vaultspec-core vault rule promote, Options

  • --from - Audit stem to promote from. Required.

  • --as - Kebab-case name of the promoted rule. Required.

  • --force (default off) - Overwrite existing rule source.

  • --dry-run (default off) - Preview without writing.

  • --json (default off) - Output as JSON.

  • --target (-t) - Target directory (defaults to current working directory).

ExamplesLink to vaultspec-core vault rule promote, Examples

  • Promote a specific finding from an audit file into a project-shared rule:

    Command

    vaultspec-core vault rule promote --from 2026-05-17-feature-audit --as project-rule-name

vaultspec-core vault checkLink to Vault commands, vaultspec-core vault check

Usage synopsis

vaultspec-core vault check [OPTIONS] COMMAND [ARGS]...

Run health checks on .vault/. Exits with code 1 if errors are found.

Shared optionsLink to vaultspec-core vault check, Shared options

  • --fix (default off) - Apply auto-fixes where supported.

  • --feature TAG (-f) - Limit to a specific feature.

  • --verbose (-v, default off) - Show INFO-level diagnostics.

  • --json (default off) - Emit machine-readable output.

  • --limit N (default 50) - Maximum findings to return per check. The per-check and aggregate counts are never windowed, so severity totals stay exact on any page.

  • --offset N (default 0) - Findings to skip, for paging.

vaultspec-core vault check all additionally accepts --no-hints to suppress the next-step advisory hints it prints after a run.

rename-integrity adds a second repair flag, because a name mismatch can be resolved from either side: --fix is filename-wins and rewrites the frontmatter name to match the file, while --fix-frontmatter-wins is the inverse and renames the file to match the frontmatter name. Pick the one whose side you trust.

SubcommandsLink to vaultspec-core vault check, Subcommands

  • all (--fix: partial, --feature: yes) - Run every check in sequence.

  • structure (--fix: yes, --feature: no) - Check vault directory structure and filename conventions.

  • frontmatter (--fix: yes, --feature: yes) - Validate document frontmatter against vault schema.

  • modified-stamp (--fix: yes, --feature: yes) - Validate and reconcile the modified: recency stamp on every document.

  • annotations (--fix: yes, --feature: yes) - Find generated template annotations in vault documents.

  • markdown (--fix: yes, --feature: yes) - Check and optionally fix markdown hygiene (whitespace, blank runs, trailing newline).

  • links (--fix: yes, --feature: yes) - Check wiki-links follow Obsidian convention (no .md extension).

  • dangling (--fix: yes, --feature: yes) - Find related: frontmatter wiki-links that resolve to no document.

  • body-links (--fix: yes, --feature: yes) - Find wiki-links and markdown path links in document body text.

  • placeholders (--fix: no, --feature: yes) - Find unreplaced {...} template placeholders in document body prose.

  • orphans (--fix: no, --feature: yes) - Find documents with no incoming wiki-links.

  • features (--fix: no, --feature: yes) - Check feature tag completeness - missing doc types.

  • exec-mapping (--fix: no, --feature: yes) - Pair ledger rows with plan Steps: a per-Step record or a closed Step with no row in an existing ledger is an error; a closed Step with no row in a plan without a ledger, a row for an open or unknown Step, is a warning; a row for a retired Step is clean.

  • body-sections (--fix: no, --feature: yes) - Check document bodies carry the sections their template mandates.

  • feature-rename-integrity (--fix: no, --feature: yes) - Surface exec folders whose feature disagrees with their records’ tag.

  • references (--fix: compatibility-only, --feature: yes) - Report missing cross-references without selecting evidence or decision links.

  • schema (--fix: compatibility-only, --feature: yes) - Check ADR links to Research, Reference, or Audit evidence and the status of decisions linked by active approved plans. Decision-free plans may have no ADR links.

  • adr-status (--fix: yes, --feature: yes) - Validate ADR status against the canonical taxonomy.

  • rename-integrity (--fix: yes, --feature: no) - Check name/filename integrity for rules, skills, and agents.

  • encoding (--fix: no, --feature: yes) - Surface .vault/ documents that are not valid UTF-8 (detection only).

  • code-boundary (--fix: no, --feature: yes) - Scan source files for references to the project’s own vault records (opt-in; findings are advisory).

  • foreign (--fix: no, --feature: no) - Warn about files the framework did not place inside the managed .vaultspec/ or .vault/ trees (detection only; findings are warnings, never errors).

compatibility-only means the flag is accepted but performs no repairs: evidence and authority links need an explicit choice. yes = fully supported, partial = only the sub-checks that accept --fix apply fixes (all dispatches to every check it runs), no = flag rejected with error. all runs twenty of the twenty-one checks above: code-boundary is opt-in and runs only when named, so an exit-0 all makes no claim about it. structure does not support --feature filtering.

Use vaultspec-core vault repair when the operator goal is end-to-end recovery with generated index refresh, post-fix validation, and a final delta report.

ExamplesLink to vaultspec-core vault check, Examples

  • Run all vault health checks to verify link integrity and directory structure:

    Command

    vaultspec-core vault check all

  • Audit and automatically repair dangling wiki-links:

    Command

    vaultspec-core vault check dangling --fix

  • Check feature completeness for a specific feature tag:

    Command

    vaultspec-core vault check features --feature test-feature

  • Scan for and report any generated template instructions or annotations:

    Command

    vaultspec-core vault check annotations --feature test-feature

  • Verify Obsidian-style wiki links in body text resolved against the vault:

    Command

    vaultspec-core vault check body-links

  • Audit rule, skill, and agent filenames for matching name tags:

    Command

    vaultspec-core vault check rename-integrity

  • Find all unreferenced (orphaned) documents in the vault:

    Command

    vaultspec-core vault check orphans

  • Validate document frontmatter fields against required templates:

    Command

    vaultspec-core vault check frontmatter --fix

  • Check wiki-link formats (ensuring no .md file extensions are used):

    Command

    vaultspec-core vault check links

  • Enforce architectural schema dependency rules:

    Command

    vaultspec-core vault check schema

  • Verify all external references are valid and up to date:

    Command

    vaultspec-core vault check references

  • Check directory structure and naming conventions for rules, skills, and agents:

    Command

    vaultspec-core vault check structure

vaultspec-core vault planLink to Vault commands, vaultspec-core vault plan

Usage synopsis

vaultspec-core vault plan [OPTIONS] COMMAND [ARGS]...

Inspect and manipulate plan documents per the plan-hardening convention. Plans declare a complexity tier (L1, L2, L3, L4) in frontmatter and are structured as Epic > Wave > Phase > Step. Every mutating operation goes through this surface. Canonical identifiers (S##, P##, W##) remain append-only and gap-no-reuse. vaultspec-core vault plan check flags hand-edits to checkbox glyphs or display paths.

ExamplesLink to vaultspec-core vault plan, Examples

  • Query all open steps in a plan:

    Command

    vaultspec-core vault plan query .vault/plan/2026-05-17-test-feature-plan.md --open

  • Append a Step to Phase P01 of an L2 plan:

    Command

    vaultspec-core vault plan step add --phase P01 --action "Implement login authentication handler" --scope "src/auth.py" .vault/plan/2026-05-17-test-feature-plan.md

  • Toggle completion checkbox of a step:

    Command

    vaultspec-core vault plan step toggle .vault/plan/2026-05-17-test-feature-plan.md S01

  • Renumber a phase to resolve duplicate identifier conflicts:

    Command

    vaultspec-core vault plan phase renumber --to P02 .vault/plan/2026-05-17-test-feature-plan.md P01

  • Validate the formatting and structure of an existing plan file:

    Command

    vaultspec-core vault plan check .vault/plan/2026-05-17-test-feature-plan.md

  • Mark a plan step completed (idempotent check):

    Command

    vaultspec-core vault plan step check .vault/plan/2026-05-17-test-feature-plan.md S01

  • Mark a plan step incomplete (idempotent uncheck):

    Command

    vaultspec-core vault plan step uncheck .vault/plan/2026-05-17-test-feature-plan.md S01

  • Insert a new step before an existing anchor step:

    Command

    vaultspec-core vault plan step insert --action "Validate input arguments" --before S02 .vault/plan/2026-05-17-test-feature-plan.md

  • Edit an existing step’s action prose and code scope:

    Command

    vaultspec-core vault plan step edit --action "New auth handler" --scope "src/auth.py" .vault/plan/2026-05-17-test-feature-plan.md S01

  • Move a step to a different phase inside the plan:

    Command

    vaultspec-core vault plan step move --to-phase P02 .vault/plan/2026-05-17-test-feature-plan.md S01

  • Retire a plan step permanently:

    Command

    vaultspec-core vault plan step remove .vault/plan/2026-05-17-test-feature-plan.md S01

  • Append a new phase to the current wave of a plan:

    Command

    vaultspec-core vault plan phase add --title "Authentication Layer" --intent "Set up secure login/signup" .vault/plan/2026-05-17-test-feature-plan.md

  • Insert a phase before an existing anchor phase:

    Command

    vaultspec-core vault plan phase insert --title "Database Setup" --before P02 .vault/plan/2026-05-17-test-feature-plan.md

  • Edit a phase’s title or intent prose in place:

    Command

    vaultspec-core vault plan phase edit --title "Updated Auth Setup" .vault/plan/2026-05-17-test-feature-plan.md P01

  • Move a phase to a different wave in the plan:

    Command

    vaultspec-core vault plan phase move --to-wave W02 .vault/plan/2026-05-17-test-feature-plan.md P01

  • Retire a phase along with all of its descendant steps:

    Command

    vaultspec-core vault plan phase remove .vault/plan/2026-05-17-test-feature-plan.md P01

  • Append a new wave to a plan:

    Command

    vaultspec-core vault plan wave add --title "Advanced Features" --intent "Add full-text search" .vault/plan/2026-05-17-test-feature-plan.md

  • Insert a wave after an existing anchor wave:

    Command

    vaultspec-core vault plan wave insert --title "Optimization Wave" --after W01 .vault/plan/2026-05-17-test-feature-plan.md

  • Edit a wave’s title or intent prose in place:

    Command

    vaultspec-core vault plan wave edit --title "Updated Core Wave" .vault/plan/2026-05-17-test-feature-plan.md W01

  • Move a wave to reposition it within the plan:

    Command

    vaultspec-core vault plan wave move --after W02 .vault/plan/2026-05-17-test-feature-plan.md W01

  • Retire a wave along with all of its descendant phases and steps:

    Command

    vaultspec-core vault plan wave remove .vault/plan/2026-05-17-test-feature-plan.md W01

  • Display the plan’s high-level Epic intent paragraph:

    Command

    vaultspec-core vault plan epic intent show .vault/plan/2026-05-17-test-feature-plan.md

  • Update the plan’s Epic intent paragraph:

    Command

    vaultspec-core vault plan epic intent edit --text "Epic intent text associating PM issues" .vault/plan/2026-05-17-test-feature-plan.md

  • Display the plan’s current complexity tier:

    Command

    vaultspec-core vault plan tier show .vault/plan/2026-05-17-test-feature-plan.md

  • Promote a plan’s complexity tier to L4:

    Command

    vaultspec-core vault plan tier promote --target L4 --epic-intent "Epic goal" .vault/plan/2026-05-17-test-feature-plan.md

  • Demote a plan’s complexity tier to L1:

    Command

    vaultspec-core vault plan tier demote --target L1 --force .vault/plan/2026-05-17-test-feature-plan.md

Shared mutation optionsLink to vaultspec-core vault plan, Shared mutation options

Every mutating plan verb - the step, phase, wave, epic-intent, and tier commands - shares three flags:

  • --dry-run (default off) - Preview the rewritten plan without writing it.

  • --json (default off) - Output as JSON.

  • --canonicalise (default off) - Strip unrecognized prose blocks while re-serializing the plan. Without it, prose the parser does not recognize is carried through untouched; with it, the plan is rewritten to the canonical structure only. Preview with --dry-run before using it on a plan that carries hand-written notes.

Read commandsLink to vaultspec-core vault plan, Read commands

  • status - Report plan health, structure, and completion. --json emits a machine-readable payload.

  • check - Validate convention compliance; with --fix, apply autofixable transformations.

  • query - Filter Step rows by --phase/--wave scope and --open/--closed predicate.

vaultspec-core vault plan check exits 1 when at least one ERROR-severity finding is present.

vaultspec-core vault plan statusLink to vaultspec-core vault plan, vaultspec-core vault plan status

Usage synopsis

vaultspec-core vault plan status [OPTIONS] PATH

Report plan health, structure, completion percentages, and identify missing execution records.

ArgumentsLink to vaultspec-core vault plan status, Arguments

  • PATH - Path to the .vault/plan/...-plan.md plan file.

OptionsLink to vaultspec-core vault plan status, Options

  • --json (default off) - Emit machine-readable status payload.

General OutputLink to vaultspec-core vault plan status, General Output

When run without --json, the command renders a console summary displaying:

  • Plan Path & Complexity Tier: Declared level (L1 to L4).

  • Container Counts: Total count of Epic, Waves, Phases, and Steps.

  • Completion Status: Checked vs. unchecked steps and total progress percentage.

Ledger Coverage (exec-missing)Link to vaultspec-core vault plan status, Ledger Coverage (exec-missing)

The status command pairs every checked step with the plan’s ledger:

  • If a step is checked ([x]) in the plan but the ledger has no row naming it, the CLI generates a yellow warning block:

    Captured output

    ! exec-missing: checked steps lacking execution records: S01, S02

  • This warning does not block execution or raise exit codes; the command still exits with code 0.

Machine-Readable Output (--json)Link to vaultspec-core vault plan status, Machine-Readable Output (--json)

When passed --json, the output utilizes the uniform vaultspec.vault.plan.status.v1 schema envelope:

Captured output

{
  "schema": "vaultspec.vault.plan.status.v1",
  "status": "unchanged",
  "data": {
    "path": ".vault/plan/2026-05-17-test-feature-plan.md",
    "tier": "L2",
    "waves": 0,
    "phases": 1,
    "steps": 5,
    "checked_steps": 2,
    "completion_pct": 40.0,
    "exec_missing_ids": ["S01", "S02"]
  }
}
ExamplesLink to vaultspec-core vault plan status, Examples

  • Check the progress and ledger coverage of a plan:

    Command

    vaultspec-core vault plan status .vault/plan/2026-05-17-test-feature-plan.md

Step commandsLink to vaultspec-core vault plan, Step commands

  • add - Append a Step at the next-available S##. Requires --action and --scope. At L2 and above, also supply --phase; omit it at L1.

  • insert - Insert at a named position with --before/--after; parent inferred from anchor.

  • edit - Replace --action, --scope, or both without changing the canonical identifier.

  • move - Re-parent (--to-phase), re-position (--before/--after), or both.

  • remove - Retire the Step’s canonical id permanently; the next-available counter skips it.

  • check - Mark the Step closed ([x]); idempotent.

  • uncheck - Mark the Step open ([ ]); idempotent.

  • toggle - Flip the Step’s checkbox state.

Phase commandsLink to vaultspec-core vault plan, Phase commands

  • add - Append a Phase at the next-available P##. Requires --title and --intent.

  • insert - Insert at a named position with --before/--after.

  • edit - Replace --title, --intent, or both in place.

  • move - Re-parent (--to-wave), re-position (--before/--after), or both.

  • renumber - Remediate a duplicated id via --to <P##>; refuses live / retired collisions.

  • remove - Retire the Phase plus every descendant Step (cascading retirement).

phase renumber is the audited remediation surface for collisions inherited from legacy plans. One example is a writer who treated P## as Wave-scoped rather than per-document. The verb retires the old id so it cannot be reused, then recomputes every descendant Step’s display path against the new parent canonical id.

Wave commandsLink to vaultspec-core vault plan, Wave commands

Identical shape to Phase, but the parent is implicit (Epic frame). Only --before/--after re-position. No --to-epic flag exists. Wave operations require L3 or L4.

Epic intent (L4 only)Link to vaultspec-core vault plan, Epic intent (L4 only)

  • intent show - Print the Epic intent paragraph.

  • intent edit - Replace the Epic intent paragraph; --text must declare the project-management (PM) association.

Tier commandsLink to vaultspec-core vault plan, Tier commands

  • show - Print the plan’s declared tier.

  • promote - Advance the tier transitively, for example L1 -> L4 in one call. Synthesized containers use --phase-title/--phase-intent/--wave-title/--wave-intent/--epic-intent for placeholders.

  • demote - Step the tier down. Refuses with an error when the collapsing layer holds more than one container; pass --force to retire the dropped ids and proceed.

Move-flag precedenceLink to vaultspec-core vault plan, Move-flag precedence

step move and phase move accept the re-parent flag (--to-phase / --to-wave) and the position flags (--before / --after) independently or together:

  • Re-parent flag alone re-parents and appends to the destination tail.

  • Position flag alone re-positions within the current parent; the anchor must share that parent.

  • Both flags re-parent and position the item; the anchor must reside in the destination post-move.

A self-referential move (step move S01 --before S01) is rejected with the relevant Move{Step,Phase,Wave}Error.

Identifier retirementLink to vaultspec-core vault plan, Identifier retirement

remove, multi-step demotion, and Wave / Phase removal all add the retired canonical id to a hidden <!-- RETIRED: ... --> ledger embedded in the plan body. next_available_* consults this ledger so retired identifiers are never reused, even across parse / serialize round-trips invoked by --fix.

Trailer commandsLink to vaultspec-core vault plan, Trailer commands

  • emit - Print a well-formed Vaultspec-Step or Vaultspec-Feature commit-linkage trailer line. Takes exactly one of --step (a Step or Phase display path, e.g. W01.P02.S06 or P02) or --feature (a kebab-case feature tag, leading # optional).

  • validate - Validate the commit-linkage trailers found in a commit-message file. Always exits 0.

The commit-linkage trailer is an opt-in, advisory convention (per the accepted commit-linkage ADR): a malformed or absent trailer never blocks a commit and never fails a core command. validate reports each malformed trailer to stderr and always exits 0, which makes it safe to wire up as a commit-msg-stage pre-commit hook. Teams that want the check add a local hook entry to their .pre-commit-config.yaml; teams that do not are unaffected:

File contents

- repo: local
  hooks:
    - id: vaultspec-plan-trailer
      name: Validate vaultspec commit-linkage trailers
      language: system
      stages: [commit-msg]
      entry: uv run vaultspec-core vault plan trailer validate

At the commit-msg stage, pre-commit passes the path to the commit-message file (for example .git/COMMIT_EDITMSG) as the hook’s positional argument, which lines up with validate’s MESSAGE_FILE argument - no extra flag is needed. Add uv’s --no-sync flag to the uv run wrapper when the environment is already resolved and the hook should skip the dependency check.

ExamplesLink to Trailer commands, Examples

  • Emit a Step trailer for a commit template:

    Command

    vaultspec-core vault plan trailer emit --step P02.S06

  • Emit a feature trailer:

    Command

    vaultspec-core vault plan trailer emit --feature commit-linkage

  • Validate a commit message file directly:

    Command

    vaultspec-core vault plan trailer validate .git/COMMIT_EDITMSG

Spec commandsLink to Spec commands

Group command: vaultspec-core spec [OPTIONS] COMMAND [ARGS]...

Spec subcommands that operate on a workspace accept --target / -t DIR. --json is command-specific and appears only on commands that support machine-readable output.

vaultspec-core spec doctorLink to Spec commands, vaultspec-core spec doctor

Usage synopsis

vaultspec-core spec doctor [OPTIONS]

Run diagnostic collectors across the framework, providers, builtins, .gitignore, vault content, and configuration files. Reports findings and exits with the highest severity observed. The vault content row is read-only; when generated template annotations are present, doctor reports a warning and points to vaultspec-core vault sanitize annotations. Unreadable vault markdown files are reported as warnings and are not modified.

OptionsLink to vaultspec-core spec doctor, Options

  • --target DIR (-t, default cwd) - Diagnose a directory other than the current one.

  • --json (default off) - Emit the diagnosis as JSON.

  • --gate-errors (default off) - Exit 0 on warnings and fail (exit 2) only on errors. Intended for the pre-commit gate, where warning-level provider-mirror lag is an expected steady state that must not block a commit.

Exit codes: 0 = all ok, 1 = warnings, 2 = errors.

Not every line the diagnosis prints is weighed. The tool-server configuration line, the process registry, and stale package seeds are reported for your attention and do not raise the code, so a run can print warn and still exit 0. Do not infer failure from the word warn in the output: read the exit code, or read status under --json. The conditions that do raise it are the framework layout, the provider directories, the builtins, .gitignore and .gitattributes, migrations, the pre-commit hooks, rename integrity, vault content, and an install-mode or version-floor mismatch on any declared package.

ExamplesLink to vaultspec-core spec doctor, Examples

  • Diagnose overall workspace health across configuration, git, and vault:

    Command

    vaultspec-core spec doctor

vaultspec-core spec rules / vaultspec-core spec skills / vaultspec-core spec agentsLink to Spec commands, vaultspec-core spec rules / vaultspec-core spec skills / vaultspec-core spec agents

Create, read, update, and delete (CRUD) operations for framework resources. All three groups share the same subcommand structure.

Usage synopsis

vaultspec-core spec rules [OPTIONS] COMMAND [ARGS]...
vaultspec-core spec skills [OPTIONS] COMMAND [ARGS]...
vaultspec-core spec agents [OPTIONS] COMMAND [ARGS]...

SubcommandsLink to vaultspec-core spec rules / vaultspec-core spec skills / vaultspec-core spec agents, Subcommands

  • list - List all resources.

  • add NAME [--body BODY] [--from-file FILE] [--force] [--dry-run] - Create a resource. skills add and agents add also accept --description TEXT for the resource’s frontmatter summary, and skills add additionally accepts --template NAME to scaffold from a named template instead of an empty body.

  • show NAME - Print resource content to stdout.

  • edit NAME [--editor EDITOR] - Open in configured editor. Resolution order: –editor flag, local config, VISUAL, EDITOR, vi. See which editors are accepted.

  • remove NAME [--yes|--force] (-y) - Delete a resource. Prompts unless confirmed.

  • rename OLD_NAME NEW_NAME - Rename a resource.

  • sync (--dry-run, --force) - Resource-scoped sync; use top-level vaultspec-core sync for a complete provider refresh.

  • restore FILENAME - Restore to snapshotted original.

  • status (--json) - Report dry-run sync with prune enabled, returning missing/drifted/stale status.

edit accepts the --editor option to override the editor binary for this invocation. add accepts the unified --body flag for direct content or --from-file to read from a file. Rules carry no description, so rules add has no --description; only skills support --template.

Which editors are acceptedLink to vaultspec-core spec rules / vaultspec-core spec skills / vaultspec-core spec agents, Which editors are accepted

The editor setting names a command that is executed, so it is validated before anything is launched. Two rules apply to every source.

The command must be a program name or path followed by plain arguments. Arguments are expected and supported - code --wait and subl -n -w are both fine, and a quoted path containing spaces is fine - but shell metacharacters (;, &, |, `, $, %, (, )), quoting syntax and control characters are refused. The editor is launched directly rather than through a shell, so those characters have no meaning here.

The program itself must be a known text editor when the value arrives through the --editor flag or through the project-local editor config key. Those two travel: a flag can be composed by automation, and .vaultspec/config.toml is committed with the workspace, so cloning a repository is enough to inherit its value. Roughly eighty editors are recognised, including vi, vim, nvim, nano, micro, emacs, helix, code, codium, cursor, zed, subl, kate, gedit, notepad, and the JetBrains launchers. A rejection message lists the full set.

The VAULTSPEC_EDITOR, VISUAL and EDITOR environment variables are not limited to that set. Setting an environment variable for a process already requires the ability to run code as that user, so screening it would protect nothing while stranding anyone whose editor is not recognised. If your editor is refused by the flag or the config key, set it in the environment instead:

Command

export VAULTSPEC_EDITOR="/opt/my-editor --wait"

An editor named by a source that is simply not installed is skipped, and resolution continues down the ladder as before; only a value that resolves and is then refused stops the command, so the reason is never silently swallowed.

Editing is interactive by definition. A command invoked through the MCP gateway’s invoke tool has no terminal attached, so no editor is opened for it from any source, and the gateway refuses --editor outright rather than passing it through.

vaultspec-core spec <resource> sync commands are narrow maintenance surfaces. They do not guarantee that provider-facing config stubs such as AGENTS.md, CLAUDE.md, GEMINI.md, or .codex/config.toml have been fully refreshed. Run vaultspec-core sync after source-side changes when the goal is a complete provider-facing workspace.

ExamplesLink to vaultspec-core spec rules / vaultspec-core spec skills / vaultspec-core spec agents, Examples

  • List all rules, skills, or agents configured in the current project:

    Command

    vaultspec-core spec rules list

  • Create a new custom project-level rule:

    Command

    vaultspec-core spec rules add enforce-newline --body "All workspace source files must end with a single trailing newline."

  • Create a new custom skill from a local template:

    Command

    vaultspec-core spec skills add unit-test-runner --description "Run python pytest suite" --template "templates/skill_template.md"

  • Create a new custom agent persona:

    Command

    vaultspec-core spec agents add database_expert --description "An expert database optimization agent"

  • Display the content of a project rule:

    Command

    vaultspec-core spec rules show enforce-newline

  • Edit a project skill using a specified editor command:

    Command

    vaultspec-core spec skills edit unit-test-runner --editor zed

  • Delete a project agent persona:

    Command

    vaultspec-core spec agents remove database_expert --force

  • Rename a project-level rule atomically:

    Command

    vaultspec-core spec rules rename old-rule-name new-rule-name

  • Synchronize local rules changes to enrolled provider output stubs:

    Command

    vaultspec-core spec rules sync

  • Report parsing and synchronization status of project skills:

    Command

    vaultspec-core spec skills status

  • Restore a default rule to its original snapshotted version:

    Command

    vaultspec-core spec rules restore enforce-newline.builtin.md

vaultspec-core spec systemLink to Spec commands, vaultspec-core spec system

Usage synopsis

vaultspec-core spec system [OPTIONS] COMMAND [ARGS]...

SubcommandsLink to vaultspec-core spec system, Subcommands

  • show (--json) - Display system prompt parts and generation targets.

  • sync (--dry-run, --force, --json) - Resource-scoped system prompt sync.

ExamplesLink to vaultspec-core spec system, Examples

  • Display assembled system prompt configuration and composition:

    Command

    vaultspec-core spec system show

  • Synchronize system prompts and stubs to provider workspaces:

    Command

    vaultspec-core spec system sync

vaultspec-core spec hooksLink to Spec commands, vaultspec-core spec hooks

Usage synopsis

vaultspec-core spec hooks [OPTIONS] COMMAND [ARGS]...

Agent-runtime hooks: shell commands your coding agent runs when something happens in a session. Authored once in .vaultspec/hooks/ and rendered into each installed provider’s native hook config. For the file format, the canonical events and each provider’s spelling, see agent-runtime hooks.

This group does not manage vaultspec’s own lifecycle events. Those are triggers, and they are a separate directory, a separate command group, and a separate approval.

SubcommandsLink to vaultspec-core spec hooks, Subcommands

  • list (--json) - List this workspace’s hooks and the providers they render into.

  • show NAME - Show one hook’s source file.

  • status (--json) - Report parse errors and events no installed provider can run.

  • sync (--dry-run, --force) - Render this workspace’s hooks into each provider’s native config.

  • trust [NAME] [--revoke] [--json] - Approve this workspace’s hooks to be rendered into your agents’ configs, or withdraw that approval.

There is no hook add: a hook is a file you write in .vaultspec/hooks/, like a rule or a skill.

  • add [NAME] [--event EVENT] [--command COMMAND] [--force] [--json] - Deprecated. Creates a trigger, not a hook, and is kept only so a caller of the pre-split name reaches what it meant. Use vaultspec-core spec triggers add.

  • run EVENT [--json] - Deprecated. Fires a trigger, not a hook. Use vaultspec-core spec triggers run.

Both print a deprecation line naming the replacement, and both are removed one release from now. They are listed rather than hidden because the operator reading --help to find where add went is exactly the person who needs to be told.

Hook trustLink to vaultspec-core spec hooks, Hook trust

A hook file declares a shell command, and .vaultspec/hooks/ is shared through git like the rest of your project policy, so a hook definition arrives with every clone and every pull. That makes the file itself the wrong place to record whether its command may run: anyone who can open a pull request could otherwise also grant themselves execution on every machine that clones the branch.

A rendered hook raises the stakes over a trigger, because it runs inside your agent’s session on every matching tool call rather than once per sync.

vaultspec-core therefore treats a workspace’s hooks as untrusted until an operator says otherwise, and records that decision outside the workspace - in the machine-global VaultSpec home, ~/.vaultspec/hook-trust.json. Nothing a checkout, an archive, or a clone carries can put an entry there. That file keeps its name from before hooks and triggers were separated; its entries are keyed by resolved path, so the two systems’ approvals never collide.

Approval is per file and pinned to that file’s exact contents. Editing a hook, or pulling a change to one, drops the approval until you grant it again, so a hook you approved last month cannot quietly become a different command this month. It also means a trusted hook stops running the moment its file changes, which is the intended trade: a second vaultspec-core spec hooks trust after an intentional edit is cheaper than an unnoticed one.

  • Anywhere without an operator - CI (CI is set), --json output, redirected input, VAULTSPEC_NON_INTERACTIVE, or an MCP tool call - the hooks are skipped and the reason is written to stderr. There is no flag that auto-approves, because a flag a script can pass is a flag a repository can talk a script into passing.

  • The refusal lives in the renderer, not in the prompt, so every route into it is gated and not only the ones that can ask. A hook with no source file on disk is refused for the same reason: nothing about it can be matched against the ledger.

  • You are asked before a sync that would render and before vaultspec-core install --upgrade. A fresh install renders nothing, so it does not ask.

  • Declining costs only the hooks. The sync itself still completes.

  • Revoking works end to end: the next sync omits the withdrawn hook and removes the entry it had written, rather than leaving it behind.

  • vaultspec-core spec hooks list shows a trust column, so an enabled hook that is not running never has to be a mystery.

  • The gateway’s invoke tool cannot reach vaultspec-core spec hooks sync, vaultspec-core spec hooks trust, vaultspec-core sync, or vaultspec-core install at all; they are denied at the MCP surface.

vaultspec-core spec hooks trust approves provider hooks only. When the workspace also has unapproved triggers, it says so and names the verb that approves those, because the two grants are separate.

ExamplesLink to vaultspec-core spec hooks, Examples

  • List this workspace’s hooks and where each one renders:

    Command

    vaultspec-core spec hooks list

  • See which declared events no installed provider can run:

    Command

    vaultspec-core spec hooks status

  • Approve this workspace’s hooks, then render them:

    Command

    vaultspec-core spec hooks trust
vaultspec-core spec hooks sync

  • Preview a render without writing:

    Command

    vaultspec-core spec hooks sync --dry-run

  • Withdraw approval; the next sync removes what it rendered:

    Command

    vaultspec-core spec hooks trust --revoke

vaultspec-core spec triggersLink to Spec commands, vaultspec-core spec triggers

Usage synopsis

vaultspec-core spec triggers [OPTIONS] COMMAND [ARGS]...

Lifecycle triggers: shell commands bound to vaultspec’s own events, fired by the CLI rather than by your agent. Source files live in .vaultspec/triggers/.

One event fires today, config.synced, after an all-provider vaultspec-core sync completes. Two earlier events were declared but never emitted and have been retired; a trigger bound to one is now reported rather than silently ignored.

SubcommandsLink to vaultspec-core spec triggers, Subcommands

  • list (--json) - List this workspace’s lifecycle triggers.

  • add [NAME] [--event EVENT] [--command CMD] [--body BODY] [--from-file FILE] [--force] [--dry-run] - Add a new trigger. --event defaults to config.synced.

  • show NAME - Display a trigger’s source file.

  • edit NAME [--editor EDITOR] - Open a trigger in the configured editor.

  • rename OLD_NAME NEW_NAME - Rename an existing trigger atomically.

  • remove NAME [--yes|--force] - Delete a trigger.

  • status (--json) - Report trigger parse errors and unsupported events.

  • run EVENT [--path PATH] - Fire this workspace’s triggers for one lifecycle event.

  • trust [NAME] [--revoke] [--json] - Approve this workspace’s triggers to run their shell commands as you, or withdraw that approval.

Trigger trustLink to vaultspec-core spec triggers, Trigger trust

Triggers carry the same consent model as hooks, for the same reason and through the same machine-global ledger: a trigger file arrives with every clone, so approval is recorded outside the workspace and pinned to each file’s contents. vaultspec-core sync and vaultspec-core spec triggers run show you each untrusted trigger’s command and offer to remember your approval, but only at an interactive terminal.

Approval is keyed by resolved path. Upgrading from a version that kept triggers in .vaultspec/hooks/ relocates them, which drops their approval - run vaultspec-core spec triggers trust once to restore it. The migration says so when it moves them.

The gateway’s invoke tool cannot reach vaultspec-core spec triggers add, vaultspec-core spec triggers run, or vaultspec-core spec triggers trust.

ExamplesLink to vaultspec-core spec triggers, Examples

  • Add a trigger that checks the vault after every sync:

    Command

    vaultspec-core spec triggers add post-sync-check --command "vaultspec-core vault check all"

  • List this workspace’s triggers and their trust state:

    Command

    vaultspec-core spec triggers list

  • Fire the triggers bound to the sync event:

    Command

    vaultspec-core spec triggers run config.synced

  • Report parse errors and events that no longer exist:

    Command

    vaultspec-core spec triggers status

  • Rename a trigger, then withdraw its approval:

    Command

    vaultspec-core spec triggers rename post-sync-check vault-gate
vaultspec-core spec triggers trust vault-gate --revoke

vaultspec-core spec gitignoreLink to Spec commands, vaultspec-core spec gitignore

Usage synopsis

vaultspec-core spec gitignore [OPTIONS] COMMAND [ARGS]...

SubcommandsLink to vaultspec-core spec gitignore, Subcommands

  • disable (--json) - Decline the vaultspec-managed .gitignore block for the whole project.

  • enable (--json) - Allow management of the .gitignore block for the whole project.

disable records blocks.gitignore = false in .vaultspec/workspace.json; commit this file to share the policy. enable clears that override. Neither command edits .gitignore; remove an existing managed block yourself if needed.

Install and upgrade create or restore the managed block unless project policy disables it. Ordinary sync leaves a manually removed block absent on that machine. To restore it, enable management and run vaultspec-core install.

Both commands exit zero when the requested policy already holds.

OptionsLink to vaultspec-core spec gitignore, Options

  • --json (default off) - Emit the result as JSON.

  • --target DIR (-t, default cwd) - Act on a directory other than the current one.

ExamplesLink to vaultspec-core spec gitignore, Examples

  • Decline the block for the whole project:

    Command

    vaultspec-core spec gitignore disable

  • Resume managing it:

    Command

    vaultspec-core spec gitignore enable

vaultspec-core spec gitattributesLink to Spec commands, vaultspec-core spec gitattributes

Usage synopsis

vaultspec-core spec gitattributes [OPTIONS] COMMAND [ARGS]...

SubcommandsLink to vaultspec-core spec gitattributes, Subcommands

  • disable (--json) - Decline the vaultspec-managed .gitattributes block for the whole project.

  • enable (--json) - Allow management of the .gitattributes block for the whole project.

These controls share the availability and policy behavior of vaultspec-core spec gitignore, using blocks.gitattributes in .vaultspec/workspace.json. The default entries control line endings and union merging of execution ledgers.

OptionsLink to vaultspec-core spec gitattributes, Options

  • --json (default off) - Emit the result as JSON.

  • --target DIR (-t, default cwd) - Act on a directory other than the current one.

ExamplesLink to vaultspec-core spec gitattributes, Examples

  • Disable managed Git attributes for the project:

    Command

    vaultspec-core spec gitattributes disable

  • Resume managing it:

    Command

    vaultspec-core spec gitattributes enable

vaultspec-core spec precommitLink to Spec commands, vaultspec-core spec precommit

Usage synopsis

vaultspec-core spec precommit [OPTIONS] COMMAND [ARGS]...

SubcommandsLink to vaultspec-core spec precommit, Subcommands

  • disable (--json) - Decline vaultspec-managed .pre-commit-config.yaml scaffolding.

  • enable (--json) - Restore vaultspec-managed .pre-commit-config.yaml scaffolding.

  • migrate (--remove-yaml, --dry-run, --json) - Transplant the canonical vaultspec hooks into prek.toml.

disable records hooks.pre_commit = false in .vaultspec/workspace.json to stop YAML scaffolding. Commit this file to share the policy; enable clears the override. Neither command changes existing configuration or uninstalls an active Git hook.

Install and upgrade can recreate missing YAML unless --skip precommit, project policy, or an owning prek.toml prevents scaffolding. Ordinary sync leaves manually deleted YAML absent. After enabling management, run vaultspec-core install to restore it.

With this policy disabled, reconciled ignore entries include /.pre-commit-config.yaml. Ignoring a file does not untrack an existing committed copy. Both policy commands exit zero when the requested state already holds.

When prek.toml owns the hook boundary, sync no longer scaffolds .pre-commit-config.yaml and prek silently ignores it. migrate renders the canonical hook set into a vaultspec-managed block inside prek.toml. It is idempotent - re-running with the hooks already present is a no-op - and the superseded YAML config is never deleted unless --remove-yaml is passed and the canonical hooks are verified present in prek.toml.

OptionsLink to vaultspec-core spec precommit, Options

  • --remove-yaml (default off, migrate only) - Also delete the superseded .pre-commit-config.yaml once the canonical hooks are verifiably present in prek.toml.

  • --dry-run (default off, migrate only) - Preview without writing.

  • --json (default off) - Emit the result as JSON.

ExamplesLink to vaultspec-core spec precommit, Examples

  • Stop vaultspec from ever writing the hook config again:

    Command

    vaultspec-core spec precommit disable

  • Restore managed scaffolding:

    Command

    vaultspec-core spec precommit enable

  • Preview the transplant without writing:

    Command

    vaultspec-core spec precommit migrate --dry-run

  • Transplant hooks, then remove the superseded YAML:

    Command

    vaultspec-core spec precommit migrate --remove-yaml

vaultspec-core spec mcpsLink to Spec commands, vaultspec-core spec mcps

Usage synopsis

vaultspec-core spec mcps [OPTIONS] COMMAND [ARGS]...

Manage canonical MCP server definitions in .vaultspec/mcps/*.json and reconcile them into provider-native enrollment files. Provider targets are all, claude, antigravity, and codex; scopes are project, local, and user. Unsupported provider/scope combinations fail instead of writing to a substitute location. Use top-level vaultspec-core sync for a complete refresh across all provider-facing outputs.

SubcommandsLink to vaultspec-core spec mcps, Subcommands

  • vaultspec-core spec mcps list - List all registered MCP server definitions.

  • vaultspec-core spec mcps status [PROVIDER] (--scope SCOPE, --json, --target PATH) - Inspect enrollment and ownership state without starting or probing MCP servers.

  • vaultspec-core spec mcps add --name NAME [--config JSON] [--force] - Add a new custom MCP server definition.

  • vaultspec-core spec mcps remove NAME [--force] - Remove an MCP server definition (--force skips confirmation).

  • vaultspec-core spec mcps sync [PROVIDER] (--scope SCOPE, --dry-run, --force, --prune, --json, --target PATH) - Reconcile canonical definitions into provider-native enrollment.

  • vaultspec-core spec mcps uninstall [PROVIDER] (--scope SCOPE, --dry-run, --force, --json, --target PATH) - Remove only vaultspec-owned provider-native enrollment.

vaultspec-core spec mcps status exits 0 only when MCP config status is ok, otherwise 1. It checks config health only and does not start or probe MCP server processes. The default provider is all and the default scope is project. --force on sync explicitly adopts or replaces same-name external enrollment; --prune removes owned enrollment whose canonical source was deleted. uninstall preserves canonical definitions and externally owned host entries.

ExamplesLink to vaultspec-core spec mcps, Examples

  • Verify the health and synchronization status of MCP server definitions:

    Command

    vaultspec-core spec mcps status

  • List all registered MCP server definitions:

    Command

    vaultspec-core spec mcps list

  • Sync registered MCP definitions to deployment files:

    Command

    vaultspec-core spec mcps sync

  • Inspect Codex project enrollment:

    Command

    vaultspec-core spec mcps status codex --scope project

  • Preview removal of vaultspec-owned Claude user enrollment:

    Command

    vaultspec-core spec mcps uninstall claude --scope user --dry-run

  • Register a new custom MCP server definition:

    Command

    vaultspec-core spec mcps add --name sqlite-mcp --config "{\"command\": \"npx\", \"args\": [\"@modelcontextprotocol/server-sqlite\"]}"

  • Remove a registered MCP server definition:

    Command

    vaultspec-core spec mcps remove sqlite-mcp --force

vaultspec-core spec referenceLink to Spec commands, vaultspec-core spec reference

Usage synopsis

vaultspec-core spec reference generate [OPTIONS]

Regenerate the generator-owned regions of the bundled machine-facing CLI reference (src/vaultspec_core/builtins/reference/cli.md) from the live Typer command surface. The reference is a hybrid of hand-written prose and generator-owned zones delimited by vaultspec:generated HTML-comment markers; this verb rewrites only the managed zones and leaves the prose untouched.

  • --check (default off) - Render in memory, diff against the committed file, exit non-zero on mismatch without writing.

  • --json (default off) - Emit machine-readable output.

Default (write) mode rewrites the bundled reference in place when the managed regions have drifted. --check mode is the CI and pre-commit entry point: it renders into memory, prints a unified diff on mismatch, and exits non-zero, leaving the file untouched (exit 0 when already in sync).

  • Refresh the bundled reference after a command or flag change:

    Command

    vaultspec-core spec reference generate

  • Verify the bundled reference is up to date (CI gate):

    Command

    vaultspec-core spec reference generate --check

Usage synopsis

vaultspec-core spec reference snapshot [OPTIONS]

Maintain src/vaultspec_core/builtins/reference/published-surface.json, the record of the command and MCP tool surface of the latest published release. The generated unreleased-surface regions of these documents are the difference between that record and the live surface, which is why no version caveat in them is hand-written.

  • --check (default off) - Report whether the record is due a refresh; exit non-zero when it is, without writing.

  • --emit (default off) - Print this build’s own surface as a snapshot document to stdout and write nothing.

  • --verify FILE - Compare a surface document (from --emit) against the committed record; exit non-zero when they differ.

  • --json (default off) - Emit machine-readable output.

Default (write) mode refreshes the record from the live surface, and only when the tree declares a different version from the one recorded. The record belongs to a release, so the release candidate branch - where the version is already the candidate’s and the tree is the one about to be tagged - is the only place it may move. On main between releases the versions match and the verb is a no-op; refreshing there would stamp the previous release’s version onto commands that release does not contain.

  • Refresh the record on a release candidate branch:

    Command

    vaultspec-core spec reference snapshot

  • Read a published distribution’s own surface back, in an isolated install:

    Command

    uv run --isolated --no-project --with vaultspec-core \
  vaultspec-core spec reference snapshot --emit > surface.json

  • Prove a released distribution matches the record shipped for it:

    Command

    vaultspec-core spec reference snapshot --verify surface.json

Migration commandsLink to Migration commands

Group command: vaultspec-core migrations [OPTIONS] COMMAND [ARGS]...

Every migration subcommand also accepts the global --target / -t DIR and --json flags.

The migration registry runs every entry whose target version exceeds the workspace manifest’s vaultspec_version, then bumps the manifest version on success. Migrations are idempotent, and because they relocate, rewrite, and delete tracked .vault/ documents they only run for a caller that asked to change the workspace:

  • vaultspec-core install --upgrade, vaultspec-core migrations run, and vaultspec-core vault repair run the whole registry - converging is what you invoked them for.

  • vaultspec-core vault add, vaultspec-core vault feature index and the MCP create tool run only the entries that decide where their own write lands. Writing a document into a stale layout is what leaves one feature with two tracked indexes, so they fix that; they never rewrite or delete a document you did not name.

That second rule is deliberately narrow. A verb that writes one document has no standing to rewrite forty-seven others, so returning to a long-untouched workspace and adding one ADR converges the layout and leaves everything else exactly where it was. The entries that fold and remove documents wait for one of the three commands above.

Every other command, including every read (vaultspec-core vault list, vaultspec-core vault graph, vaultspec-core vault check, and the MCP query tools), leaves the workspace exactly as it finds it.

Anything left pending is reported rather than silently deferred: any command that observes a stale workspace logs a warning naming the outstanding entries. Run vaultspec-core migrations status to see them, and vaultspec-core migrations run to apply them - it names every document it is about to remove and asks before it does.

Where deleted documents goLink to Migration commands, Where deleted documents go

Some migrations remove .vault/ documents - the execution-record folds replace a folder of per-Step records with one ledger, and that consolidation is not expressible as an additive rewrite. Before any of them unlinks a file, a byte-identical copy of it is written to:

Captured output

.vault/.trash/<YYYYMMDD-HHMMSS>-<migration>/<the document's path under .vault/>

Each snapshot directory also carries a RESTORE.txt naming every copy’s original location, so a file can be identified by the path it had rather than by its name alone.

  • How long they stay: forever. Nothing in vaultspec ever deletes a snapshot. A safety net that expires on a timer is not a safety net, and for a document authored since the last commit - or in a workspace whose .vault/ is not in git at all - the snapshot is the only copy that exists. The directory is listed in the managed .gitignore block, so it never enters the repository. Delete it yourself when you have decided the documents are not coming back; .vault/.trash/ is always safe to remove in whole or in part.

  • How to get one back: copy it. There is no restore command, because a snapshot is a plain directory of unmodified files and copying one back is the whole operation. Read RESTORE.txt for the destination, then:

    Command

    cp .vault/.trash/20260517-120000-exec_ledger_only/exec/2026-05-17-demo/2026-05-17-demo-P01-S01.md     .vault/exec/2026-05-17-demo/

  • If the copy cannot be written, nothing is deleted. A full disk or an unwritable .vault/ fails the migration before the first unlink and leaves the manifest version alone, so the next run re-attempts. Deleting because the backup failed is the one outcome worse than not deleting.

Preview a deletion before it happens with vaultspec-core migrations run --dry-run, which enumerates every path the run would remove and changes nothing. The list comes from the same planner the real run applies, so it is the run rather than a description of one.

vaultspec-core migrations statusLink to Migration commands, vaultspec-core migrations status

Usage synopsis

vaultspec-core migrations status [OPTIONS]

List registered migrations and which entries are pending against the current workspace manifest. Read-only; never mutates.

OptionsLink to vaultspec-core migrations status, Options

  • --target DIR (-t, default cwd) - Inspect a workspace other than the current directory.

  • --json (default off) - Emit status, registered list, and pending list as JSON.

Exit codes: 0 when up to date or workspace has no manifest, 1 when migrations are pending.

ExamplesLink to vaultspec-core migrations status, Examples

  • List all registered schema migrations and check for pending entries:

    Command

    vaultspec-core migrations status

vaultspec-core migrations runLink to Migration commands, vaultspec-core migrations run

Usage synopsis

vaultspec-core migrations run [OPTIONS]

Apply every pending migration in version order and bump the manifest’s vaultspec_version. A migration that fails stops the run and leaves the manifest unchanged so the next invocation re-attempts it.

OptionsLink to vaultspec-core migrations run, Options

  • --target DIR (-t, default cwd) - Migrate a workspace other than the current directory.

  • --dry-run (default off) - List every document the pending migrations would delete and change nothing.

  • --yes (-y, default off) - Skip the confirmation prompt for deletions.

  • --json (default off) - Emit per-entry summaries and counts as JSON.

When the pending migrations would delete documents, an interactive terminal is asked to confirm unless --yes is passed. Non-interactive callers - CI, --json, the MCP server, a piped or closed stdin - are warned and proceed rather than waiting for input: the registry also runs from vaultspec-core install --upgrade, vaultspec-core vault repair, and the authoring verbs that let the schema decide where they write (vaultspec-core vault add, vaultspec-core vault feature index, and the MCP create tool), so refusing here would only push a blocked script onto a trigger that asks nothing at all. Either way, every removed document is copied into .vault/.trash/ first.

Exit codes: 0 on success (including the no-pending no-op and every dry run), 1 if any migration failed or an operator declined the deletion.

ExamplesLink to vaultspec-core migrations run, Examples

  • Preview every document the pending migrations would delete:

    Command

    vaultspec-core migrations run --dry-run

  • Execute all pending schema migrations and upgrade the workspace:

    Command

    vaultspec-core migrations run --yes

Config commandsLink to Config commands

Group command: vaultspec-core config [OPTIONS] COMMAND [ARGS]...

Manage local project configuration settings stored in .vaultspec/config.toml at the workspace root.

Every config subcommand also accepts the global --target / -t DIR and --json flags.

vaultspec-core config getLink to Config commands, vaultspec-core config get

Usage synopsis

vaultspec-core config get [OPTIONS] KEY

Read a local configuration value.

OptionsLink to vaultspec-core config get, Options

  • --json (default off) - Emit machine-readable output.

ExamplesLink to vaultspec-core config get, Examples

  • Retrieve the local project-level editor setting:

    Command

    vaultspec-core config get editor

vaultspec-core config setLink to Config commands, vaultspec-core config set

Usage synopsis

vaultspec-core config set [OPTIONS] KEY VALUE

Write a local configuration value. Supported keys: editor.

The editor value is validated on write and again every time it is used, so a file written by an older version or edited by hand cannot slip past the check. See which editors are accepted. Reading and clearing keep working on a value the edit path refuses - vaultspec-core config get editor, vaultspec-core config list, and vaultspec-core config unset editor are all unaffected - so an inherited setting can always be inspected and removed.

OptionsLink to vaultspec-core config set, Options

  • --json (default off) - Emit machine-readable output.

ExamplesLink to vaultspec-core config set, Examples

  • Configure the local project-level editor command to Zed:

    Command

    vaultspec-core config set editor zed

vaultspec-core config unsetLink to Config commands, vaultspec-core config unset

Usage synopsis

vaultspec-core config unset [OPTIONS] KEY

Clear a local configuration entry.

OptionsLink to vaultspec-core config unset, Options

  • --json (default off) - Emit machine-readable output.

ExamplesLink to vaultspec-core config unset, Examples

  • Clear the local project-level editor configuration:

    Command

    vaultspec-core config unset editor

vaultspec-core config listLink to Config commands, vaultspec-core config list

Usage synopsis

vaultspec-core config list [OPTIONS]

Enumerate all known configuration entries and current values.

OptionsLink to vaultspec-core config list, Options

  • --json (default off) - Emit machine-readable output.

ExamplesLink to vaultspec-core config list, Examples

  • Enumerate all local project-level configuration settings and values:

    Command

    vaultspec-core config list

Environment variablesLink to Environment variables

All variables are prefixed VAULTSPEC_. Environment variables override defaults but are overridden by the --target flag.

  • VAULTSPEC_TARGET_DIR (path, default cwd) - Root workspace directory (where .vault/ and .vaultspec/ live). Equivalent to --target on the CLI. Also used by vaultspec-core-mcp to locate the workspace. Defaults to the current working directory if unset.

  • VAULTSPEC_DOCS_DIR (str, default .vault) - Vault directory name.

  • VAULTSPEC_INDEX_DIR (str, default index) - Name of the subdirectory inside the vault that holds the auto-generated feature indexes (<feature>.index.md).

  • VAULTSPEC_FRAMEWORK_DIR (str, default .vaultspec) - Framework directory name.

  • VAULTSPEC_CLAUDE_DIR (str, default .claude) - Claude tool directory name.

  • VAULTSPEC_GEMINI_DIR (str, default .gemini) - Gemini tool directory name.

  • VAULTSPEC_ANTIGRAVITY_DIR (str, default .agents) - Antigravity directory name.

  • VAULTSPEC_IO_BUFFER_SIZE (int, default 8192) - I/O read buffer size in bytes.

  • VAULTSPEC_TERMINAL_OUTPUT_LIMIT (int, default 1000000) - Subprocess stdout capture limit in bytes.

  • VAULTSPEC_LOCK_TIMEOUT_SECONDS (float, default 120.0) - Total seconds a single advisory-lock acquisition may wait before failing with a diagnosable timeout instead of blocking indefinitely. Covers the in-process and cross-process layers combined. Raise it if a large corpus or a slow network volume makes legitimate contention exceed the budget.

  • VAULTSPEC_LOCK_TIMEOUT_SECONDS (float, default 120.0) - Total seconds a single advisory-lock acquisition may wait before failing with a diagnosable timeout instead of blocking indefinitely. Covers the in-process and cross-process layers combined. Raise it if a large corpus or a slow network volume makes legitimate contention exceed the budget.

  • VAULTSPEC_LOG_LEVEL (str, default INFO) - Root log level for the CLI, for example DEBUG, INFO, or WARNING. Overridden by --debug when set.

  • VAULTSPEC_EDITOR (str, default zed -w) - Editor command for vaultspec-core spec {rules|skills|agents} edit. Overridden by the project-local config editor value, and the --editor flag. Resolved in order: --editor flag, project config, $VISUAL, $EDITOR/VAULTSPEC_EDITOR, vi. Unlike the flag and the config key, an editor named here is not restricted to the recognised set; see which editors are accepted.

  • VAULTSPEC_JSON_PRETTY (str, unset by default) - Indents --json output. Any value other than 0, false, no, off, or the empty string turns it on; without it the envelope is written as one compact line.

  • VAULTSPEC_NO_HINTS (str, unset by default) - Set to 1 to drop the Next actions block the commands print after their report. Equivalent to --no-hints. Only the exact value 1 counts; anything else leaves the hints in place.

  • VAULTSPEC_STDIO_WATCHDOG (str, default on) - Lifetime watchdog for the MCP server. Set it to 0, false, off, or no to disable it, which leaves the server to exit on stdin EOF alone. Read by vaultspec-core-mcp rather than by the CLI; see the MCP reference.

See alsoLink to See also

For bug reports and feature requests, open an issue on the vaultspec-core issue tracker.