Skip to content

cli.md

Latest commit

 

History

History
188 lines (116 loc) · 3.81 KB

cli.md

File metadata and controls

188 lines (116 loc) · 3.81 KB

CLI Reference

The vault CLI provides 15 commands for managing governed knowledge stores.

pip install qp-vault[cli]

Error messages display structured vault error codes (e.g., [VAULT_300] Invalid lifecycle transition) without exposing internal paths, SQL, or stack traces.

Commands

vault init

vault init <path>

Initialize a new vault. Creates SQLite database and audit log.

vault add

vault add <file> [--trust T] [--layer L] [--tags t1,t2] [--name N] [--path P]
Option Short Default Description
--trust -t working Trust tier: canonical, working, ephemeral, archived
--layer -l (none) Memory layer: operational, strategic, compliance
--tags (none) Comma-separated tags
--name -n (auto) Display name
--path -p . Vault directory

vault search

vault search <query> [--top-k N] [--path P]

Trust-weighted hybrid search with Rich table output.

vault list

vault list [--trust T] [--layer L] [--tenant ID] [--limit N] [--path P]

List resources with optional filters. Shows trust tier, name, status, and ID.

vault inspect

vault inspect <resource-id> [--path P]

Show detailed metadata: CID, content hash, trust tier, status, lifecycle, chunks, size, timestamps.

vault status

vault status [--path P]

Vault summary: total resources, breakdown by trust tier, status, and layer.

vault verify

vault verify [resource-id] [--path P]

Without resource-id: verify entire vault (Merkle root). With resource-id: verify single resource (SHA3-256 hash check). Exit code 1 on failure.

vault health

vault health [--path P]

Composite health score (0-100): freshness, uniqueness, coherence, connectivity, issues.

vault delete

vault delete <resource-id> [--hard] [--path P]

Soft delete (default) or permanent hard delete.

vault transition

vault transition <resource-id> <target> [--reason R] [--path P]

Change lifecycle state. Valid targets depend on current state (see Lifecycle).

vault expiring

vault expiring [--days N] [--path P]

Show resources expiring within N days (default: 90).

vault content

vault content <resource-id> [--path P]

Retrieve and display the full text content of a resource.

vault replace

vault replace <resource-id> <file-or-text> [--path P]

Replace content atomically. Creates new version, supersedes old. Shows old ID (SUPERSEDED) and new ID.

vault supersede

vault supersede <old-id> <new-id> [--path P]

Link two resources: old becomes SUPERSEDED, new gets supersedes pointer.

vault collections

vault collections [--path P]

List all named collections.

vault provenance

vault provenance <resource-id> [--path P]

Show provenance records: upload timestamp, uploader, method.

vault export

vault export <output-file> [--path P]

Export vault to JSON file. Shows resource count.

Global Options

All commands accept --path / -p to specify the vault directory.

Exit Codes

  • 0: Success
  • 1: Failure (verification failed, resource not found, invalid transition)

Designed for CI: vault verify && deploy.