View as Markdown

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 -P -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; -P keeps the working directory off sys.path). 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 discovered) - Target workspace directory. Overrides VAULTSPEC_TARGET_DIR. With neither set, the root is discovered from the working directory: the .gt/ container root, then the worktree root, then the repository root, and the working directory itself only when none of those is found.

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

  • --verbose (-v, default off) - Enable INFO-level logging (top-level flag). --debug outranks it when both are given.

  • --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

The block below compares this reference with the latest published release at the time it was generated: what it lists is documented here and absent from that release. It is computed from the surface recorded from that release’s published distribution, so it covers every affected command rather than the ones somebody remembered. The record is written after publication, from the release’s own distribution, through vaultspec-core spec reference snapshot --record, and never by hand. Run vaultspec-core spec reference generate to refresh the block; do not hand-edit between the markers.

Measured against 0.3.5, the latest published release when this reference was generated: 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

ProjectLink to Command index, Project

ReviewLink to Command index, Review

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) - Refresh everything install owns, idempotently: re-scaffolds any missing directory, runs pending migrations, re-infers the provisioning mode for a legacy workspace that declares none, syncs, and migrates the MCP launch shape.

  • --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.

  • --env NAME - Import a supported variable from the process environment. Repeatable. --env NAME=VALUE supplies a non-secret setting directly. Secret values on the command line are refused; import them by name or file.

  • --env-file PATH - Import supported names from a UTF-8 dotenv file (maximum 64 KiB). Explicit --env entries override file entries; the last repeated entry wins.

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

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

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

Exit codes: 0 success, 1 failure, 2 completed with a required step skipped. The three are shared by every vaultspec package’s install surface; core has no step that reports 2 today.

Local environment provisioningLink to install, Local environment provisioning

Usage synopsis

vaultspec-core install --env VAULTSPEC_CORE_TYPESAFE_API_KEY
vaultspec-core install --upgrade --env-file /private/vaultspec.env --env VAULTSPEC_NO_HINTS=1

The first command imports an already exported key without putting its value in shell history. Only supplied keys replace existing values. Installation, adoption, upgrade, --force, and sync preserve unmentioned settings; a failed install does not replace them. Existing installations still require --upgrade or --force. Dry runs report names and planned outcomes without writing. Outputs never show imported values.

Values already present in the process environment affect this invocation but are not saved to the project unless you import them explicitly. Core validates --env and --env-file before provisioning. After a real install or upgrade returns without errors, Core merges supplied values into .vaultspec/.env; a dry run reports outcomes without writing. An import does not change the current process environment or the target, provider, or launch mode already selected for this command; stored values are available to later Core commands. The final report can already reflect imported VAULTSPEC_JSON_PRETTY and VAULTSPEC_NO_HINTS settings.

Values are stored in .vaultspec/.env, outside the vault. The installer establishes mandatory ignore rules, refuses tracked or redirected storage paths, and writes atomically with owner-only permissions (a restricted DACL on Windows). Ignore protection remains required when managed-block maintenance is disabled. The commit gate rejects force-added local environment files. Full framework uninstall removes this local store. Protect the original import file separately; installation never rewrites it.

Supported imports are VAULTSPEC_CORE_TYPESAFE_API_KEY, VAULTSPEC_IO_BUFFER_SIZE, VAULTSPEC_TERMINAL_OUTPUT_LIMIT, VAULTSPEC_LOCK_TIMEOUT_SECONDS, VAULTSPEC_JSON_PRETTY, and VAULTSPEC_NO_HINTS. Other names are refused. Dotenv imports support comments, export, and single-line quoted or unquoted values, with no variable interpolation or shell evaluation. Double-quoted backslashes and quotes may be escaped.

For persistable settings, .vaultspec/.env is the third rung of the settings resolution order: after explicit command options and the process environment, before the trusted workspace-root .env credential fallback, persisted configuration, derived and external defaults, and shipped defaults. A blank value is unset in the store as everywhere else, and falls through. Both CLI and MCP use this resolver, scoped to the selected workspace; file and environment changes refresh its cache. Local settings work in all install modes, while the root .env fallback keeps the trust restrictions described under settings resolution. Provisioning does not copy secrets into generated MCP configuration or change the parent shell’s environment. A running MCP server keeps its inherited process environment until restarted, and that environment continues to override local file edits.

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.

