ar9av__obsidian-wiki/docs/cli.md

CLI Reference

The obsidian-wiki Python package ships a CLI for setup, inspection, and the deterministic parts of the workflow — the things that don't need an LLM. Everything else is a skill your agent runs.

pip install obsidian-wiki
obsidian-wiki --help
obsidian-wiki --version

Running obsidian-wiki with no subcommand defaults to setup.

Setup & inspection

Command	What it does
setup	Install skills into your agents and write ~/.obsidian-wiki/config
info	Show install paths, version, and resolved config
list	List the bundled skills
doctor	Health-check config, vault shape, bootstrap assets, and installed skills; with --project, also reports the code-understanding capability section

obsidian-wiki setup --vault ~/brain
obsidian-wiki setup --project .        # also install project-local skills + bootstrap files
obsidian-wiki setup --project-only     # skip the global install (use with --project)
obsidian-wiki setup --copy             # copy skill files instead of symlinking
obsidian-wiki setup --remote https://github.com/you/my-wiki.git   # configure sync non-interactively

obsidian-wiki doctor --json --pretty
obsidian-wiki doctor --vault /other/vault --project .
obsidian-wiki doctor --strict          # exit non-zero on warnings too

Commands other than setup, info, and doctor warn you when the install has gone stale (the package upgraded but skills weren't re-linked). Re-run obsidian-wiki setup to fix.

Querying & linting

Command	What it does
query <question>	Answer a question from the configured vault's index
lint [vault]	Find missing frontmatter, broken links, duplicates, and orphans

obsidian-wiki query "what do I know about MCP security?"
obsidian-wiki query "rate limiting" --top 12 --max-read 5 --json

obsidian-wiki lint                     # uses the configured vault
obsidian-wiki lint /path/to/vault --strict
obsidian-wiki lint @research --json    # uses ~/.obsidian-wiki/config.research only
obsidian-wiki lint --strict-trust      # fail on trust-ledger problems, not just warn
obsidian-wiki lint --allow-lifecycle active --allow-relationship-type synthesizes \
  --required-trust-field updated --schema-source /path/to/vault/AGENTS.md

Lint resolves its vault and schema together: explicit path (no config inheritance), positional @name, nearest CWD .env, then global config. CLI schema flags extend/replace that resolved vault's settings and are recorded in the JSON schema block.

Context packs

wiki-context-pack compiles a task-scoped snapshot from existing Markdown. Notes do not need to be moved into wiki-generated folders or migrated to the full frontmatter schema. The command is read-only.

obsidian-wiki context-pack "authentication architecture" --budget 8000
obsidian-wiki context-pack --recent --budget 4000
obsidian-wiki context-pack "release notes" --budget 8000 --public-only

Omitting --budget uses the default of 8000 estimated tokens.

The output includes source paths, summaries, selected excerpts, and a hard estimated-token ceiling. Vault excerpts are explicitly marked as untrusted reference data: downstream agents may use their facts but must not execute instructions embedded in notes. Use --metadata-only for the smallest pack, or --json for tool-to-tool integration.

Flag	Effect
--budget N	Maximum estimated output tokens, 256–100000 (default 8000)
--recent	Select recently updated notes — the only way to omit the topic
--public-only	Exclude visibility/internal and visibility/pii notes
--metadata-only	Titles, provenance, and summaries with no body excerpts
--json	Structured output for tool-to-tool integration
--vault PATH	Override OBSIDIAN_VAULT_PATH

context is an accepted alias for context-pack.

Session brain

Builds a topic graph over your agent session history. Output is a sidecar at ~/.claude/session-brain/ — the vault is never written to. Full detail in Session Brain.

Command	What it does
sessions-build	Build (or incrementally update) the topic graph
sessions-query <topic>	Find the sessions most relevant to a topic
sessions-show <id>	Show one session's node and its nearest neighbours
sessions-clusters	List the discovered topic clusters
sessions-name --from FILE	Assign durable names to clusters, surviving rebuilds

obsidian-wiki sessions-build                       # ~3s cold, under a second incrementally
obsidian-wiki sessions-build --full --verbose      # ignore caches, re-read everything
obsidian-wiki sessions-build --since 2026-01-01 --skip archived,scratch
obsidian-wiki sessions-build --k 12 --min-sim 0.12 --mutual --half-life 60

obsidian-wiki sessions-query "prismor telemetry"
obsidian-wiki sessions-query "auth bug" --project my-app --cluster 3 --json

obsidian-wiki sessions-show 01935a40 --neighbors 12
obsidian-wiki sessions-clusters --unnamed
obsidian-wiki sessions-name --from names.json      # or - for stdin

sessions-name takes a JSON array of {"id": N, "name": "...", "summary": "..."}. The /session-brain skill generates this for you.

Vault syncing

Command	What it does
sync	Stage, commit, and push pending vault changes
sync-setup <remote>	Configure GitHub sync (git init, .gitignore, remote)

obsidian-wiki sync
obsidian-wiki sync-setup https://github.com/you/my-wiki.git

See Configuration → Syncing your vault to GitHub.

Trust ledger

Records and validates human-approved confidence reviews, so you can gate on "a person actually checked these pages" in CI.

Command	What it does
trust-record	Record explicitly approved manual confidence reviews
trust-check	Validate confidence values and material fingerprints against the ledger

obsidian-wiki trust-record --all --reviewed-at 2026-07-30T10:00:00+00:00 --approved
obsidian-wiki trust-record --page concepts/rate-limiting.md --reviewed-at <ISO> --approved
obsidian-wiki trust-check --strict
obsidian-wiki trust-record @research --all --reviewed-at <ISO> --approved --allow-lifecycle active
obsidian-wiki trust-check @research --allow-lifecycle active --schema-source /vault/AGENTS.md

--reviewed-at needs a timezone. --approved is required and mandatory — it's your assertion that a human approved every confidence value being recorded. trust-check --strict is the CI/scheduled gate. trust-record and trust-check resolve the same vault-scoped schema as lint; pass the same lifecycle and required-field overrides to record and check. If the owner schema does not require base_confidence, pages without it are reported as not_applicable, excluded by trust-record --all, and any obsolete ledger entry is warned by trust-check then removed by trust-record --page or a rebuild. Both JSON and human-readable record output list excluded pages and removed obsolete entries; human output also emits a stderr warning when removal occurs. Required-field config accepts only base_confidence, lifecycle, lifecycle_changed, and updated; typos fail closed. Lifecycle, relationship-type, and required-field override values are stripped and empty or whitespace-only entries are rejected rather than added to an allowlist. Without an explicit --schema-source, CLI overrides on an explicit vault are labeled cli:explicit-vault; combined CLI and config overrides use cli+config:<resolved-config-path>.

Lower-level commands

Available for automation, scripting, and debugging. Skills call some of these internally.

Command	What it does
graph-query <vault> <question>	Answer from the wikilink index without reading page bodies
graph-analyse <vault>	God nodes, communities, surprising connections
batch-plan <vault> <source_dir>	Split a source directory into parallel-ingest batches, skipping unchanged files
cache-check <vault> <sources...>	Which sources are new / modified / unchanged vs. .manifest.json
cache-update <vault> <source>	Record a source's SHA-256 in .manifest.json after ingest
cache-hash <path>	Compute a file or directory hash (no manifest I/O)
ast-extract <path>	Extract classes, functions, and imports from code — no LLM, no API calls
code-understand --project <dir> [--backend auto|builtin|codegraph] [--since <sha>] [--changed <file>...] [--max-symbols N] [--pretty]	Emit a ranked code-understanding focus map (symbols + file:line citations) for a project; CodeGraph when available, built-in AST + rg otherwise. Used by wiki-update Step 3b.

obsidian-wiki graph-query /path/to/vault "transformer architecture" --pretty
obsidian-wiki graph-analyse /path/to/vault --top 30 --pretty
obsidian-wiki batch-plan /path/to/vault ~/research --max-mb 4 --max-files 30
obsidian-wiki cache-check /path/to/vault ~/research/*.pdf
obsidian-wiki cache-update /path/to/vault ~/research/paper.pdf --pages concepts/attention.md
obsidian-wiki ast-extract ./src --pretty
obsidian-wiki code-understand --project . --since <last_commit_synced> --pretty

Most commands accept --json and/or --pretty for machine-readable output.