CLI reference
title: "CLI reference" type: navigation docs_shell: true
CLI reference
Every python3 -m llmwiki <subcommand> — with every flag, realistic examples, and expected output. If a command isn't listed here it isn't shipping. This page is generated against the live argparse tree, so adding a flag without documenting it will fail the guardrail test.
Global flags: -h / --help on every command, --version at the root.
llmwiki --help groups commands into six lifecycle sections (same labels and order as the table below). Canonical loop: ingest (sync / add) → summarise (synth) → review candidates → publish (build). synth does not rebuild the site; run build afterwards when Home / Analytics should refresh.
Top-level
python3 -m llmwiki --version # → llmwiki <version>
python3 -m llmwiki --help # lifecycle map of every subcommand
python3 -m llmwiki # same as --help
| Group | Commands |
|---|---|
| Start here | init · configure-sources · install-agent-kit |
| Daily loop (this order) | sync · add · synth · candidates · build |
| Run the loop for me | all · watch · install-automation |
| Look around | lint · search · query · trace · graph · adapters · usage · version |
| Take things out | remove |
| Rare — one-time | migrate · queue |
The shorter alias llmwiki works too once the package is installed (pip install llm-wiki-plus — see deploy/pypi-publishing.md).
TAB completion of these command names in bash and zsh is one line in your shell startup file, which ./setup.sh offers to add — see Shell completion.
init — scaffold raw/ / wiki/ / site/
Creates the three data directories + seeds nine navigation files inside wiki/.
python3 -m llmwiki init
Flags: none.
Expected output:
raw/sessions/
wiki/sources/
wiki/entities/
wiki/concepts/
wiki/syntheses/
site/
seeded wiki/dashboard.md
seeded wiki/index.md
...
Idempotent. Safe to re-run — it never overwrites files that exist.
sync — convert .jsonl sessions to markdown
The workhorse. Walks every configured adapter, converts new sessions into raw/sessions/, reconciles wiki/index.md against pages on disk, then (by default) auto-builds and auto-lints.
python3 -m llmwiki sync
python3 -m llmwiki sync --since 2026-04-01 --project llm-wiki
python3 -m llmwiki sync --adapter claude_code codex_cli
python3 -m llmwiki sync --no-auto-build --no-auto-lint
python3 -m llmwiki sync --vault "~/Documents/Obsidian Vault"
python3 -m llmwiki sync --vault ~/my-vault --allow-overwrite
python3 -m llmwiki sync --force
Flags
| Flag | What |
|---|---|
--adapter NAME [NAME ...] |
Limit to / load specific adapters. Default: every ingest-ready coding-agent source with a present store and no enabled: false. Notes intake still needs enabled: true. See multi-agent-setup.md. |
--since YYYY-MM-DD |
Only sessions on/after this date (e.g. --since 2026-04-01). Overrides durable filters.since / adapters.*.since for every source this run. Absent CLI flag: use config lookback, or unlimited if unset. See configuration-reference.md — Sync lookback. |
--project SUBSTRING |
Filter by project-slug substring. |
--include-current |
Include sessions < 60 min old (default skips live ones). |
--force |
Ignore the mtime state file, reconvert everything. |
--auto-build / --no-auto-build |
Rebuild site/ after sync (default: on). |
--auto-lint / --no-auto-lint |
Run lint after sync (default: on). |
--vault PATH |
Vault-overlay mode — write new pages inside the given Obsidian / Logseq vault instead of wiki/. See guides/existing-vault.md. |
--allow-overwrite |
With --vault: allow clobbering existing vault pages (default: refuse, append under ## Connections instead). |
--status |
Show last-sync time + per-adapter counters + quarantine (does not run a sync). |
--recent N |
With --status: also show last N sync/synthesize log entries. |
Note: There is no
sync --dry-run. Usesync --statusfor observability oradd --dry-runfor document-intake previews. State lives inllmwiki-state.json(configured once at CLI entry via--vault/vault.default_path).
Expected output (typical)
==> claude_code: 3 new sessions since last sync
✓ wrote 3 pages under raw/sessions/
✓ ingested into wiki/sources/ (2 new entities, 1 new concept)
✓ auto-build: site/ rebuilt (690 HTML files)
✓ auto-lint: 28 issues: 0 errors, 22 warnings, 6 info
Common recipes
- Nightly cron-style sync of one project only:
llmwiki sync --project my-project --no-auto-lint --since $(date -v-1d +%Y-%m-%d) - Vault-overlay round-trip:
llmwiki sync --vault "~/Documents/Obsidian Vault"
add — add a document to the wiki (#16 / #273)
Converts a URL, file, folder, or stdin in the process locale encoding (-) into raw Markdown under raw/docs/, then (by default) rebuilds the site so the new material is visible on Raw / Home. Does not synthesize wiki/sources/ unless you pass --synthesize. Path and URL sources may be freely mixed and repeated; - (stdin) must be the only source in that invocation. MCP wiki_add is a thin proxy onto the same shared run_add path — see mcp.md.
python3 -m llmwiki add https://example.com/some-article
python3 -m llmwiki add ./notes.pdf ./research-folder/
python3 -m llmwiki add https://example.com/post --title "Custom Title" --tag research
python3 -m llmwiki add ./doc.md --project my-project --note "Imported from Slack"
python3 -m llmwiki add https://example.com/post --dry-run
python3 -m llmwiki add ./doc.md --synthesize # opt in to wiki/sources for this run
cat notes.md | python3 -m llmwiki add - --title "Piped notes"
Default outcome: raw file(s) written, synth-pending refreshed, site rebuilt. No new wiki/sources/ pages from that add. Pass --synthesize to run synthesis on only the docs this add wrote (same rollback rules as before). Pass --no-build to skip the site rebuild. --no-synthesize is a deprecated warn+no-op alias (synthesis is already off by default) so old scripts keep working for one release.
Stdin (add -) and MCP content use the piped-text conversion path: frontmatter source: "piped" (never a /tmp/… provenance). Prefer --title for stdin; otherwise title derives from the first heading / body start.
Source-layer guardrail: pass the user's exact path, URL, or text. Do not reconstruct input from wiki/sources/ or other derived pages unless the user asked.
Flags
| Flag | What |
|---|---|
SOURCE |
URL (http/https), file, folder, or - for stdin in the process locale encoding. Repeatable except - (cannot mix with other sources). |
--title TEXT |
Override title derivation (single source only). |
--project NAME |
Group under raw/docs/<NAME>/ instead of the doc's own slug. |
--tag TAG |
Extra frontmatter tag (repeatable). |
--note TEXT |
Blockquote note prepended to the document body. |
--synthesize |
Opt in to synthesize wiki/sources/ for the docs this add wrote (off by default). |
--no-synthesize |
Deprecated warn+no-op; synthesis is already off by default (#273). |
--no-build |
Skip the post-add site rebuild. |
--render |
Force the headless-browser layer for URLs (needs playwright). |
--no-render |
Never use the headless-browser layer. |
--dry-run |
Convert and report, write nothing, run nothing. |
--force-new |
Always land a new snapshot even when the converted body matches an existing doc (#22). |
--vault PATH |
Write under the given vault's raw/docs/ instead of the repo. |
URL sources go through a layered pipeline (markdown negotiation → extraction → render escalation) before landing as Markdown.
remove — cascade-remove a raw doc and everything derived (#B2)
Selects raw docs under the resolved vault's raw/docs/ by a project name or slug glob, then removes them together with every artifact derived from them — the synth.files state keys and the wiki/sources/ pages (part-pages included) — so a naive delete can never leave orphan pages or dangling state behind. After deletion it prunes backlinks, rebuilds wiki/index.md, and appends a remove entry to wiki/log.md.
python3 -m llmwiki remove old-project --dry-run # preview the full cascade
python3 -m llmwiki remove 'old-project*' --yes # slug glob, no prompt
python3 -m llmwiki remove taxes --vault ~/my-vault --yes
Positional
| Value | What |
|---|---|
SELECTOR |
Project name or slug glob (e.g. old-project*) matched against raw/docs/. |
Flags
| Flag | What |
|---|---|
--dry-run |
Print the full cascade (every raw file, state key, and wiki page) and change nothing. |
--yes |
Skip the confirmation prompt. Required when stdin is not a TTY — cascade deletion is never silent. |
--vault PATH |
Cascade against the given vault instead of the repo's own directories. |
A selector that matches nothing is a clean no-op with a message. Without --dry-run and without --yes, the command prints the cascade and asks for confirmation on a TTY, or refuses (exit 2) when there is none.
build — compile the static HTML site
Turns wiki/ markdown into site/ HTML. Also writes AI-consumable exports (llms.txt, llms-full.txt, sitemap.xml, rss.xml, robots.txt, graph.jsonld, ai-readme.md) into the output directory — there is no separate export subcommand.
python3 -m llmwiki build
python3 -m llmwiki build --out ~/public_html
python3 -m llmwiki build --search-mode tree
python3 -m llmwiki build --synthesize --claude /usr/local/bin/claude
python3 -m llmwiki build --vault ~/my-vault --out ~/site
python3 -m llmwiki build --vault demo --out ./site --local-root /home/user
Flags
| Flag | What |
|---|---|
--out PATH |
Output directory. Default: ./site/. |
--synthesize |
Call the claude CLI for overview synthesis (experimental). |
--claude PATH |
Path to the claude binary. Default: /usr/local/bin/claude. |
--search-mode {auto,tree,flat} |
Search routing mode (#53). auto picks tree vs flat from heading depth; tree / flat force the mode. Default: auto. |
--vault PATH |
Vault-overlay mode — build from an existing Obsidian / Logseq vault. Output still lands at --out. |
--local-root PATH |
Value shown in place of a session's stored home directory (#109). Default: this machine's home directory, so local paths stay usable. Pass a fixed string when publishing so the same vault renders identically anywhere. Substitution applies to the cwd field only. |
--seed-project-stubs |
Create a wiki/projects/<slug>.md stub for any project without one (#414). Off by default — build is read-only on wiki/. |
Expected output (final lines)
wrote search-index.json (7 KB meta) + 30 chunks (904 KB total) · tree mode · 64% deep pages
wrote 7 AI-consumable exports: ai-readme.md, graph.jsonld, llms-full.txt, llms.txt, robots.txt, rss.xml, sitemap.xml
wrote site/graph.html (interactive graph viewer)
wrote site/prototypes/index.html (6 prototype states)
wrote site/docs/ (94 editorial pages: hub + tutorials + style guide)
==> build complete: 703 HTML files, 61 MB
usage — MCP tool-usage telemetry vs synthesis cost (#26)
python3 -m llmwiki usage # human-readable report
python3 -m llmwiki usage --json # machine-readable totals
python3 -m llmwiki usage --compact # roll past months into rollup.json first
Folds the local MCP telemetry logs into totals and prints them next to the synthesis cost persisted in state — so the "is this wiki earning its synthesis spend?" question is answerable at a glance.
The live MCP surface is six tools (wiki_search, wiki_read_page, wiki_health, wiki_sync, wiki_export, wiki_add); see mcp.md for parameters and migration from retired tool names (#196).
The MCP server logs one JSON record per tool call to a per-process file under <vault>/usage/ (mcp-<pid>-<start>.jsonl), merged at read time. Several server processes run at once (one per editor session), so per-process files mean zero write contention and no lock on the hot path; telemetry never touches llmwiki-state.json. Each record carries tool, query, hits (0 = a knowledge gap or noise; null = the tool can't report a count), resp_bytes, duration_ms, caller_project, caller_source, server_pid, server_started. Writes are best-effort — a telemetry failure never breaks a tool call. Opt out with LLMWIKI_MCP_TELEMETRY=0.
Caller attribution. caller_project is resolved per call and caller_source says where it came from:
caller_source |
Meaning |
|---|---|
project-dir-env |
The workspace path a client auto-injects into the server's environment. Claude Code sets CLAUDE_PROJECT_DIR (≥ v2.1.139) into every stdio MCP server — zero config — and spawns one server per session, so it is a stable per-caller signal available at the first call. |
client-root |
The client's own workspace directory, obtained via an MCP roots/list request. Attributed to the first root when a client reports several. |
path |
A path argument carrying the caller's working directory encoded into one segment (…/-home-dev-code-my-app/…), used for clients that offer neither of the above. |
unattributed |
No caller-scoped signal — caller_project is unknown. |
They are tried in that order. All three project sources feed one shared slugs.project_slug_from_abs_path, so a project resolves to the same slug whether it arrived through telemetry or through session ingestion (and thus keys onto its own project page).
Client coverage. Claude Code attributes every call with no setup, via CLAUDE_PROJECT_DIR. Cursor currently provides no zero-config signal — it advertises the roots capability but returns Method not found on the actual roots/list call, and injects no workspace env var — so its calls fall to the path heuristic where a path argument is present, else unknown, until it ships a fix. The server's own os.getcwd() is never used: a client may launch the server anywhere (Claude Code's desktop app uses $HOME), so it is unrelated to the caller's project.
Unattributed calls are counted in the totals but never presented as a project: they print as (unattributed) here and are excluded from the site's "Heaviest project by MCP usage" card. Records written by an earlier version carry no caller_source and are read as unattributed regardless of the project name they hold, because that name is the server process's own working directory rather than the caller's. The same applies to a usage/rollup.json written before this change — the raw records behind it are already deleted, so its labels are retracted rather than recomputed.
Daily series (#52). usage/daily.json stores per-day MCP call totals (mcp_calls, retrievals, writes, session_reads, doc_reads, other_reads, by_tool, attribution counts) so Analytics activity heatmaps survive --compact. Compact folds retiring JSONL files into folded_days before delete; each llmwiki build refreshes the live overlay from non-folded files without double-counting. The CLI report itself is unchanged — the Analytics page is the primary surface. See State persistence.
Scope is MCP calls only — file:// static-site browsing stays untracked.
Flags
| Flag | What |
|---|---|
--json |
Emit the aggregated totals (consumption + cost) as JSON. |
--compact |
Fold whole past months into the kept-forever usage/rollup.json and delete their raw logs before reporting. |
--vault PATH |
Read telemetry from this vault instead of the repo root. |
--state-file PATH |
State file to read the synthesis-cost estimate from. |
configure-sources — enable detected session stores
python3 -m llmwiki configure-sources
Interactive interview: shared start date first (Enter = today−30 or keep stored; or type YYYY-MM-DD). Then each shipped adapter: facts (Sessions · Earliest · In last 30 days, path found or not) → Enable ([Y/n] when a default path exists and ingest is ready, [y/N] otherwise) → path (suggested only if found) → start date (Enter = use shared, or YYYY-MM-DD). Writes filters.since and adapters.<name> to gitignored config.json.
Lookback quiz keys: shared Enter writes today−30 (or keeps stored); typed YYYY-MM-DD sets a custom shared floor. Per-source Enter on start date inherits shared (no since key); typed YYYY-MM-DD writes adapters.<name>.since. Merge-write touches only those since keys plus enable/path. Non-interactive --yes / skipped interview invents no dates. Config "all" on a per-adapter since key (hand-edited) still means no date gate for that source.
| Flag | What |
|---|---|
--yes |
Non-interactive: skip interview (no config writes). |
After a pip install (no setup.sh), run this once after llmwiki init. Git clone setup.sh offers the same interview on a TTY before install-automation. Set LLMWIKI_SKIP_CONFIGURE_SOURCES=1 to skip from setup.sh. Durable keys: configuration-reference.md — Sync lookback.
adapters — list every adapter + its status
python3 -m llmwiki adapters
Flags: none.
Expected output:
Registered adapters:
name present enabled description
---------------- -------- -------- ------------------------------
claude_code yes yes Claude Code — reads ~/.claude/projects/
openclaw yes yes OpenClaw — reads configured roots …
cursor_ide yes yes Cursor IDE — Composer sessions (globalStorage state.vscdb)
cursor_cli yes yes Cursor Agent CLI — reads ~/.cursor/chats/
Columns: present (store path on disk), enabled (yes / no — included on the next bare sync). Set via configure-sources; use sync --adapter <name> for a one-off.
graph — build the knowledge graph
python3 -m llmwiki graph # builtin wikilink graph
python3 -m llmwiki graph --engine graphify # AI-powered graph (requires graphifyy)
python3 -m llmwiki graph --format json
python3 -m llmwiki graph --format html
Flags
| Flag | What |
|---|---|
--format {json,html,both} |
Output format(s). Default: both. |
--engine {builtin,graphify} |
Graph engine. builtin = stdlib wikilink graph. graphify = AI-powered with community detection, confidence-scored edges, god nodes. Requires pip install graphifyy. Default: builtin. |
Builtin engine: Emits graph/graph.json (nodes + edges) and/or graph/graph.html (vis-network interactive viewer) plus sibling graph-viewer.js and vis-network.min.js. The interactive trio is also auto-copied into site/ on every build, so the graph works offline from the built static site without a CDN fetch.
Graphify engine: Runs the Graphify pipeline: tree-sitter AST extraction for code, semantic analysis for docs, Leiden community detection, god-node analysis. Outputs to graphify-out/ (graph.json, graph.html, GRAPH_REPORT.md) and copies to graph/ for build compatibility. Install: pip install llm-wiki-plus[graph] or pip install graphifyy.
lint — run registered wiki-quality rules
python3 -m llmwiki lint
python3 -m llmwiki lint --json
python3 -m llmwiki lint --fail-on-errors --fail-on-warnings
python3 -m llmwiki lint --rules link_integrity,orphan_detection
python3 -m llmwiki lint --rules page_findability,title_ambiguity,search_consistency
python3 -m llmwiki lint --wiki-dir ~/another-wiki
Flags
| Flag | What |
|---|---|
--wiki-dir PATH |
Wiki dir. Default: <content root>/wiki. Wins over --vault; the vault settings file is then read from its parent. |
--rules NAMES |
Comma-separated rule names. Default: all applicable. An unrecognised name exits 2 and lists the valid names. |
--min-refs N |
How many distinct wiki/sources/ pages must name a [[wikilink]] target before an unresolved link to it is reported. Default: 3 — the candidate harvest's own threshold, so a target the harvest deliberately declined is not a finding. --min-refs 1 reports every unresolved link, and is the lowest accepted value: 0 and negatives exit 2. |
--json |
JSON output: summary, issues, total_pages, disabled_rules, ran — the last naming the checks that produced the report, so a run narrowed by --rules cannot read as a full one. |
--fail-on-errors |
Exit 1 if any error-severity issues. |
--fail-on-warnings |
Exit 1 if any warning-severity issues. Stricter than --fail-on-errors; pass both to gate on either. |
--vault PATH |
Lint the wiki under this vault root, and read that vault's llmwiki.json. |
A wiki can switch off the rules that cannot apply to it, in a committed <vault>/llmwiki.json — every report then names each skipped rule and its recorded reason. See configuration-reference.md § Vault file for the file's shape and the caution that goes with it.
Rules
All rules are deterministic (no LLM). Structural: frontmatter_completeness, frontmatter_validity, link_integrity, orphan_detection, content_freshness, duplicate_detection, index_sync, contradiction_detection, claim_verification, summary_accuracy, stale_candidates, tags_topics_convention, stale_reference_detection, frontmatter_count_consistency, tools_consistency, stub_source_pages, provenance_integrity. Findability (#197): page_findability, title_ambiguity, search_consistency. The live count is whatever llmwiki lint --help prints.
contradiction_detection, claim_verification, and summary_accuracy used to hide behind --include-llm and advertise an LLM callback that was never wired. As of #72 they always run as structural checks: non-filler ## Contradictions sections, entity/concept claims without sources, and empty summary: frontmatter. Filler bodies like None identified., None detected., and multi-sentence None identified. … elaborations are not findings (unless the section also contains an unnegated affirmative conflict cue such as Contradicts earlier…). Cues that appear only inside negation (does not conflict with prior…, no claims that conflict…) stay filler (#86).
orphan_detection counts inbound [[wikilinks]] and catalog markdown links ([title](path.md) that resolve to a wiki page), so pages listed only from index.md are not orphans. link_integrity resolves targets case- and punctuation-insensitively ([[LLM-Wiki]] → llm-wiki.md) but does not do substring matching. It honours the candidate harvest's significance threshold (#150): a target named by no source page is always reported, a target named fewer than --min-refs times is a deliberate decline and is not, and a target named at least that often with no page of its own is a genuine gap and is.
stub_source_pages (#24) flags pages under wiki/sources/ whose body is machine-generated filler — a pending sentinel (<!-- llmwiki-pending: … -->) or the dummy backend's Auto-synthesized from session body. Those sources still count as unsynthesized backlog; refill them with llmwiki synth on a real backend.
provenance_integrity (#122) emits an error for each broken downward hop on pages that already carry sources: and/or source_file: — missing source-summary pages or missing raw files. Pages without those fields are skipped. The message names the missing hop and points at llmwiki trace, synth, or migrate broken-provenance as appropriate; this rule only reports.
stale_reference_detection (#303 / #87) flags living pages (entities, concepts, …) whose dated claim about a target predates that target's last_updated. Pages under wiki/sources/ and pages with frontmatter type: source are skipped — they are dated session records and cannot be "un-staled" without rewriting history.
Findability rules (#197)
These three share one corpus scan per lint run (same scoring path as llmwiki search / MCP wiki_search). They skip — rather than report clean — when the vault root is unavailable to the rule runner.
| Rule | Severity | What it checks |
|---|---|---|
page_findability |
error | A titled wiki page is not returned at all when searched by its own title (score ≤ 0, absent from the search corpus, or cut short by the result cap). Findability is keyed on title, not slug/filename — bare [[slug]] links are link-resolution metainfo (link_integrity), not findability failures. Prefer [[slug\|Title]] so readers see the title. |
title_ambiguity |
warning | A titled wiki page is not ranked first for its own title — names the outranking page, or reports a score tie. |
search_consistency |
error | Match-mode search disagrees with a literal scan over wiki pages and session content (present terms must hit; absent terms must not). Prints both term groups in full. |
search_consistency also reports a survival share at info severity: the fraction of sampled session terms that also appear in wiki pages. That share is information, never a defect — synthesis routinely drops wording, so a low share is expected until (or unless) those terms are rewritten into wiki pages.
Expected output
scanned 31 pages
28 issues: 0 errors, 22 warnings, 6 info
## link_integrity (22)
[warning] entities/GPT5.md: broken wikilink [[MultimodalModels]]
...
candidates — approval workflow
Positional action picks list / promote / flip-promote / merge / discard / apply / rewrite-key-facts.
--slug on promote / flip-promote / merge / discard / rewrite-key-facts (and merge --into, discard --redirect) matches the searched filename exactly first; failing that, it falls back to a unique norm_page_key fold of those filenames (case and punctuation insensitive, same fold link_integrity and harvest use), so --slug Junk still finds a stub written JUNK.md. The searched files are the pending stubs under wiki/candidates/<kind>/ for the review actions and the trusted pages under wiki/entities/ and wiki/concepts/ for rewrite-key-facts. A fold matching more than one page raises, naming every match, instead of guessing. A slug is sanitized the way a stub filename is and the resolved page must sit inside the wiki, so --slug ../../outside resolves to nothing rather than to a file beside the vault (#282).
Successful promote / flip-promote / merge / discard / apply reconcile wiki/index.md (#101): dead candidates/… bullets are dropped, an empty ## Candidates section is removed, and newly trusted pages are listed under Entities/Concepts. /wiki-candidates should call these same actions — do not run idle sync/synth just to refresh the catalog after review. Site UI: open site/candidates.html — it lists everything pending, takes a decision per row, and its Apply button prints the candidates apply --vault … --actions - command plus the JSON batch for the rows you decided (#97). A successful apply then rebuilds site/ so the open candidates page, Home, and Analytics match the wiki; pass --no-rebuild to skip that (for example when applying several batches before one llmwiki build).
promote fills an empty (or heading-only) ## Key Facts from nested fact: bullets on the cited source pages' Connections topics (#147 / #103). That path is offline — Dummy / None backends are fine. Non-empty reviewer Key Facts are left alone. Opt-in rewrite of trusted pages still needs a model: rewrite-key-facts uses the backend named by synthesis.backend (override the prompt per vault at wiki/prompts/key_facts.md).
merge folds a harvest stub into the target by unioning its sources: and Connections links and recording the name under ## Aliases (inbound [[merged-away]] links resolve to the survivor via that section in graph, lint, backlinks, and references); a candidate containing reviewer prose still has that prose appended under ## Candidate merge — <date>. Target may be a trusted page or another pending stub in the same kind.
discard archives the stub and rewrites every [[link]] to its name outside wiki/archive/ (any casing, labels and anchors included) to plain text — the label when there is one, else the name as written — so no link points into cold storage (#282). With --redirect PAGE those links become [[PAGE|text]] instead and the name is recorded under PAGE's ## Aliases, so later links to it resolve there and the synth vocabulary maps the name onto that page. PAGE must be an existing page outside wiki/candidates/ and wiki/archive/. Links are left alone when another live page or alias already answers to the name, and --redirect is then refused before the stub moves — the error names the page that already owns the name, since recording the alias anyway would leave two live pages answering to it. PAGE's own mention of the discarded name becomes plain text rather than a link to itself. The command prints how many links it rewrote in how many pages, and warns on stderr naming every page it could not read (those may still link to the discarded name). --redirect only applies to discard: combined with another action it is refused, on the command line and in an apply batch alike.
apply runs a batch of the same intents in one process (the JSON shape site/candidates.html prints). A batch that merges into a peer slug the same batch also promotes, flip-promotes, discards, or merges away is refused before any row runs — the CLI prints the conflicting actions and exits non-zero (#149).
python3 -m llmwiki candidates apply --actions '[{"action":"promote","slug":"Foo","kind":"entities"},{"action":"promote","slug":"Prompt Caching","kind":"concepts"}]'
python3 -m llmwiki candidates apply --actions - <<'EOF'
[{"action":"discard","slug":"Bogus","kind":"entities","reason":"noise"}]
EOF
Already-trusted pages that still carry machine-assembled (regex) Key Facts, or pasted harvest-stub ## Candidate merge blocks from the old merge path, are fixed with rewrite-key-facts:
python3 -m llmwiki candidates list
python3 -m llmwiki candidates list --stale --stale-days 60
python3 -m llmwiki candidates list --json
python3 -m llmwiki candidates promote --slug NewEntity
python3 -m llmwiki candidates promote --slug NewEntity --kind concepts
python3 -m llmwiki candidates flip-promote --slug Misfiled
python3 -m llmwiki candidates merge --slug DuplicateFoo --into Foo
python3 -m llmwiki candidates discard --slug BogusEntity --reason "LLM hallucinated"
python3 -m llmwiki candidates discard --slug "Old Name" --reason "duplicate" --redirect ExistingPage
python3 -m llmwiki candidates rewrite-key-facts --slug ExistingEntity
python3 -m llmwiki candidates rewrite-key-facts --all
Flags
| Flag | What |
|---|---|
--slug NAME |
Page slug. Required for promote / flip-promote / merge / discard; or with rewrite-key-facts. |
--all |
For rewrite-key-facts: every entity/concept page. |
--into NAME |
For merge: target slug (trusted page or another pending stub in the same kind). |
--reason TEXT |
For discard: why (written to archive's .reason.txt). |
--redirect PAGE |
For discard: point every [[link]] to the discarded name at existing live page PAGE (keeping the visible text) and record the name under its ## Aliases. Without it, discard turns those links into plain text. |
--kind {entities,concepts,sources,syntheses} |
Subtree. Auto-detected if omitted. |
--wiki-dir PATH |
Wiki dir. Default: ./wiki. |
--stale |
With list: only stale candidates. |
--stale-days N |
Staleness threshold. Default: 30. |
--json |
JSON output for list. |
--actions JSON |
For apply: JSON array of {action,slug,kind?,into?,reason?,redirect?} (redirect only with discard). Pass - to read the array from stdin. |
--no-rebuild |
For apply: skip rebuilding site/ after a successful batch. Default is to rebuild so candidates.html drops the rows that were just promoted, merged, or discarded. |
See guides/existing-vault.md for the round-trip semantics when a candidate lives inside a vault.
synth — synthesize sources + harvest candidates
Primary command (#90 / #147). Default runs both phases: pending sources → wiki/sources/, then entity/concept candidates → wiki/candidates/.
A real sources pass is two language-model jobs, then bookkeeping: (1) prepare known-names once at the start of the run (canonical name, aliases, kind, short description) from wiki already on disk — Dummy / not is_llm skips this and uses heuristic vocabulary inject; because that one call can take a minute or more, it first prints Preparing known names from N candidate topic(s) (~S KB prompt) — one language-model call, may take a minute… (no line when it is skipped or there are no candidates); (2) one source-summary ask per queued raw file, with that frozen list in the prompt (vocabulary may include kind="entity|concept" when known — #257). Connections bullets name each topic with kind and nested fact: claims.
Job 1 is known-names preparation (builds the vocabulary the source-summary prompts see, including kind). The later offline candidates harvest (after sources, or synth --candidates-only) only parses those Connections bullets into wiki/candidates/ — no classify LLM call; harvest cost alone is zero LLM. Do not treat them as one stage. Pages that only lack usable (entity) / (concept) labels on Connections — and whose targets already have matching wiki filings — should use llmwiki migrate topic-kinds for label-only catch-up (#174), not a full paid re-synth.
Clean stop (#145 / #181). Ctrl+C, or a backend usage limit (the synthesizer's error message says the account's session or usage quota is exhausted), stops the run from starting new sources. Queued sources are cancelled; pages already in flight finish and are recorded (page, state entry, pending removal). The run then does the same bookkeeping as a successful one — a single wiki/log.md entry marked stopped early with a Deferred: count, pending refresh, index rebuild — and harvests candidates from what was written (unless --sources-only, which prints llmwiki synth --candidates-only). A usage-limit stop prints one line, Stopped after N/M source(s) — backend usage limit (resets <time>); waiting for K page(s) already in flight., instead of an error per remaining source. Sources that did not run are deferred, not errors: they stay pending and the next run picks them up. All three backends (Claude CLI, Cursor Agent CLI, Ollama) recognise a usage limit from the message text (hit your … limit, usage limit, quota exceeded, …); a plain rate-limit 429 / "Too Many Requests" is a per-source error. If the limit hits the known-names preparation, no page is sent and every queued source is deferred. Pressing Ctrl+C a second time while in-flight pages finish kills the Claude / Cursor CLI processes and ends the run; those pages stay pending. Ollama has no child process, so a second Ctrl+C there waits for in-flight requests up to the Ollama timeout. synth never rebuilds site/ — after a successful run or a stop, run llmwiki build.
Exit codes:
0— every queued source was synthesized (and harvested, unless--sources-only).1— at least one source failed, or harvest failed.2— usage error (bad flags or paths).75— stopped on the backend's usage limit; retry after the reset time.130— interrupted with Ctrl+C.
A stop exits 75 / 130 even when some sources in the same run also failed; those errors are still printed.
python3 -m llmwiki synth --check # probe the backend
python3 -m llmwiki synth --estimate # cost + Candidates (pre-run state)
python3 -m llmwiki synth --force # re-synth everything, then harvest
python3 -m llmwiki synth --sources-only # legacy: sources only
python3 -m llmwiki synth --sessions-only # all pending sessions (skip docs)
python3 -m llmwiki synth --docs-only # all pending docs (skip sessions)
python3 -m llmwiki synth --candidates-only # entity/concept candidates only
python3 -m llmwiki synth --candidates-only --min-refs 5
python3 -m llmwiki synth --path raw/sessions/<file>.md
python3 -m llmwiki synth # real run (sources + candidates)
llmwiki synth is the synthesize entry. Known-names prepare runs at the start of each sources pass.
Before the first page is synthesized, a real run announces the batch: Synthesizing 11 source(s) with ClaudeCLISynthesizer (2 at a time) — the count is the work queue after up-to-date, ineligible, and already-claimed sources are excluded, so it is what the run will actually do. An empty queue says Nothing to synthesize — every source is already up to date. instead. Each result line then carries its position, [3/11] synthesized: <project> → <page>, counting completed sources against that total; pages finish in whatever order the backend returns them, so the positions arrive out of order while the last one is always N/N.
--estimate prints the sources cost estimate with honest input units (#81): Corpus: N eligible sources (S sessions + D docs) and Already synthesized: N of M eligible sources (not page/file counts under wiki/sources/), then a separate Source pages (current state): T on disk (Sess sessions + D docs + X stubs) line for on-disk .md file counts. It also prints a Candidates (pre-run state): block — the harvestable shape of wiki/sources/ as it exists now, with a note that pending sources are not yet reflected. It is not a forecast of what the next run will harvest (#113). After a successful real synth (not estimate), the CLI prints an end-of-run summary: Synthesized:, Duration:, optional Tokens: / Cost: when known. Harvest still prints its Candidates line once; the end summary does not repeat Candidates.
--estimate writes vault state. It calls no backend and touches no page, but it records its result in the vault's llmwiki-state.json: the pending list (synth.pending), the Home Pipeline rows (synth.pipeline) and the estimate block (synth.estimate) — what the Home page's Pipeline counts show. Pending is judged by file modification times, so right after a git clone, checkout or pull every source looks changed and the estimate records them all as pending. In a vault whose state file is committed (such as the repository's demo/), discard that change instead of committing it.
Flags
| Flag | What |
|---|---|
--check |
Probe backend availability + exit (0 if reachable). |
--force |
Ignore state, re-synth every source. |
--estimate |
Print cached-vs-fresh token + dollar estimate for pending sources in eligible-source units (Corpus / Already synthesized), plus Source pages (current state): T on disk (sessions + docs + stubs) and Candidates (pre-run state): (current wiki/sources/ shape — not a forecast of the next harvest) (#50 / #90 / #81 / #113). |
--sources-only |
Synthesize wiki/sources/ only — skip candidate harvest (legacy synthesize behaviour). Mutually exclusive with --candidates-only / --check / --estimate. |
--sessions-only |
Synthesize only raw/sessions/ — skip raw/docs/. Mutually exclusive with --docs-only. Combinable with --path / --force (paths under raw/docs/ then exit 2). Incompatible with --check / --estimate. |
--docs-only |
Synthesize only raw/docs/ — skip raw/sessions/. Mutually exclusive with --sessions-only. Combinable with --path / --force (paths under raw/sessions/ then exit 2). Incompatible with --check / --estimate. |
--path PATH |
Synthesize only this raw session or doc under raw/sessions/ or raw/docs/ (repeatable; relative to the vault root, or absolute under it) (#62). Exit 2 if the path is missing or outside the vault. Still honours filters.include_subagents / exclude_headless (ineligible files are skipped even when named). Incompatible with --check / --estimate. |
--candidates-only |
Harvest entity/concept candidates from already-synthesized wiki/sources/ into wiki/candidates/, then exit (#90 / #147). Reads the source layer only — never raw/ — so it runs no per-source synthesis and no classify LLM call; kind, description, and facts come from Connections topic bullets already on those pages. LLM cost is zero. Unreadable source pages still fail the run and write nothing. Mutually exclusive with --sources-only / --check / --estimate. |
--min-refs N |
Candidate threshold: a [[wikilink]] target becomes a candidate when N or more distinct source pages name it (default: 3). |
--concurrency N |
Synthesize N source pages at once, overriding synthesis.concurrency (default: 2; range 1–16). 1 runs strictly sequentially. Pages are I/O-bound on the backend, so the wall clock shrinks roughly in proportion; raise it only as far as your provider's rate limits and your machine allow. all has no matching flag — its synth stage reads synthesis.concurrency. |
--backend NAME |
One-run overlay of synthesis.backend (dummy | ollama | claude | cursor_cli). Honoured by --check, --estimate, and a real run. Does not write config.json. Unknown names exit 2. |
--vault PATH |
Read/write under the vault root; configures the active llmwiki-state.json. |
Backend is picked from synthesis.backend in config.json / sessions_config.json (dummy by default; ollama for local; claude for synchronous claude -p; cursor_cli for Cursor Agent CLI agent -p, default model composer-2.5). Nested blocks: synthesis.claude, synthesis.cursor_cli, synthesis.ollama (flat claude_* still works). This is the synthesis generator — not the cursor_cli / cursor_ide session-ingest adapters. See configuration.md.
Removed in v1.4.0:
--list-pendingand--complete(agent-delegate pending prompts). Usesynthesis.backend: claude(orcursor_cli) instead.
Auto-tagging (#351)
Every synthesize call now produces topical tags alongside the deterministic baseline. The synthesizer emits a <!-- suggested-tags: prompt-caching, rag, github-actions --> block as the first line of its response; the pipeline parses it, strips it from the body, and merges the tags into frontmatter with:
- Baseline preserved — adapter, project slug, model family stay.
- Maintainer wins — on
--force, whatever you added viallmwiki tag addis kept at the front of the list. - Stop-word filter — the LLM can't re-add boilerplate tags (
session,summary,claude-code, etc.). - Cap 5 — max 5 AI tags per page to prevent drift.
- Near-dup rejection —
prompt-cacheis blocked whenprompt-cachingis already on the page (threshold 0.80 + prefix check).
No extra API round-trip — rides the existing synthesis call, so cost estimates from --estimate are unchanged. If the backend returns no suggested-tags block (dummy backend, malformed output), the page still ships with baseline tags.
Removed: synthesize (use synth; the old name was sources-only by default) and consolidate-topics (known-names prepare is part of synth).
queue — inspect and run unified queue
Manage the unified vault queue in llmwiki-state.json.
python3 -m llmwiki queue
python3 -m llmwiki queue enqueue --task-type add_doc --source https://example.com
python3 -m llmwiki queue run --vault /path/to/vault --limit 20
Positional
| Value | What |
|---|---|
status |
Print queue counts, task-type breakdown, state path, and oldest pending timestamp. |
enqueue |
Add one task (add_doc, session_sync, synthesize, build). |
run |
Execute pending tasks serially (up to --limit). |
Flags
| Flag | What |
|---|---|
--task-type {add_doc,session_sync,synthesize,build} |
Task kind for enqueue. |
--source TEXT |
Source payload for add_doc enqueue. |
--limit N |
Max tasks to process in one run call. Default: 20. |
--vault PATH |
Vault root used for task execution and state lookup. |
--state-file PATH |
Override direct state file path. |
migrate — list or apply a named one-time vault repair
Rare. One-time vault repairs after an upgrade — not part of the daily loop. List available migrations with llmwiki migrate or llmwiki migrate --list. Nothing is applied until you choose a name: llmwiki migrate <name> [flags]. There is no run-everything default. Prefer --dry-run on a named migration to preview writes.
New migrations are registered under migrate in llmwiki/cli.py, not as new top-level commands. Older docs that said migrate-X mean migrate <name> (for example migrate-raw-redaction → migrate raw-redaction).
python3 -m llmwiki migrate
python3 -m llmwiki migrate --list
python3 -m llmwiki migrate state --state-file /path/to/vault/llmwiki-state.json
python3 -m llmwiki migrate raw-redaction --vault /path/to/vault --dry-run
python3 -m llmwiki migrate raw-unredaction --vault /path/to/vault --dry-run
python3 -m llmwiki migrate tools-used --vault /path/to/vault
python3 -m llmwiki migrate page-kinds --vault /path/to/vault --dry-run
python3 -m llmwiki migrate topic-kinds --vault /path/to/vault
python3 -m llmwiki migrate wikilink-titles --vault /path/to/vault --dry-run
python3 -m llmwiki migrate discarded-topic-links --vault /path/to/vault --dry-run
python3 -m llmwiki migrate source-page-paths --vault /path/to/vault --dry-run
python3 -m llmwiki migrate broken-provenance --vault /path/to/vault --dry-run
state — one-time legacy state migration (v1.4.0)
Migrates legacy dotfiles (.llmwiki-state.json, .llmwiki-synth-state.json, .llmwiki-queue.json, .llmwiki-quarantine.json, .llmwiki-pending-prompts/) into the unified llmwiki-state.json.
Implementation lives at scripts/migrate_state_v1_4_0.py; the CLI is a thin wrapper.
python3 -m llmwiki migrate state
python3 -m llmwiki migrate state --state-file /path/to/vault/llmwiki-state.json
python3 scripts/migrate_state_v1_4_0.py --state-file /path/to/vault/llmwiki-state.json
| Flag | What |
|---|---|
--state-file PATH |
Explicit target state file (defaults to configured vault path). |
The command is idempotent and prints cleanup suggestions for migrated legacy files. It also repairs the vault: legacy pending prompts are resolved (not re-queued); dead synth_request queue items are purged; one synthesize queue task is enqueued when synth.pending_total > 0 and none is already pending (drain with llmwiki queue run --vault <path>); removed synthesis backends (agent, agent-delegate, agent_delegate) print a WARNING: to set claude, ollama, or dummy. Report keys: state_file, migrated, orphan_cleanup_suggestions, warnings, pending_prompts_total, pending_prompts_unfilled, synth_request_items_purged, queued_synthesize.
raw-redaction — deterministic username rewrite in raw/
Rewrites already-synced raw/sessions/*.md so home-path and dash-encoded agent-store segments use the USER placeholder (-Users-<you>-… → -Users-USER-…). In-place string rewrite only — does not re-convert from ~/.claude/projects / Cursor stores, does not touch wiki/, and does not enqueue synthesis.
Prefer this over llmwiki sync --force when redaction completeness in existing raw/ matters: agent transcripts are usually retained only ~30 days, so older sessions often have no source left to re-convert; force-sync followed by re-synth also burns LLM tokens for no benefit.
Implementation: scripts/migrate_raw_encoded_username.py. After migrating, rebuild so site/ picks up any display changes: llmwiki build --vault PATH.
python3 -m llmwiki migrate raw-redaction --vault /path/to/vault --dry-run
python3 -m llmwiki migrate raw-redaction --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing raw/sessions/. |
--dry-run |
Report files that would change; write nothing. |
--real-username NAME |
Override redaction.real_username (default: config / $USER). |
--replacement-username NAME |
Override placeholder (default: USER). |
Runs regardless of redaction.redact_username — invoking it is the explicit request to redact. Idempotent: already-redacted files count as unchanged. Private local vaults that never publish raw/ can skip this and only run llmwiki build after upgrading (see UPGRADING.md).
raw-unredaction — restore real usernames in raw/ paths
Reverse of raw-redaction (#253). Rewrites already-synced raw/sessions/*.md so the USER placeholder in home-path and dash-encoded segments (/home/USER/…, -Users-USER-…) becomes your real username again. A bare USER word outside a path position is never touched. Same file scope and guarantees as raw-redaction: no re-convert, no wiki/ changes, no synthesis.
Use it on a private vault synced while redaction.redact_username was on (the default before #253). Refuses (exit 2) when the real username is empty or equals the placeholder. Prints a note when the effective config still has redaction.redact_username: true, since new syncs would write the placeholder again. Rebuild afterwards: llmwiki build --vault PATH.
python3 -m llmwiki migrate raw-unredaction --vault /path/to/vault --dry-run
python3 -m llmwiki migrate raw-unredaction --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing raw/sessions/. |
--dry-run |
Report files that would change; write nothing. |
--real-username NAME |
Username to restore (default: redaction.real_username / $USER). |
--replacement-username NAME |
Placeholder to replace (default: USER). |
Idempotent: files with no placeholder left count as unchanged.
Limitations — review the --dry-run list before writing:
- It cannot tell a redacted path from a placeholder path a person typed on purpose. Prose that quotes a rule such as "use
/home/USER/…" is rewritten to your real home path too. - It restores one target username for every file. In a vault synced from several machines or accounts, that name is wrong for files that came from the others.
tools-used — expand CallMcpTool frontmatter from origin stores
Rewrites tools_used and tool_counts in already-synced raw/sessions/*.md when the originating agent session file still exists. Re-reads records through the session adapter and applies the same tool_use_recorded_names expansion llmwiki sync uses (CallMcpTool → mcp__{server}__{tool}). In-place frontmatter update only — does not touch wiki/, does not enqueue synthesis, and never invents MCP names when the origin store is gone (TTL / deleted sessions count as skipped_missing_origin and stay unchanged).
Implementation: scripts/migrate_tools_used_mcp.py. After migrating, rebuild so analytics and the site pick up the new tool names: llmwiki build --vault PATH.
python3 -m llmwiki migrate tools-used --vault /path/to/vault --dry-run
python3 -m llmwiki migrate tools-used --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing raw/sessions/. |
--dry-run |
Report files that would change; write nothing. |
--config PATH |
Optional sessions_config.json override (record filters). |
Origin resolution prefers the vault's llmwiki-state.json sync keys (adapter::home-relative-path), then falls back to a glob under the adapter session store by sessionId. Claude Code JSONL is fully supported; Cursor and other non-JSONL stores work when the state key or glob resolves a readable origin path. Missing origins leave CallMcpTool entries intact for wiki_adoption body fallback.
page-kinds — retype pages off the removed question/comparison kinds
llmwiki/schema.py lists five knowledge kinds — source, entity, concept, project, synthesis. A hand-written page declaring type: question or type: comparison is a frontmatter_validity error, and this migration clears it: each such page is retyped to concept and moved into wiki/concepts/ keeping its filename, then wiki/questions/ and wiki/comparisons/ lose their _context.md and are pruned once empty.
Inbound links are left alone on purpose. [[wikilinks]] resolve by filename, never by folder, so a page that keeps its name keeps every inbound link and no referring page needs editing.
Two safety rules: a page whose filename is already taken in wiki/concepts/ is retyped where it stands and reported as a collision rather than overwriting anything, and a removed folder still holding other content is left in place and reported rather than deleted. A vault with no removed-kind page prints nothing to migrate and exits 0 without writing.
Implementation: llmwiki/migrate_page_kinds.py — in the package rather than under scripts/, so it runs from a pip install with no checkout. After migrating, rebuild so site/ picks up the new locations: llmwiki build --vault PATH.
python3 -m llmwiki migrate page-kinds --vault /path/to/vault --dry-run
python3 -m llmwiki migrate page-kinds --vault /path/to/vault
python3 -m llmwiki lint --vault /path/to/vault --rules frontmatter_validity
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing wiki/. |
--dry-run |
Report what would change; write nothing. |
Idempotent: a second run finds nothing to migrate. On a run that changed something the command reconciles wiki/index.md and appends ## [YYYY-MM-DD] migrate | page kinds to wiki/log.md.
topic-kinds — stamp entity/concept kinds onto older source Connections
Older source summaries often list [[wikilinks]] under ## Connections without an (entity) or (concept) kind. After the one-pass topic shape, those pages look like they still need a full rewrite. This offline migration stamps known kinds from pages already under wiki/entities/, wiki/concepts/, and the matching wiki/candidates/ folders — no language model, no network call, and raw/ is never written.
Only the Connections section is edited. Nested fact: lines, Key Claims, Key Quotes, and frontmatter stay byte-identical. Names that exist as both an entity and a concept are ambiguous: those bullets are skipped and listed in the report rather than guessed. Already-kinded bullets are left alone.
A successful non-dry-run that stamps at least one page writes .llmwiki-topic-kinds-stamped.json at the vault root (vault-local machine state — not for git) so you can later force-resynthesize exactly those sources if you want fact lines. The same apply (and a re-run over already-clear pages) upserts synth state for every raw session/doc whose wiki target is rewrite-clear — including when many raw files share one synth filename — so plain llmwiki synth / --estimate will not re-bill them. The report always states that zero facts were derived.
Implementation: llmwiki/migrate_topic_kinds.py. Stamping clears the rewrite-needed flag when at least one resolvable kind lands; it does not invent facts. Use llmwiki synth --force --path … on stamped pages if you want fact lines afterwards.
python3 -m llmwiki migrate topic-kinds --vault /path/to/vault --dry-run
python3 -m llmwiki migrate topic-kinds --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing wiki/. |
--dry-run |
Report what would change; write nothing (no stamped JSON either). |
Idempotent: a second run finds nothing to stamp and prints nothing to migrate: no connection lines need topic kinds. Preview with --dry-run before applying.
wikilink-titles — add title display text to bare resolving wikilinks
Wiki search and the page_findability lint key on page title (frontmatter title), not on slug/filename. Bare [[OpenAI]] links still resolve correctly, but their visible text is the slug stem. This offline migration rewrites resolving bare [[slug]] links to [[slug|Title]] using titles already on disk under wiki/ — no language model, no network call, and raw/ is never written.
Section anchors are preserved ([[Page#Section]] → [[Page#Section|Title]]). Case/punctuation variants that uniquely match a page under the same norm_page_key fold as link_integrity / harvest (e.g. [[LLM-Wiki]] when the page slug is llm-wiki) are rewritten to the canonical slug plus title ([[llm-wiki|…]]). Links that already carry display text ([[slug|alias]]), unresolved or ambiguous-norm targets, true aliases (written name is a different page identity), and titles that would break wikilink syntax (contain | or ]]) are skipped and counted in the report. Fenced/example [[slug]] tokens are rewritten the same as prose — skim --dry-run changed pages before applying.
Implementation: llmwiki/migrate_wikilink_titles.py. Cosmetic/readability only — not required for lint green once findability is title-only. Rebuild the site after applying if you want HTML to show the new display text: llmwiki build --vault PATH.
python3 -m llmwiki migrate wikilink-titles --vault /path/to/vault --dry-run
python3 -m llmwiki migrate wikilink-titles --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing wiki/. |
--dry-run |
Report what would change; write nothing. |
Idempotent: a second run finds nothing to rewrite and prints nothing to migrate: no bare slug wikilinks need title display text. Preview with --dry-run before applying.
discarded-topic-links — unlink or redirect links to discarded candidates
Since #282 candidates discard rewrites the links to the name it archives. Candidates discarded before that still have [[links]] pointing into wiki/archive/, which link_integrity reports. This offline migration finds every archived candidate that no live page answers to (by stem or ## Aliases — merged and redirected names are left alone) and turns each [[Name]], [[name|label]] or [[Name#section]] outside wiki/archive/ into plain text: the label when the link has one, otherwise the name as written. --redirect NAME=PAGE (repeatable) points that name's links at an existing live page instead ([[PAGE|text]]) and records the name under the page's ## Aliases, exactly like candidates discard --redirect. It also moves candidate stubs a / in their name filed into a subfolder to the flat path harvest now writes (A/B thing → candidates/<kind>/A-B thing.md), reporting a conflict instead of overwriting an existing file. No language model, no network call, raw/ never written.
Implementation: llmwiki/migrate_discarded_topic_links.py. Rebuild the site afterwards: llmwiki build --vault PATH.
python3 -m llmwiki migrate discarded-topic-links --vault /path/to/vault --dry-run
python3 -m llmwiki migrate discarded-topic-links --vault /path/to/vault --redirect "Old Name=ExistingPage"
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing wiki/. |
--dry-run |
Report what would change; write nothing. |
--redirect NAME=PAGE |
Point links to discarded NAME at existing PAGE (and record the alias) instead of unlinking them. Repeatable. |
--force |
Unlink a name whose reason.txt records a merge even when no live page answers to it, instead of reporting a suggested --redirect. |
Every --redirect pair is checked before the first write: a name with no archived candidate, or a PAGE that is missing or ambiguous, stops the run with nothing written (nothing was written: fix the errors above and re-run) and exit code 1. A pair whose name a live page already answers to — including a re-run of the same command, once the alias exists — needs no redirect and is listed under skipped: rather than dropped. Pages the run could not read are listed under errors: and exit code 1, with the changes that did apply printed above them, so a vault with one unreadable page never reports success while links to a discarded name are left behind.
Merged names are guarded. A candidate a reviewer merged is archived with Reason: merged into <target>, and its links belong on the survivor page. The survivor normally answers to the merged-away name through its ## Aliases entry, so the migration never touches those links. When the survivor was later renamed or re-filed — or when the merge predates the alias entry entirely — nothing but that reason file still ties the name to a page, and flattening its links to plain text would throw the target away. Such a name keeps its links, is listed under merged, left linked: with the page the run believes it means, and the run exits 1 so a script notices:
merged, left linked: 1
- Old Name — merged into foo (587 links)
--redirect "Old Name=code-foo"
a reviewer merged these names into a page that no longer answers to them, so their links were left as they are: re-run with the --redirect lines above, or --force to unlink them like a dismissal
Re-run with the suggested --redirect lines to point the links at the survivor (which then records the alias, so a third run reports nothing), or pass --force to unlink them like any other dismissal. The suggestion is the live page answering to the recorded target, else the single live page whose norm_page_key contains or is contained by it; when nothing matches, the report asks for a page (--redirect "Old Name=<page>"). Everything else in the same run — the flatten, plain dismissals, explicit redirects — still applies, and --dry-run prints the same partition.
A recorded merge with no links anywhere in the wiki needs no --redirect: it is left out of merged, left linked: entirely and never makes the run exit 1 on its own — there is nothing for an operator to preserve or flatten.
Idempotent: a second run finds nothing to rewrite and prints nothing to migrate: no links to discarded candidates and no nested stubs.
source-page-paths — move source pages filed under a stale name
A real wiki/sources/ page is tied to its raw file by source_file:. When its filename differs from the one synth derives for that raw file today (<date>-<slug> under wiki/sources/<project>/), synth's duplicate guard skips the source on every run — reported as one skipped N source(s) already claimed by a real page under another name line — and synth --estimate / Home keep counting it as pending. Earlier naming schemes (a session description shared by many sessions, the whole raw filename after the date, a number-shaped slug that fell back to the raw filename) left such pages behind.
This offline migration, with no language model and no network call:
- Finds every real (non-stub) source page whose
source_file:names an existingraw/sessions/orraw/docs/file and whose path differs from the derived one. A doc's--part-NNpages move as one group, keeping their part suffixes. - Moves each page to its derived path with body and frontmatter intact.
titlechanges only while it still readsSession: <old name> — <date>(the converter's title for the old name); it then becomes the raw file's current title. - Rewrites
[[old-stem]],[[old-stem|label]]and[[old-stem#anchor]]links acrosswiki/, and the stem in frontmattersources:lists. A label changes only when it equals the old title. When more than one page answers to a bare stem, the link (orsources:entry) in page P follows the one source page with that stem whose body links back to P (matched with the same case/punctuation fold aslink_integrity); if that back-linker stays put the link is left as it is, and with no back-linker, several, or a back-linker whose new name would itself be ambiguous, the link is reported as ambiguous and left alone — the report counts links disambiguated by backlink, links still ambiguous, and those that will break because every page of that name moves; a path-qualified link ([[sources/<project>/<stem>]],[[<project>/<stem>]]) is rewritten when its path matches exactly one page.wiki/archive/and the log are never edited. - Records synth state (
synth.filesin<vault>/llmwiki-state.json, the raw file's mtime) for each moved source, and for a real page already at its derived path, when the source has no state entry yet. An existing entry is kept as it is — one older than the raw file means the raw was re-converted after synthesis, and synth still has to see that page as stale. Moves are applied first; a move that fails to write or to leave its old path is undone, reported, and dropped together with its link rewrites and state entry. Then refreshes the Home pending count, rebuildswiki/index.mdwhen the vault keeps one, and appends amigrate | source page pathsentry towiki/log.md. - Reports a collision — and changes nothing for that source — when a real page already sits at the derived path. A stub at the derived path for the same source is replaced.
Implementation: llmwiki/migrate_source_page_paths.py. raw/ is never written. Rebuild the site afterwards: llmwiki build --vault PATH.
python3 -m llmwiki migrate source-page-paths --vault /path/to/vault --dry-run
python3 -m llmwiki migrate source-page-paths --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing wiki/ and raw/. |
--dry-run |
Print planned moves, collisions, link rewrites, ambiguous links and state upserts; write nothing. |
Idempotent: a second run finds nothing to move and prints nothing to migrate: every source page sits at its derived path.
broken-provenance — remap or clear hops to missing raw sessions
After a Cursor Agent CLI re-sync that used the filesystem stem store as sessionId, force-convert can leave wiki pages pointing at deleted raw/sessions/… paths while newer raw files exist under the same project slug (cursor-<hash>). This offline migration walks wiki pages that carry source_file: / sources: provenance and, when a hop targets a missing raw/sessions/ file:
- Parses the project slug from the missing path (for example
cursor-<hash>). - Finds existing raw files whose names contain that project slug.
- Restricts candidates to the same calendar day (
YYYY-MM-DDprefix). Never remaps across days (that used to point every June stub at a single January session). - Remaps only among same-day interactive raw files: explicit
is_headless: false, or legacy unmarked (nois_headlessfield — same eligibility rule as synth). When several remain, remaps to the uniquely closest HH-MM in that shortlist. - Otherwise clears the broken
source_file(same-day headless-only pools, ambiguous closest-time ties, or no same-day interactive candidate) and drops matchingsources:list aliases. Wiki pages themselves are never deleted. Never remaps to a row that is explicitlyis_headless: true.
Implementation: llmwiki/migrate_broken_provenance.py. Preview with --dry-run. Prefer a Cursor Agent CLI re-sync first so raw filenames carry real chat dates and is_headless is stamped; unmarked legacy same-day files remain remap-eligible until then.
python3 -m llmwiki migrate broken-provenance --vault /path/to/vault --dry-run
python3 -m llmwiki migrate broken-provenance --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing wiki/ and raw/. |
--dry-run |
Report what would change; write nothing. |
The report prints remapped / cleared / unresolved counts. Idempotent once hops are healed or cleared.
install-agent-kit — copy packaged slash commands and skills (#109)
A pip install carries the user-facing /wiki-* slash commands and skills inside the package (llmwiki/agent_kit/). This command copies commands/ and skills/ beneath a directory you name so Claude Code (or any agent that reads that layout) can see them. --dest is required — the command does not guess at agent directory conventions.
Typical destinations, by where you want the commands and skills to be visible:
--dest |
Who reads it |
|---|---|
~/.claude |
Claude Code, every project on the machine |
~/.cursor |
Cursor, every project on the machine (it reads top-level commands/ and skills/) |
~/.codex |
Codex CLI, every project on the machine |
.claude |
Claude Code, this project only — what contributors in this clone use to get /wiki-* locally |
Point --dest at whichever agent directory you actually use; install into more than one if you switch between agents. The files are plain markdown and the format is portable, so an agent with a different layout can take the same commands/ and skills/ folders. The packaged skills themselves are catalogued in slash-commands.md.
Re-running after an upgrade refreshes the copies, and reports which of them were stale. A destination file whose content already matches the kit is left alone and counted as unchanged. A file that differs is classified by what its content is, using the same digests that gate pruning:
| Class | What it means | What happens |
|---|---|---|
outdated |
The bytes are the revision <dest>/.llmwiki-agent-kit.json records for that path, so they are a copy llmwiki itself installed. |
Reported as outdated, naming the version that installed it when the manifest records one, and overwritten. No .bak — these are llmwiki's own bytes, so a backup of them is noise, and writing one can overwrite a real backup beside it. |
customised |
The bytes match nothing the manifest records there, so you edited the file (or it predates the manifest). | Reported as customised, naming the version you patched when the manifest knows the path. Your edits cannot be merged into the kit update, so the file is copied to <filename>.bak beside it before the kit version is written, and the backup is reported once it is on disk. |
Running --dry-run against an install is therefore how you ask is my agent kit stale? — it classifies exactly as a real run and writes nothing. Version attribution comes only from <dest>/.llmwiki-agent-kit.json: with no manifest, or for a path the manifest does not record, the report names no version rather than guessing one.
The install also prunes commands and skills the kit has retired (#214), so an agent directory populated by an older install stops offering them. Pruning is gated on content, never on the name: a file is deleted only while it still hashes to a revision llmwiki is known to have written at that path. Two things supply those digests — a small list of retired paths carried in the package, each mapped to the digests of every revision it ever shipped, and <dest>/.llmwiki-agent-kit.json, a manifest of the llmwiki version and a path → sha256 record of what this command installed, written after a pass. Anything the previous manifest recorded that the current kit no longer ships is pruned when its bytes are unchanged. A file this command never installed is never touched, whatever its name, so your own commands beside the kit's are safe; a retired command you customised is safe for the same reason — an unrecognised digest leaves the file alone and reports it as kept. Manifest entries that are absolute, escape the destination, or sit outside commands//skills/ are ignored, and a manifest that is missing, unreadable, or written in an older shape that carries no digests falls back to the retired list. Because only bytes llmwiki itself wrote are ever removed, a prune makes no backup; only files are removed — never directories. --dry-run reports the prune and deletes nothing.
The manifest is a normal file in --dest. When that is a git-tracked .claude/, commit .llmwiki-agent-kit.json alongside commands/ and skills/: it is what lets a later upgrade recognise its own files and clean them up. Because it is also what decides which files are replaced without a .bak, treat a manifest you did not generate the way you treat the files beside it.
Contributor-only commands (fix-bug, implement-feature, release) and skills (docs-that-work, pytest-best-practices, release, …) stay in this repository's .claude/ tree and are not part of the kit. Cutting a tagged release uses .claude/skills/release/SKILL.md via /release (see docs/maintainers/RELEASE_PROCESS.md).
python3 -m llmwiki install-agent-kit --dest .claude --dry-run
python3 -m llmwiki install-agent-kit --dest .claude
python3 -m llmwiki install-agent-kit --dest /path/to/agent-dir
Flags
| Flag | What |
|---|---|
--dest PATH |
Required. Directory that will receive commands/ and skills/. |
--dry-run |
Report what would be written; write nothing. |
The command prints every path written, every outdated copy it replaced, every customised file with the .bak its previous content went to, every path pruned, every retired path it kept because the content was not its own, and a count of identical files left untouched. Every path in the report, errors included, is absolute, so you can open it straight from the output. Exit 0 on success, 1 if a file could not be read or written.
version — print the installed version
python3 -m llmwiki version
python3 -m llmwiki --version
Both print llmwiki <version>.
search — literal term or phrase search (#197)
Pre-AI-era literal search: score-weighted matching of the characters you type, found anywhere including inside longer words — for example cat matches concatenate. No stemming, no spelling correction, no meaning-based matching. Same engine agents use via MCP wiki_search.
This is not query. search ranks pages by literal character overlap; query walks the knowledge graph in natural language via Graphify (pip install llm-wiki-plus[graph]).
Result text. Both modes use the same centred snippet window (~400 characters around the first hit via extract_snippet). Term mode still returns matching lines (each line previewed that way); phrase mode returns one page snippet per hit.
python3 -m llmwiki search RAG --vault /path/to/vault
python3 -m llmwiki search "reinforcement learning" --mode phrase --format json
python3 -m llmwiki search --terms-file terms.txt --mode term
python3 -m llmwiki search --terms-file phrases.txt --mode phrase
python3 -m llmwiki search --terms-file - --mode phrase < phrases.txt
Positional
| Arg | What |
|---|---|
QUERY |
Single term (default --mode term) or phrase (--mode phrase). Omit when using --terms-file. |
Flags
| Flag | What |
|---|---|
--mode {term,phrase} |
term → match mode (token-style); phrase → extract mode (multi-word / whole-phrase bonus). Default: term. |
--terms-file PATH |
Bulk input, one term or phrase per line; # comments and blanks skipped; - reads stdin. Use with --mode term for a term list or --mode phrase for a phrase list. |
--vault PATH |
Search this vault root read-only. Without it, uses config.json vault.default_path or the repo demo content. |
--include-raw |
Also scan raw/sessions/ (term mode). |
--kind K |
Frontmatter type filter (term mode). |
--max-pages N |
Result cap in phrase mode. Default: 5. |
--format {text,json} |
Text list or JSON payload matching the MCP tool shapes. Default: text. |
Bulk runs group hits per entry and state which entries returned nothing. Always exits 0 on a successful search (including zero hits). Does not interpret expectations — use lint findability rules (page_findability, title_ambiguity, search_consistency) for pass/fail. Read-only: never modifies the vault.
query — natural-language knowledge-graph walk (Graphify)
python3 -m llmwiki query "what projects am I working on"
python3 -m llmwiki query "Flutter mobile" --depth 2 --budget 1000
Asks a natural-language question over the Graphify knowledge graph. Distinct from search, which does literal term/phrase matching with no semantics.
Flags
| Flag | What |
|---|---|
--depth N |
BFS traversal depth. Default: 3. |
--budget N |
Max output tokens. Default: 2000. |
Requires Graphify (pip install llm-wiki-plus[graph]). Run llmwiki graph first to build the graph.
trace — print downward provenance to raw transcripts (#122)
Walk a wiki page’s encoded chain to its source summaries and raw files. Uses only frontmatter (sources:, source_file:) — no body excerpts. Missing hops are marked; the walk still succeeds.
python3 -m llmwiki trace Demo --vault /path/to/vault
python3 -m llmwiki trace wiki/entities/Demo.md --vault /path/to/vault
Positional
| Arg | What |
|---|---|
PAGE |
Vault-relative wiki path (wiki/entities/Foo.md) or a resolvable page name/stem under wiki/. |
Flags
| Flag | What |
|---|---|
--vault PATH |
Trace under this vault (reads wiki/ + raw/). Without it, uses config.json vault.default_path or the repo demo content. |
Expected output
One line per hop: role, title, location; missing hops append (missing). A page with no provenance prints the page line plus (no further provenance).
page Demo wiki/entities/Demo.md
source Kickoff session wiki/sources/kickoff.md
raw Kickoff transcript raw/sessions/2026-01-01T12-00-demo-kickoff.md
Exit codes
| Code | Meaning |
|---|---|
0 |
Walk completed (including chains with missing hops). |
1 |
Starting page could not be resolved (or locator unsafe / empty). |
2 |
Configured --vault / default vault path is unusable. |
Use trace to inspect broken hops; repair them by hand or with synth / migrate broken-provenance as the lint message suggests. llmwiki doctor folds provenance findings into the heal flow and can run those repairs with consent (--check to diagnose only).
all — run the full pipeline
The one command to run after agent sessions land. It runs every stage in order — sync → synth → build → graph → lint — so a scheduled job is a bare llmwiki all rather than a trail of flags. AI-consumable exports (llms.txt, sitemap.xml, etc.) are written by build, not a separate step.
Every stage runs by default and every stage has an opt-out flag: --no-sync, --no-synth, --skip-graph, --skip-lint. synth is the only stage that can call an LLM; with the default dummy synthesis backend it makes no provider call at all, and --no-synth turns it off outright.
python3 -m llmwiki all # every stage
python3 -m llmwiki all --no-synth # no LLM calls
python3 -m llmwiki all --no-sync --no-synth # build → graph → lint only
python3 -m llmwiki all --graph-engine builtin # skip optional graphify
python3 -m llmwiki all --skip-graph --lint-fail warnings # fail CI on any lint issue
Flags
| Flag | What |
|---|---|
--out DIR |
Output dir for build. Default: site/. |
--search-mode {auto,tree,flat} |
Forwarded to build. Default: auto. |
--graph-engine {builtin,graphify} |
Forwarded to graph. Default: graphify. |
--no-sync |
Skip the sync step (do not convert new agent sessions first). |
--no-synth |
Skip the synth step, so the run makes no LLM calls. |
--synth-force |
Pass --force to synth (re-synthesize every session). |
--skip-graph |
Skip the graph step entirely (useful when graphify is not installed). |
--skip-lint |
Skip the lint step entirely. |
--lint-fail {never,errors,warnings} |
When lint findings fail the run with exit 2. Default: never. |
--strict |
Spelling for --lint-fail warnings. When both are given, the stricter wins. |
--fail-fast |
Stop at the first non-zero step (useful for demo-vault / unattended runs where nobody will open the static site afterward). Default: continue later stages — e.g. if synth fails after a successful sync, build still runs — and report the worst exit code. |
--with-sync, --with-synth |
Deprecated and inert — the stages they used to enable now run by default. Accepted so an already-installed scheduled command keeps parsing; each prints a one-line notice. |
--vault PATH |
Run every step against this vault instead of the repo. |
Lint failure policy
lint always prints its findings. --lint-fail decides whether those findings end the run:
| Policy | Fails when |
|---|---|
never (default) |
Never — findings are reported and the run still exits 0. |
errors |
Lint reported at least one error-severity issue. |
warnings |
Lint reported at least one error or warning. |
When --lint-fail fails the run (exit 2, unless an earlier step already set a non-zero code), the site HTML from the preceding build in this run is kept — lint does not undo or revert site/. Home surfaces the failure via Pipeline state (Last lint + banner); see ui.md.
Conflicting flags
--no-synth wins over --with-synth, and --no-sync wins over --with-sync, in any order on the command line — the deprecated --with-* aliases are inert and cannot re-enable a stage you just switched off. --strict and --lint-fail resolve to whichever of the two is stricter.
Exit codes — the first non-zero step's code wins, so a later lint failure never masks an earlier synth code:
0— every step succeeded.1— a step failed (for example a synth source error).2— the lint failure policy was met, or a required directory was missing.75— synth stopped on the backend's usage limit. Harvest,build,graphandlintstill run for the pages that landed; the deferred sources wait for the next run.130— synth was interrupted with Ctrl+C. Later stages still run for the pages that landed.
With --fail-fast, a synth stop harvests what landed and then ends the run with 75 / 130.
watch — near-real-time maintain when sessions finish
Polls adapter session stores on an interval and runs maintain when a session looks finished. Uses per-adapter turn-complete heuristics (Claude stop_reason, Cursor last role, Codex events). Mid-tool / permission loops stay deferred until the adapter reports safe. Adapters without a finished-signal still trigger after a 2s mtime settle — not a multi-minute quiesce.
Single-flight: only one maintain iteration at a time (sync → synth → build by default). Changes that arrive during a run set a dirty flag and retry after it finishes. Sync may time out (~180s); synth and build have no timeout.
python3 -m llmwiki watch
python3 -m llmwiki watch --adapter claude_code cursor
python3 -m llmwiki watch --interval 10 --settle 3
python3 -m llmwiki watch --dry-run
python3 -m llmwiki watch --no-synthesize --no-build
python3 -m llmwiki watch --vault ~/my-vault
Flags
| Flag | What |
|---|---|
--adapter NAME [NAME ...] |
Limit to / load specific adapters. Default: every ingest-ready coding-agent source with a present store and no enabled: false. Notes intake still needs enabled: true. See multi-agent-setup.md. |
--interval SECONDS |
Poll interval. Default: 5. |
--settle SECONDS |
Mtime settle before ready check for adapters without a finished-signal. Default: 2. |
--dry-run |
Detect finished sessions only; do not run maintain. |
--no-synthesize |
Skip the synthesize step. |
--no-build |
Skip the build step. |
--vault PATH |
Maintain this vault instead of the repo. |
install-automation — set up the daily job
Sets up the job that keeps your wiki current so you do not have to run the steps by hand. Interactive by default: it asks what the daily job should do, when it should run, and shows you the exact command line before writing anything. Pass --yes with the flags below for an unattended install.
What the daily job can do
| Job | What it does | Writes | Cost |
|---|---|---|---|
| Ingest only (default) | Collects new agent sessions into your vault and refreshes the site. | raw/, site/ |
Never contacts an AI provider — free. |
| Maintain | Collects new sessions, summarises each one into a wiki page, gathers candidate topics for review, refreshes the browsable site once per cycle at the build step after summarization, and reports wiki quality findings into the run log. A separate sync-only path (including optional Ingest automation) is a different concern — not “Maintain finished.” | raw/, wiki/sources/, wiki/candidates/, site/ |
Sends session text to your AI provider — this costs money once a real provider is configured. Run llmwiki synth --estimate to see how much before the job first fires. |
Optional extras (maintain only)
Nothing here is on by default; the wizard offers them as one comma-separated question and each has a flag.
| Extra | Flag | Effect |
|---|---|---|
| Build the knowledge graph | --graph builtin / --graph graphify |
The job also builds the graph, with the built-in builder or the richer graphify one (pip install llm-wiki-plus[graph]; the job falls back to the built-in builder until that extra is installed). Writes graph/. |
| Fail the job on quality errors | --lint-fail errors |
The scheduled job reports failure when the quality check finds errors. |
| Fail the job on quality warnings | --lint-fail warnings |
The scheduled job reports failure on any warning or error. Stricter than errors. |
Without a failure policy the quality check still runs and its full report lands in the run log — findings simply never mark the job as failed.
When it runs
The wizard offers presets and translates each into a cron expression; --schedule takes the same expression directly. Whatever the route, the schedule is validated before any unit file is written — an expression llmwiki cannot translate into your OS scheduler's own format is refused with the reason (exit code 2).
| Preset | Cron | Example |
|---|---|---|
| Every day | M H * * * |
"0 8 * * *" — every day at 08:00 (the default) |
| Weekdays only | M H * * 1-5 |
"30 7 * * 1-5" — weekdays at 07:30 |
| Once a week | M H * * D |
"0 18 * * 3" — Wednesdays at 18:00 |
| Custom cron expression | as typed | "0 */6 * * *" — every six hours |
Supported grammar is standard 5-field cron: *, integers, lists (1,15), ranges (1-5), steps (*/15), day names SUN–SAT, month names JAN–DEC. Nicknames (@daily), Vixie/Quartz extensions (L, W, #), a seconds field, and any expression restricting both day-of-month and day-of-week are refused — the last one because cron ORs those two fields and no OS scheduler can express it.
Linux systemd timers use Persistent=true so a missed run catches up once after wake (not every skipped day while the laptop stayed off). By default the installer writes rendered units to ~/.automation/, copies them into your OS scheduler (~/.config/systemd/user on Linux, ~/Library/LaunchAgents on macOS), and enables the job. Pass --no-activate to write unit files only and print manual enable commands. Each run appends to <vault>/.llmwiki/last-automation.log (truncated each run). .llmwiki/automation-status.json under the vault drives the Home Automation panel (settings only — job, schedule, cost/backend, hooks/watch, log path; Maintain notes that the site refreshes once after summarization) and records scheduler activation state. Stage completion times live under Pipeline state, not Automation. The wizard defaults to Maintain on Enter; choose 1 for ingest-only. Re-running replaces the existing job rather than adding a second one.
python3 -m llmwiki install-automation
python3 -m llmwiki install-automation --yes --job maintain
python3 -m llmwiki install-automation --yes --job maintain --graph builtin --lint-fail errors --schedule "0 8 * * 1-5"
python3 -m llmwiki install-automation --yes --job ingest --schedule "30 7 * * *" --units-dir ~/.config/systemd/user
python3 -m llmwiki install-automation --yes --job maintain --synth-backend ollama --watch-enabled
python3 -m llmwiki install-automation --yes --no-activate
python3 -m llmwiki install-automation --vault ~/my-vault
Flags
| Flag | What |
|---|---|
--yes |
Non-interactive: use the flags and defaults below; never installs hooks. |
--job {ingest,maintain} |
What the daily job does. Default: ingest. |
--graph {none,builtin,graphify} |
Build the knowledge graph, and with which builder. Default: none. |
--lint-fail {never,errors,warnings} |
Quality findings at this level report the scheduled job as failed. Default: never. Same spelling as the all flag. |
--schedule "<cron>" |
When the job runs, as a 5-field cron expression. Default: "0 8 * * *". An expression that cannot be translated exits 2 with the reason. |
--synth-backend NAME |
Synthesis backend for automation status (dummy / ollama / claude / cursor_cli). Interactive mode also writes synthesis.backend to config.json, after you confirm the summary. |
--units-dir PATH |
Staging directory for rendered unit files before OS activation. Default: ~/.automation/. Linux/macOS still install into the platform scheduler location unless --no-activate. |
--watch-enabled |
Set watch_enabled in automation status so the site Automation panel shows Watch: on (does not install or start llmwiki watch). |
--force-platform {linux,macos,windows} |
Override platform detection for unit format. |
--activate |
Copy units into the OS scheduler location and enable the job (default). |
--no-activate |
Write unit files only; print copy-paste enable commands. |
--vault PATH |
Vault the job runs against: automation-status.json is written under it, and the scheduled command carries --vault PATH whenever it differs from vault.default_path in config.json, so the job and its status file always mean the same vault. Omitted, the job resolves its vault from config. |
--profile {A,B,C} |
Deprecated — use --job. A maps to ingest, B and C to maintain. Prints a notice; --job wins when both are given. |
--hour N |
Deprecated — use --schedule. Translated to "{minute} {hour} * * *", and ignored with a notice when --schedule is given. |
--minute N |
Deprecated — use --schedule. See --hour. |
Exit codes:
0— the scheduler files were written (and activated unless--no-activate), or you answered n at the final confirmation (automation skipped; vault and config unchanged).1— scheduler activation failed (--activatedefault); status file recordsscheduler_error.2— the schedule is not an expression llmwiki can translate.
The installed wrapper script ends its log with EXIT:<code>, the scheduled command's real exit code, and exits with that same code — so the scheduler can tell a usage-limit stop (75) from a failure (1). Wrappers installed by an older release always logged EXIT:0; re-run install-automation to regenerate them.
Status file fields (under <vault>/.llmwiki/automation-status.json): in addition to job/schedule keys, activation adds scheduler_activated (bool), scheduler_backend (systemd / launchd / schtasks), scheduler_units_dir (install path), scheduler_active (read-back when available), and scheduler_error (string when activation failed).
Exit codes (conventions)
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Operation failed (user-visible error) |
2 |
Usage error (bad flags, missing file, etc.) |
75 |
Temporary stop: the synthesis backend's usage limit was reached (synth, all); retry after the reset |
130 |
Interrupted with Ctrl+C after a clean stop (synth, all) |
Subcommands document their own non-zero exit conditions where relevant (lint --fail-on-errors).
Related
- Slash commands — the
/wiki-*surface used from Claude Code. - UI reference — every screen + nav surface on the compiled site.
- Configuration · Full configuration reference.