Exit codes: 0 success, 1 failure, 2 completed with a required step skipped. The three are shared by every vaultspec package’s install surface; core has no step that reports 2 today.

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

commit-gateLink to Workspace commands, commit-gate

Usage synopsis

vaultspec-core commit-gate [OPTIONS] [PATHS]...

The read-only check the generated pre-commit hook runs. It checks each staged vault document with the checkers that judge a document on its own, and blocks only on errors the commit introduces: an error the document’s committed version already carries is printed as advisory and does not block. It also blocks staged per-machine files, such as the install manifest, snapshots, lock sentinels, and local vault caches, and every .env or .env.* file other than an .env.example template. It never writes, and it never runs the whole-vault checks; vaultspec-core vault check all remains the corpus-wide gate for CI and explicit runs.

ArgumentsLink to commit-gate, Arguments

  • PATHS (optional) - Files to check, relative to the workspace root. The hook passes the staged files; with none given, the staged files are read from git.

OptionsLink to commit-gate, Options

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

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

Exit codes: 0 = nothing blocks, 1 = something blocks.

ExamplesLink to commit-gate, Examples

  • Check what is staged right now, the way the commit hook will:

    Command

    vaultspec-core commit-gate

  • Check two documents explicitly and capture the result for a script:

    Command

    vaultspec-core commit-gate .vault/adr/2026-02-04-auth-adr.md .vault/plan/2026-02-04-auth-plan.md --json

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 discovered) - 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 discovered) - 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 discovered) - 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 discovered) - 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 discovered) - 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.

The rollup’s Discovery section says which vault search to reach for. First it says whether hosted vault search (vaultspec-core vault search) is configured and whether the key came from the environment, provisioned local_env, or workspace dotenv. It then shows whether the vaultspec-rag companion is provisioned, which decides the next step a declined vault search names. Both lines report configuration, not liveness: a configured key can still be rejected when a search runs, and a provisioned companion can still be down. Under --json they are data.hosted_search (configured, source) and data.companion (package, signal, mode, version, floor, health_authority; the key is absent when the probe failed).

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 the discovered workspace root).

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 the discovered workspace root).

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, repeatable; each is written as its own 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 discovered) - 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 the discovered workspace root).

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 adr crossrefLink to Vault commands, vaultspec-core vault adr crossref

Usage synopsis

vaultspec-core vault adr crossref [OPTIONS] [REFS]...

Find the ADRs a decision should cross-reference. Every other ADR is ranked locally; hosted judgments evaluate a bounded shortlist. The reply lists suggested links and declared links judged weak. With --apply, the new links are written into the source’s related: field. The same backend serves the MCP crossref tool.

The judgment runs in three stages, each with a fixed ceiling, so a run’s cost does not grow with the size of the vault:

  • Every other ADR is ranked by code alone: the code identifiers the two decisions share (module and file paths, CLI verbs, configuration variables) and the overlap between the source’s decision text and each candidate’s feature, title, and opening line. Nothing is sent.

  • The best 192 candidates are put to hosted search as Choice questions of at most 32 options each.

  • The best 32 of the combined ranking, plus up to 8 declared links outside them, are judged in pairs.

A source costs at most 46 requests under a 15-second deadline. A sweep takes at most 50 sources, or 52 when it must settle a refusal, and 300 seconds, and the vault may hold at most 5,000 ADRs.

Cross-referencing uses the hosted-search key in VAULTSPEC_CORE_TYPESAFE_API_KEY (see environment variables) and sends ADR text to the TypeSafe API. Without a key it sends nothing, reports that it is not configured, and names the search to run instead: the vaultspec-rag search when rag is provisioned, the ADR listing otherwise.

Output lists each source, then its verdicts. A link verdict means the source should link that ADR; it is marked new, declared, or written. A weak verdict is a link the source already declares, judged below the threshold. Weak links are listed for a reader to check and are never removed. Each verdict also carries an advisory relation: supersedes, refines, depends_on, conflicts, shared_artifact, topic_only, or unrelated. It tells an author which pairs to read in full; it does not decide anything.

ArgumentsLink to vaultspec-core vault adr crossref, Arguments

  • REFS - ADRs to cross-reference: a stem, filename, path, or [[wiki-link]]. One ADR is judged on its own; several make a sweep.

OptionsLink to vaultspec-core vault adr crossref, Options

  • --feature TAG (-f) - Sweep this feature’s ADRs.

  • --all (default off) - Sweep non-retired ADRs, including proposals. Superseded, rejected, and deprecated ADRs are skipped unless named.

  • --isolated (default off) - Sweep only ADRs that link no other ADR. Combines with --feature to narrow further; --all stands alone.

  • --after STEM - Resume a sweep after this ADR: the next_after a previous sweep reported, with the same selector. Sweeps run in stem order and store no state. An ADR the provider refuses to read is held open while the sweep judges on, past its source limit by up to two more ADRs if it must: a later ADR the provider reads shows the refusal was that ADR’s own, and the sweep moves past both. A refusal no read settles, three refusals in a row, or any other failure stops the sweep with stopped set and the cursor before the first refusal still open, so resuming retries from there.

  • --max-sources N (default 10) - Most ADRs one sweep judges, from 1 to 50.

  • --body-file PATH - Judge proposed body prose for one existing ADR without changing it. Use this for an amendment before replacing accepted text. Omit frontmatter; no sweep options or --apply may accompany it. The result marks the source as draft.

  • --apply (default off) - Write each new link verdict into the source’s related:, as each source finishes, without reading them first. Nothing is removed, and no candidate is written to. To add only the links you have read and confirmed, run without --apply and use vaultspec-core vault link add.

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

  • --target (-t) - Target directory (defaults to the discovered workspace root).

Under --json, data.sources holds one entry per source judged, with its status (ok, not_configured, or unavailable), its verdicts (stem, kind, score, relation, status, declared, and applied when written), and the counts links, written, and verdicts_total. A reply carries at most 80 verdict rows; a source whose rows were cut has truncated set. A source also carries unjudged_declared when some declared links were beyond the judged ceiling, write_failed for links --apply could not write, and, when it was not judged, its reason, next_step, and remediation. data also carries the totals judged, links, and written, the number of sources remaining, next_after when sources remain and one was processed (without it, a resume starts from the beginning), stopped when a sweep ended early, and usage when anything was sent.

Each judged source includes coverage: corpus, pool, and judged candidate counts, source_truncated, and candidates_truncated. Each returned candidate whose input was clipped has input_truncated. Decision and constraint sections receive space before context can consume the 6,000-character budget; other sections are retained within that bound. Read relevant full records when input was clipped. An ok response means the bounded judgment completed, not that every conflict was excluded.

Exit codes:

  • 0 - Every source taken was judged (envelope status unchanged, or updated when --apply wrote links), or hosted search is not configured (envelope status skipped).

  • 1 - A link --apply judged could not be written, or hosted search is configured but a source could not be judged (envelope status failed). The reply says where to resume.

  • 2 - Invalid input: no source or sweep option, a REFS entry or --after value that is not an ADR of this vault, REFS combined with --feature, --isolated, or --all, --all combined with --feature or --isolated, an empty --feature, a vault with more than 5,000 ADRs, or --max-sources outside 1..50.

ExamplesLink to vaultspec-core vault adr crossref, Examples

  • Check a newly drafted ADR before presenting it:

    Command

    vaultspec-core vault adr crossref 2026-05-26-new-adr-stem

  • Review the ADRs that link nothing yet, ten at a time:

    Command

    vaultspec-core vault adr crossref --isolated
vaultspec-core vault adr crossref --isolated --after 2026-05-17-last-judged-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 the discovered workspace root).

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, or a row for an unknown Step, is a warning; a row for a still-open Step is info (work in flight); 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. Warn about legacy declarations even alongside a canonical H1, and mismatches between superseded status and successor metadata. Repairs only quote a known token; missing or conflicting authority requires inspection.

  • 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 discovered) - 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, VAULTSPEC_EDITOR, 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 discovered) - 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 discovered) - 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 trust [PROVIDER] (--scope SCOPE, --target PATH, --source-from-cwd, --revoke) - Approve exact MCP commands after review and confirmation at an interactive terminal. --source-from-cwd approves definitions from the current working directory for a top-level vaultspec-core sync invocation with a --target destination. --revoke withdraws existing grants; uninstall removes deployed entries.

  • 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 - not a draft, not a prerelease. 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.

  • --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.

  • --record FILE - Write a surface document (from --emit, run inside the latest published release’s distribution) as the committed record; requires --development.

  • --development (default off) - Explicitly authorize recording from a trusted development invocation. MCP callers cannot authorize reference maintenance.

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

The record is never captured from a source tree. After publication, the release’s own distribution is installed in isolation and read back with --emit, and --record writes that document; a malformed document is refused and the record left untouched. --verify proves the committed record is what that distribution exposes. Without a mode flag the verb only reports the recorded version and counts. The three modes are mutually exclusive.

  • Report what the committed record holds:

    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

  • Record that surface as the committed record:

    Command

    vaultspec-core spec reference snapshot --record surface.json --development

  • Prove the committed record matches a published distribution:

    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 discovered) - 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 discovered) - 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

Project coordinationLink to Project coordination

vaultspec-core project contextLink to Project coordination, vaultspec-core project context

Usage synopsis

vaultspec-core project context [OPTIONS] OBJECTIVE

Collect recent Git activity, branches, worktrees, and optional GitHub issues and PRs to propose a bounded attention order for the developer’s objective. The command reads project state without changing repositories or trackers. Missing sources are reported as incomplete coverage. A configured TypeSafe key enables optional ranking; without a key, with --no-hosted, or after a service failure, deterministic ordering is used.

ArgumentsLink to vaultspec-core project context, Arguments

  • OBJECTIVE - The developer outcome to prioritize.

OptionsLink to vaultspec-core project context, Options

  • --repo OWNER/REPO - Read issues and PRs from this GitHub repository using gh.

  • --previous FILE - Reuse unchanged judgments from a previous JSON result for up to one hour. Input is limited to 64,000 bytes.

  • --limit INTEGER (default 5, range 1..10) - Maximum attention items returned.

  • --no-hosted - Disable hosted ranking even when a key is configured.

  • --target DIR (-t, default cwd) - Project directory to inspect.

  • --json - Emit structured observations, coverage, ordering, and available usage.

ExamplesLink to vaultspec-core project context, Examples

Command

vaultspec-core project context "Finish the release and unblock active PRs" --no-hosted
vaultspec-core project context "Prioritize today's work" --repo owner/project --json

Review contextLink to Review context

vaultspec-core review contextLink to Review context, vaultspec-core review context

Command

vaultspec-core review context "Preserve caller contracts" --base main --candidate src/caller.py:20-70 --candidate tests/test_service.py:1-80 --json

Select supporting passages from an explicit Git review scope. This command reads repository state without running checks or producing a review verdict. A configured VAULTSPEC_CORE_TYPESAFE_API_KEY opts into sending the objective, bounded diff and candidate passages to TypeSafe. Missing credentials, rejected keys, timeouts and service failures preserve the supplied discovery order.

Arguments and optionsLink to vaultspec-core review context, Arguments and options

  • OBJECTIVE - Review behavior or constraint, 1..1,000 UTF-8 bytes.

  • --base REF - Required base commit reference.

  • --candidate PATH[:START-END] - Required tracked, repository-relative locator; repeat for 1..12 passages. A single line can use PATH:LINE.

  • --head REF - Read the target commit and its candidate content. Without this flag, read tracked working-tree changes, including staged changes. Untracked files are excluded and working-tree reads are not atomic.

  • --limit INTEGER - Return up to this many passages; default 3, range 1..6.

  • --previous FILE - Reuse identical-input judgments from a JSON result up to 128,000 bytes for at most one hour. A key must remain enrolled. Status reused does not claim current service connectivity.

  • --no-hosted - Disable hosted selection even with a configured key.

  • --target DIR (-t, default cwd) - Git repository root.

  • --json - Return the vaultspec.review.context.v1 envelope.

Each candidate is at most 120 lines and 4,000 UTF-8 bytes from a file up to 1 MB. Larger passages need narrower locators. Collection has a shared 10-second budget; hosted selection makes one batch with a 15-second budget. A diff exceeding 24,000 bytes or involving environment/private-key paths disables hosted selection. Candidate environment stores, conventional key files, symlinks and paths outside the repository are excluded. These path protections are not general secret scanning.

The result carries verbatim selected passages and hashes, unselected locators, exclusions, diff scope, hosted status, usage and a reusable judgment. Source text is not rewritten by the model. Candidate exclusions and hosted failure exit 0 with reasons; invalid input or an unavailable Git scope exits 2. The existing MCP discover/invoke gateway exposes the same command; repeatable candidate flags accept a JSON array.

Keep the full diff and governing decisions in the review. Expand omitted context when needed, share selections across reviewers, and reuse applicable verification results. Ranking is optional supporting evidence, not proof of correctness or complete coverage.

Settings resolutionLink to Settings resolution

One order holds for every setting, in every process kind (CLI, MCP server, and any package that imports vaultspec-core’s public resolvers). Earlier rungs win:

  1. Invocation - a CLI flag or an explicit programmatic override for that call.

  2. Session environment - the process’s own environment. For a setting the framework shares, a companion package’s scoped name is read first - VAULTSPEC_<PKG>_ROOT, VAULTSPEC_<PKG>_LOG_LEVEL, VAULTSPEC_<PKG>_STDIO_WATCHDOG

    • and falls back to the framework name behind it - VAULTSPEC_TARGET_DIR, VAULTSPEC_LOG_LEVEL, VAULTSPEC_STDIO_WATCHDOG - when it supplies nothing. A credential never chains.

  3. Project store - .vaultspec/.env, for the persistable settings only, written only by an explicit import; see local environment provisioning.

  4. Workspace .env - credentials only, under the gate below.

  5. Persisted configuration - the single store that owns the key: .vaultspec/config.toml or .vaultspec/workspace.json.

  6. Derived and external defaults - pyproject.toml mode detection, or a third-party convention with a product equivalent, such as VISUAL then EDITOR.

  7. The shipped default, declared once in the table below.

The workspace .env is <workspace root>/.env. It is never found by walking up from the working directory or from where the package is installed, and no variant (.env.local and the like) is read. It supplies a credential - today only VAULTSPEC_CORE_TYPESAFE_API_KEY - one name at a time, and only when both hold: the running interpreter lives inside the workspace (its project virtual environment), and the owning package’s own resolved install mode for that workspace is dependency or dev. A uvx invocation or a globally installed tool (such as a uv tool, a pipx install, or a release binary) pointed at a fresh clone never reads that repository’s .env.

No .env file is ever committed, this one or any other: dotenv files hold secrets. The managed .gitignore block ignores every .env and .env.* file at any depth, leaving only .env.example templates committable; the commit gate refuses one that is force-added; and vaultspec-core doctor warns when the Git index already tracks one. An ignore rule cannot untrack a file, so a tracked .env needs git rm --cached and every secret it held rotated.

Booleans read one vocabulary: 1, true, yes or on against 0, false, no or off, case-folded and stripped. A blank value is unset, not off, and falls through to the next rung. An invalid value for a product-owned variable refuses the process and names the variable, the value and the expected shape. The stdio watchdog is the one protective switch that instead warns and stays armed: refusing to start is not a safer outcome than running guarded.

Environment variablesLink to Environment variables

vaultspec-core owns the VAULTSPEC_ variables below and honours a few external conventions, listed after them. Environment variables override the default and are overridden by the invocation.

  • VAULTSPEC_TARGET_DIR (path, default discovered) - Root workspace directory (where .vault/ and .vaultspec/ live), for every process kind: the CLI, the MCP server, and any importing package. Equivalent to --target on the CLI. Ranked below an explicit --target and above discovery from the working directory; a directory that does not exist is refused rather than discovered past.

  • 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_EDITOR (str, unset by default) - Editor command every surface that opens an editor consults - the edit verbs (vaultspec-core spec {rules|skills|agents} edit) and interactive creation of a rule, skill, agent, or trigger alike. Read after the --editor flag and before the project config key, VISUAL and EDITOR; vi is the last rung when none of them answers. Unlike the flag and the config key, an editor named in the environment is not restricted to the recognised set; see which editors are accepted.

  • VAULTSPEC_CORE_TYPESAFE_API_KEY (secret, unset by default) - TypeSafe API key for hosted vault search (vaultspec-core vault search and the MCP search tool), ADR wording checks, and optional project and review context ranking. Read from the process environment, then the provisioned .vaultspec/.env project store. A workspace-root .env supplies it only when both omit it, and then only under the credential gate above. Only this one variable is read from that file. Blank counts as unset at every source. The generic TYPESAFE_API_KEY does not enable it. The key never appears in output; vaultspec-core status reports only whether one is configured and from which source.

  • VAULTSPEC_LOG_LEVEL (str, default WARNING for the CLI, INFO for the MCP server)

    • Root log level when neither --debug nor --verbose is given, for example DEBUG, INFO, or WARNING. An unknown name is refused.

  • VAULTSPEC_JSON_PRETTY (bool, unset by default) - Indents --json output. A true word turns it on; unset, blank or a false word leaves the envelope one compact line.

  • VAULTSPEC_NO_HINTS (bool, unset by default) - Set to a true word to drop the Next actions block the commands print after their report. Equivalent to --no-hints. Unset, blank or a false word leaves the hints in place.

  • VAULTSPEC_NON_INTERACTIVE (bool, unset by default) - Set to a true word to declare that no operator is watching: repository triggers awaiting approval are skipped instead of prompted for. Outranks CI in both directions, so a wrapper script running under CI with somebody watching can say so with VAULTSPEC_NON_INTERACTIVE=0.

  • VAULTSPEC_STDIO_WATCHDOG (bool, unset by default; armed) - Lifetime watchdog for the MCP server, on by default. A false word disables it, which leaves the server to exit on stdin EOF alone. Unset, blank, or an unrecognised word leaves it armed: it is a protective switch, so a typo warns rather than turning the guard off. Read by vaultspec-core-mcp rather than by the CLI; see the MCP reference.

  • VAULTSPEC_MCP_GATEWAY_INVOCATION (str, unset by default) - Internal, set by vaultspec-core itself: the MCP invoke gateway sets it on every CLI process it spawns. Any non-empty value marks the process as having no terminal, so it refuses to open an editor. Not an operator setting.

vaultspec-core also honours these external variables. It does not own them.

  • CI (presence) - Set by CI systems. Same effect as VAULTSPEC_NON_INTERACTIVE.

  • NO_COLOR (non-empty string) - Set to any non-empty value to disable colour in console output, as the no-color.org convention defines it. Set but empty is not a request for monochrome output.

  • GIT_INDEX_FILE (presence) - Set by git for every commit hook it runs. While it is set, commands print no Next actions block and no --fix suggestion for a finding, because hook output is often acted on without review.

  • COLUMNS (int) - Console width. When unset, the width is read from the terminal once at startup.

  • VISUAL, EDITOR (str) - Editor commands the edit verbs consult after VAULTSPEC_EDITOR and the project config key, in that order.

  • CLAUDE_CONFIG_DIR (path, default home directory) - Claude Code’s configuration home, whose .claude.json holds user-scope MCP servers.

  • CODEX_HOME (path, default ~/.codex) - Codex’s home, whose config.toml holds user-scope MCP servers.

See alsoLink to See also

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