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 · doctor · 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 / #311)
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.
Every new import lands as one complete Markdown file (including long documents). Length-driven -01/-02 series are no longer written at add time (#311); synthesis chunks in memory instead, to the active backend's usable body budget (configuration.md § Choosing the document body budget). A converted document is capped at 512 KiB of Markdown: a larger one is rejected after conversion — also under --dry-run — and nothing is written, so split the source into smaller documents. Vaults that still hold older multi-piece raw layouts stay readable — use migrate whole-document-storage when you want one raw file + one wiki source page without a mass re-synth.
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. Site browsing still treats each base-slug under that folder as its own logical document (not one page for the whole project folder) — see ui.md. |
--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. It then cleans up the pages that cited the removed source pages (#277), rebuilds wiki/index.md, and appends a remove entry to wiki/log.md. Backlink blocks are left alone.
Cleanup covers every live page outside wiki/archive/, so lint --rules provenance_integrity stays clean afterwards:
- The removed slug is dropped from the page's
sources:list, inline (sources: [a, b]) or block (sources:followed by- alines). Pages keep their line endings (CRLF stays CRLF). A slug is skipped when another source page still has the same stem, and a[[link]]is skipped when another live page still answers to that name (stem or## Aliases). - A list item that is only a wikilink to a removed page (
- [[slug]],- [[slug|label]],- [[slug#anchor]]) is dropped from the page body. YAML frontmatter is never item-dropped (arelated:list keeps its item, with the link turned into plain text), and a## Connectionssection whose only bullets were dropped is left empty forlintor your agent to refill. - Any other wikilink to a removed page becomes plain text: its label when it has one, otherwise the name as written.
- A curated page under
entities/,concepts/,projects/,syntheses/orcandidates/that hadsources:and has none left moves towiki/archive/<same relative path>(under a UTC-timestamp folder when that name is taken), and links to it become plain text.index.md,hot.md,_context.mdand other system pages are trimmed but never archived. - An archived page's name is recorded in the dismissal ledger (
wiki/archive/candidates/dismissals.json, reasonarchived by remove: last citing source removed), soremovemarks the topic as settled:synthharvest andcandidateswill not re-propose it as a candidate even if you later add sources that mention it. The ledgerstubis the archived file relative towiki/archive/candidates/(a bare<name>.mdfor a candidate,../concepts/<name>.mdfor a page archived elsewhere).migrate dismissal-ledgerand an automatic rebuild keep these rows (reason included) for pages archived outsidearchive/candidates/; a candidateremovearchived rebuilds with an empty reason, its name still settled. - The dismissal ledger is checked before anything is deleted whenever a page is due for archiving: a corrupt
dismissals.jsonaborts the run with an error namingmigrate dismissal-ledgerand exit code 2, nothing removed. A page that cannot be read, written or archived later is listed on stderr (exit code 1) and in theremovelog entry while the remaining pages are still cleaned. - Nothing is annotated: no
## Contradictionsor review note is added for a fact that lost its citation.wiki/log.mdand its yearly archives are append-only history and are never rewritten, including when links to an archived page are unlinked. - Known limitation: dropping list items is fence-aware (lines inside fenced code blocks are left alone), but unlinking
[[…]]is not (the same limitation asrewrite_wikilinks), so a code sample on a citing page that contains a[[…]]to a removed page may still be rewritten.
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, plus each citing page and the pages that would be archived) 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.
doctor — heal the install and vault
Finds problems across the environment and vault, proposes repairs from the bundled heal catalog (llmwiki/doctor/heal_kb.json), and — with consent — runs those repairs. Default is the heal loop; --check / --dry-run are diagnose-only for scripts.
python3 -m llmwiki doctor
python3 -m llmwiki doctor --check
python3 -m llmwiki doctor --dry-run
python3 -m llmwiki doctor --error "wiki directory not found"
python3 -m llmwiki doctor --yes --error "rule=index_sync"
python3 -m llmwiki doctor --check --error "No module named 'markitdown'"
python3 -m llmwiki doctor --yes
python3 -m llmwiki doctor --kit-dest ~/.claude --check
python3 -m llmwiki doctor --vault /path/to/vault --check
Flags
| Flag | What |
|---|---|
| (default) | Heal loop: diagnose, confirm each automatic fix, apply, re-check. |
--check |
Diagnose only — print findings and suggested fixes; apply nothing (wins over heal apply even with --error). |
--dry-run |
Alias for --check. |
--error TEXT |
Look up one pasted symptom in the heal catalog (no full lint pass for the lookup itself). Matched runnable fixes still go through the same confirm / --yes path afterward unless --check. |
--yes |
Auto-apply safe fixes without per-item prompts; dangerous tiers still ask on a TTY (and are skipped on non-TTY unless confirmed later). |
--kit-dest DIR |
Optional agent-kit destination so area N (install_agent_kit) can diagnose / heal against that directory (same idea as install-agent-kit --dest). |
--vault PATH |
Operate on this vault root (must contain wiki/). |
Exit codes
| Code | Meaning |
|---|---|
0 |
Nothing actionable remains (healthy, or agreed fixes applied and re-check clean). |
1 |
Actionable problems remain (declined, failed, or still broken after re-check). |
2 |
Vault/config missing or unusable (no lint / no heal menu beyond configure/init guidance). |
Live detectors cover areas A–O (interpreter/extras, vault/config, adapters, synthesis backend, lint fold including index drift and provenance, overdue backlog, migrations, automation, site freshness, agent-kit, privacy). Catalog match and unknown-assist (--error) use the bundled heal KB; safe runners may apply under confirm or --yes, dangerous tiers (including synth) always need an explicit TTY confirm.
Automation findings (area L)
Doctor asks the OS scheduler (systemd user units, launchd agents, or Task Scheduler) which llmwiki schedules are installed and reads off each one the checkout it runs from and the vault it really serves. It checks the vault's own schedule (see install-automation) only when <vault>/.llmwiki/automation-status.json records a job; leftover schedules are reported on any vault. When a cause (unit_missing, points_elsewhere, checkout_missing) fires, not_active, stale_run and last_run_failed are not reported for the same vault. Doctor asks the scheduler whether a schedule is enabled only when the vault records a job; the leftover check reads the unit files alone.
| Finding | Severity | What it means | Fix |
|---|---|---|---|
automation.unit_missing |
error | The status file records a job, but the scheduler holds no schedule for this vault. | Doctor repair (reinstall). |
automation.points_elsewhere |
error | The schedule found for this vault (usually the legacy single llmwiki-maintain one) serves a different vault. |
Doctor repair: installs this vault's own schedule; the other vault keeps its own. |
automation.checkout_missing |
error | This vault's schedule runs from a checkout, or a wrapper script, that no longer exists. | Doctor repair, preferably from a pip-installed llmwiki. |
automation.not_active |
warning | The schedule exists but the timer is disabled, the launchd job is not loaded, or the task is disabled (or the status file records that activation did not happen). | Doctor repair (reinstall and activate). |
automation.stale_run |
warning | The schedule is installed but no run completed recently: it never ran within twice its interval since installed_at, or its last run is older than twice its interval. A run still in progress is not reported. Only a log written since installed_at counts as this schedule's run, and the shared ~/.local/state/llmwiki/last-automation.log older releases wrote counts only for the legacy single schedule or a schedule that names no log of its own. |
Read the run log, then doctor repair. |
automation.last_run_failed |
warning | The last run logged a non-zero EXIT: (the message names the log). A usage-limit stop (EXIT:75) is not a failure. |
Guided: read the named log and fix what the job reported; reinstalling the schedule does not help. |
automation.duplicate_legacy |
warning | The vault has its own schedule, but the legacy single llmwiki-maintain schedule still serves it too, so two jobs run against it (for example when install could not switch the old one off). |
Guided: run the removal commands doctor prints for the legacy schedule. |
automation.check_unavailable |
info | Doctor could not ask the scheduler (no systemd user session, missing launchctl / schtasks, unsupported platform), or the legacy schedule names no vault it can read, so the schedule is unchecked. |
Guided: check it by hand, or run doctor where the scheduler is reachable. |
automation.setup_outdated |
warning | This vault's wrapper predates run stamping (no LLMWIKI_SCHEDULED_RUN line), so Home cannot notice a missed run. |
Doctor repair (reinstall). |
automation.interpreter_missing |
error | The Python interpreter the wrapper runs no longer exists, so no scheduled run can start. | Doctor repair (reinstall from the Python you now use). |
automation.program_dir_missing |
warning | A folder recorded in program_dirs (where the job looks for the backend's CLI or the interpreter) no longer exists. |
Doctor repair (reinstall records where those programs are now). |
automation.orphan_unit |
warning | One or more schedules serve vault folders that no longer exist (for example after a vault was renamed or moved). One finding lists them all. | Guided: run the removal commands doctor prints for each; doctor never removes them itself. |
The doctor repair for the three error findings, not_active and stale_run runs python3 -m llmwiki install-automation --vault <vault> --yes --force --job <job> [--graph …] [--lint-fail …] --schedule "<cron>" [--synth-backend …] [--watch-enabled] [--units-dir …] from the llmwiki copy doctor itself runs from, reproducing the job, extras, schedule, backend, watch panel and a non-default unit staging directory the status file records. Agent hooks are not passed; the reinstall keeps the hooks the status file records. It is a dangerous-tier fix: before asking, doctor prints will run: <exact command>, runs from: <path> and, when that path is a git checkout or worktree, the development-copy warning. It runs only after you confirm on a terminal; doctor --yes alone prints the command and skips it.
When pipeline.backlog_overdue fires on a vault whose status file records a job, its message adds that scheduled maintenance may not be reaching the vault and points at the automation findings in the same report.
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, hollow_curated_pages. Findability (#197): page_findability, title_ambiguity, search_consistency. The live count is whatever llmwiki lint --help prints.
hollow_curated_pages (warning) flags a curated entity or concept page with no topic-graph edges and no renderable body (empty Key Facts once Connections/Sessions/Sources are omitted on topic pages). Fix by adding facts, merging, discarding, or removing the file — the demo vault is expected to lint clean on release.
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. Document source pages are checked too, since synth now writes their source_file: raw/docs/… claim (#307). Pages without those fields are skipped. The message names the missing hop and points at llmwiki trace plus a repair: synth for a missing source summary, migrate broken-provenance for a missing raw/sessions/ file, and llmwiki add (restore the document) or llmwiki remove (drop the orphaned page) for a missing raw/docs/ file. 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.
list prints every pending stub (or only stale ones with --stale). When a pending name near-matches one or more previously discarded subjects — not the same folded name harvest already excludes, and not a merge — the row gains an indented prior dismissals: block with one - "<DismissedName>" — <reason> line per hit, best match first (#146). An empty recorded reason shows as (discarded without explanation). Rows that remove recorded for pages it archived carry the reason archived by remove: last citing source removed and can surface as prior dismissals too. --json embeds prior_dismissals (list) and prior_dismissal (best match) with name, reason, ratio on matching rows only. Matching reads wiki/archive/candidates/dismissals.json (see migrate dismissal-ledger); it does not scan sibling *.reason.txt files for the mark.
discard archives the stub, records the decision (and --reason) in wiki/archive/candidates/dismissals.json, 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 / #146). New discards and merges do not write a sibling *.reason.txt. 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 (stored in wiki/archive/candidates/dismissals.json; shown on near-match list / candidates.html rows). |
--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 session, or for a queued document as many backend calls as the active synthesizer's usable body budget requires (#311) — chunks stay in memory, results are stitched into one wiki/sources/ page (Summary concat; Claims/Quotes exact-dedupe union; Connections union by target; tags unioned), and a mid-chunk failure fails the whole document rather than writing a complete-looking partial page. Vocabulary may include kind="entity|concept" when known (#257). Connections bullets name each topic with kind and nested fact: claims. New synth does not auto-delete legacy --part-* siblings left by older releases — leave that to migrate whole-document-storage.
Job 1 is known-names preparation (builds the vocabulary the source-summary prompts see, including kind). It caps how many candidate topics are sent (synthesis.known_names.candidate_cap, default 150 — highest reach first), uses a dedicated timeout (synthesis.known_names.timeout, default max(600, backend page timeout)), and skips or shrinks the call when the saved vocabulary already covers the capped set (#264). A name that titles a live wiki/entities/ or wiki/concepts/ page always stays that page's topic: the prepared vocabulary can fold other spellings onto it, but cannot drop it as noise or fold it onto a different page, and a page-less topic that only this page was folded into takes the page's name. How to choose the cap (what it bounds, cost/time, quality, and when exceeding ~150 means a large or noisy vault): configuration-reference § Choosing the known-names candidate cap. 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
python3 -m llmwiki queue status --id add-sync-1
Positional
| Value | What |
|---|---|
status |
Print queue counts, task-type breakdown, state path, and oldest pending timestamp. With --id <operation_id>, print one JSON object for that add (status, operation_id, retry_safe, written, errors, rolled_back, build_failed) and exit 0, or the unknown object and exit 1. |
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. |
--id ID |
With status: print one JSON object for that operation id and exit 0 when a queue row exists. When it does not, print one JSON object (status unknown, that operation_id, retry_safe false, plus a short message) and exit 1. Without --id, status keeps the human summary. |
--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 dismissal-ledger --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
python3 -m llmwiki migrate doc-source-provenance --vault /path/to/vault --dry-run
python3 -m llmwiki migrate whole-document-storage --vault /path/to/vault --dry-run
python3 -m llmwiki migrate session-tokens --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.
dismissal-ledger — rebuild dismissals.json from the archive (#146)
Candidate discard and merge decisions live in one vault file, wiki/archive/candidates/dismissals.json (pure dismissals and merge intents). New candidates discard / merge upsert that ledger only — they no longer write a sibling *.reason.txt. Near-match marks on candidates list and site/candidates.html, topic-vocabulary exclusion, and migrate discarded-topic-links all read the ledger.
This offline migration rebuilds (or imports) that file from archived stubs under wiki/archive/candidates/, from pages llmwiki remove archived elsewhere under wiki/archive/ (recorded with reason archived by remove: last citing source removed and stub ../<folder>/<name>.md, one row for the filename stem and one for a different frontmatter title), and from any legacy sibling *.reason.txt files still on disk. Prefer --dry-run first. Ordinary ledger reads also auto-rebuild when dismissals.json is missing and wiki/archive/ exists, so listing candidates or discarding after upgrade may create the file without an explicit migrate (a vault with no archive is read as an empty ledger and left untouched); this command is the operator path for a dry-run preview and for forcing a rebuild when a ledger already exists but the archive has changed. No language model, no network call, raw/ never written. Idempotent: a second apply against an unchanged archive reports no change.
Implementation: llmwiki/migrate_dismissal_ledger.py. Legacy *.reason.txt files may remain on disk after import; they are not deleted automatically. Rebuild the site afterwards if you want candidates.html to show near-match marks from the rebuilt ledger: llmwiki build --vault PATH.
python3 -m llmwiki migrate dismissal-ledger --vault /path/to/vault --dry-run
python3 -m llmwiki migrate dismissal-ledger --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing wiki/. |
--dry-run |
Report dismissals/merges that would be written; write nothing. |
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. Merge intent comes from the dismissal ledger (dismissals.json); run migrate dismissal-ledger first if the vault still only has legacy *.reason.txt and no ledger yet. 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 the dismissal ledger records as 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.
doc-source-provenance — fill blank claims on document pages (#307)
Releases before #307 synthesised every wiki/sources/ page from raw/docs/ with a blank source_file: and stamped it session-transcript. Re-synth fills the claim but keeps the stale tag. This offline migration, with no language model and no network call:
- Walks
raw/docs/and derives each doc's page path the way synth does (wiki/sources/<project or docs>/<date>-<slug>.md, plus any--part-NNpages on disk). - Fills a blank
source_fileon that page with the claim synth writes today:raw/docs/<path>, or the raw doc's ownsource_filewhen it declares one. - On every page identified as a document — by that match, by a
raw/docs/claim, or by araw-doc/wiki-addtag — removessession-transcriptfromtags:(inline or block list) and addsraw-docwhen neither document tag is left. Stub pages are included. - Reports a blank-claim page that two raw docs derive to as ambiguous and leaves it unchanged; reports a doc-tagged page no raw doc derives to as unmatched and leaves its claim blank.
- When anything changed, refreshes the synth backlog and appends a
migrate | doc source provenanceentry towiki/log.md.
A page whose source_file names raw/sessions/ is never touched, and raw/ is never written. Run it before source-page-paths, which only moves pages that already claim a raw file. Implementation: llmwiki/migrate_doc_source_provenance.py.
python3 -m llmwiki migrate doc-source-provenance --vault /path/to/vault --dry-run
python3 -m llmwiki migrate doc-source-provenance --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing wiki/ and raw/. |
--dry-run |
Report claims filled, tags stripped, raw-doc added, ambiguous and unmatched pages; write nothing. |
Idempotent: a second run changes nothing. With no ambiguous or unmatched pages left it prints nothing to migrate: every document source page already claims its raw file; otherwise it lists them again with zero pages touched.
whole-document-storage — merge legacy split documents (#311)
Before #311 a long add could land as raw/docs/<project>/<slug>-01.md … <slug>-NN.md and be summarised into one wiki source page per piece. New imports are one raw file and one summary page. This offline migration turns each clear multi-piece document in an existing vault into that same shape — no language model, no network call, and no mandatory mass re-synthesis.
- Groups raw
-NNpieces that share a directory and the#305base slug, carry(part i/N)markers, form a contiguous1..Nrun, and either share one non-emptycontent_sha256or all lack the field (pre-hash imports). Conflicting non-empty hashes or a mix of empty and non-empty stay ambiguous. Wiki pages come from each piece's derived name and fromsource_file:claims. - Lists every ambiguous group in the preview (gap in parts, hash conflict, a whole
<slug>.mdthat is not the same document or cannot be read, a frontmatterproject/datethat is not a safe path segment such as../escape, a path that resolves outsideraw/docs/wiki/sources, partly summarised pieces, inconsistent wiki claims, and similar). Apply exits non-zero and changes nothing for the whole vault while any ambiguous group remains (clear groups are not applied either). - For each clear group: writes
raw/docs/<project>/<slug>.mdwhen missing (part breadcrumbs stripped; legacy hash kept when present, otherwise computed from the joined body like a new import) by exclusive create, and never overwrites an existing whole file — a different-hash one, or one that is present but cannot be read as UTF-8 Markdown (both ambiguous). Relocates the old-NNraw files under.llmwiki-whole-doc-recovery/<UTC>/raw/docs/…. - Stitches the pieces' wiki summaries with the same deterministic rules new synth uses, unions tags, records old part names under
## Aliases, rewrites[[wikilinks]]/sources:entries, and moves the old part pages under.llmwiki-whole-doc-recovery/<UTC>/wiki/sources/…. AMANIFEST.jsonin that recovery directory lists every move. -
Collapses per-piece synth state keys to the whole-document key, refreshes pending, rebuilds
wiki/index.mdwhen the vault keeps one, and appends a migrate log entry when anything changed. -
Optional re-synth queue. After a successful apply the command lists the merged documents. On a terminal it asks once for all of them whether to mark them not synthesized; the default (Enter, EOF, or any non-terminal run without flags) keeps the stitched summaries and the synth-done state unchanged.
--mark-unsynthanswers yes without asking. Either way migrate only edits synth state — re-summarising happens later, when you runllmwiki synth.
After a successful apply (and a site rebuild), Ctrl+K Wiki / the wiki search corpus list one source row per logical document instead of many --part-N pages. Operators may still force-re-synth later; that is optional, not the migration success path.
Implementation: llmwiki/migrate_whole_document_storage.py. See UPGRADING.md.
python3 -m llmwiki migrate whole-document-storage --vault /path/to/vault --dry-run
python3 -m llmwiki migrate whole-document-storage --vault /path/to/vault
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing raw/docs/ and wiki/. |
--dry-run |
Preview clear and ambiguous groups; write nothing (apply is blocked while any group is ambiguous). |
--mark-unsynth |
After a successful apply, mark every merged document as not synthesized (drops its whole-document synth-done key and refreshes pending) so the next llmwiki synth re-summarises it. No prompt, no language-model call here — for scripts. Ignored by --dry-run; nothing happens when apply is blocked or errored. |
--keep-stitched |
Keep the stitched summaries and synth state without asking. This is the default; the flag is an explicit no-op (also suppresses the terminal question). Mutually exclusive with --mark-unsynth. |
Idempotent: a clean second run is a no-op; an interrupted apply resumes. Rebuild afterwards: llmwiki build --vault PATH.
session-tokens — backfill Analytics session Tokens (#325)
Steady-state sync only writes session Tokens for new or fingerprint-changed origin sessions (cheap no-ops otherwise). After upgrading to the session Tokens usage store, already-synced sessions would stay missing from usage/session-tokens.json and may lack token_totals in raw frontmatter unless you run this one-shot migrate.
- Seeds the usage file from existing
raw/sessions/*.mdwhentoken_totalshas at least one non-zero bucket (agent from frontmatter tags such ascursor-cli/claude-code, after loading the full adapter registry). All-zero / missing totals are skipped — they do not inflate coverageknown. Sessions that sync would filter (lookback / headless / subagents) still count when they have measurable usage — same metrics-without-raw policy as steady-statesync. - Re-reads capable agent stores still on disk (Claude Code, Codex CLI, Cursor CLI, …) using
config.jsonadapter settings, to map real turn usage into the four buckets, patch raw frontmatter when a matching session page exists, and upsert the usage file (including metrics-only rows when usage is measurable but no raw page exists). Origin sessions with empty totals are skipped the same way as raw seed. - Refreshes slim public
site/session-tokens.js(aggregates only) when the vault already has asite/tree — Analytics Tokens can then update without a full HTML rebuild.
Cursor Agent turn usage: store.db message JSON does not carry input/output/cache turn fields. Install the IDE hook with python3 -m llmwiki.cursor_token_events --install-hook (writes a POSIX /bin/sh stop handler into ~/.cursor/ and merges hooks.json; or ingest Agent CLI stream-json via --ingest-stream-json FILE). Events land in ~/.cursor/llmwiki-cursor-token-events.jsonl; sync and migrate join by conversation_id (= chat agentId). Do not invent totals from context-window occupancy. Prefer --dry-run first. See state-persistence.md and UPGRADING.md.
python3 -m llmwiki migrate session-tokens --vault /path/to/vault --dry-run
python3 -m llmwiki migrate session-tokens --vault /path/to/vault
# Fast Codex-only origin backfill (#324):
python3 -m llmwiki migrate session-tokens --vault /path/to/vault --adapter codex_cli --skip-raw
| Flag | What |
|---|---|
--vault PATH |
Required. Vault root containing raw/sessions/ and usage/. |
--dry-run |
Report would-upsert / would-patch counts; write nothing. |
--adapter NAME |
Limit origin re-read to this adapter (repeatable). Default order: codex_cli, claude_code, cursor_cli. |
--skip-raw |
Skip seeding from raw/sessions frontmatter; only re-read selected adapter origins. |
Idempotent. Rebuild afterwards: llmwiki build --vault PATH (or open Analytics after sync has refreshed the sidecar).
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 beside itself before the kit version is written: <filename>.bak first, then <filename>.bak.1, <filename>.bak.2, … if .bak already holds a different rescue copy (#224). If the file about to be overwritten already matches .bak, no duplicate is written. The report names the path used. |
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 for the same vault replaces that vault's own schedule rather than adding a second one; installing for another vault adds a separate schedule and leaves the first one alone.
One schedule per vault. Each vault gets its own scheduler unit, named from the vault folder's name plus a short hash of its resolved path: llmwiki-maintain-<slug>-<hash> on Linux (.sh / .service / .timer) and Windows (task name, plus <name>-task.xml), com.llmwiki.maintain.<slug>-<hash> on macOS (launchd label and .plist). The same vault path always gets the same name, so re-installing overwrites it, and two vaults never share one. The scheduled command always names its vault with --vault <vault>, so changing vault.default_path in config.json later never moves an installed schedule to another vault — run install-automation --vault <new vault> for that. A schedule installed by an older release under the single name llmwiki-maintain / com.llmwiki.maintain is adopted on the next successful install for the vault it serves: the installer switches it off, deletes its files, and prints Replaced the earlier single llmwiki-maintain schedule with this vault's own schedule. A legacy schedule that serves another vault, or whose vault cannot be read off it, is left alone. If switching it off fails, the install still succeeds, the error is recorded in legacy_adopt_error, and the installer prints the commands to remove it by hand.
When the chosen synthesis backend is claude and neither nested synthesis.claude.path nor flat claude_path is already set, the installer resolves claude under its own environment and writes the absolute path into synthesis.claude.path (#275). That pin keeps scheduled Maintain working when systemd catch-up runs with a minimal PATH that omits <home>/.local/bin. An existing explicit path is left alone; if Claude cannot be found at install time the install still succeeds with a warning.
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. |
--force |
Replace this vault's existing schedule even when it runs llmwiki from a different checkout, without asking. The "runs from" lines and any development-copy warning still print. |
--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 (dummy / ollama / claude / cursor_cli). Written to automation status and to synthesis.backend in config.json (interactive: after you confirm the summary; --yes: on install). When the backend is claude and no path is already set, also pins absolute synthesis.claude.path from the installer's PATH (#275). |
--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, the unit name is derived from it, and the scheduled command always carries --vault <resolved PATH>, so the job and its status file always mean the same vault. Omitted, the vault is vault.default_path from config.json, resolved at install time and pinned the same way. |
--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. |
Guard and development-copy warning. Before writing anything, install-automation looks for a schedule that already serves this vault. When that schedule runs llmwiki from a different checkout, it prints current schedule runs from: <path> and new schedule would run from: <path>; on a terminal it then asks Replace it? [y/N] (Enter keeps the existing schedule), and with --yes it stops with install-automation: existing schedule runs from a different checkout; pass --force to replace it (exit 2) unless you pass --force. When the scheduler cannot be asked, there is nothing to compare and the install proceeds. Installing from a git checkout of llmwiki prints warning: installing from a development checkout — … (or warning: installing from a git worktree — … for a worktree), because the scheduled job keeps using that copy and breaks when it is deleted, switched, or removed; the warning prints with --yes and --force too.
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), or you answered n to replacing a schedule that runs from a different checkout.1— scheduler activation failed (--activatedefault); status file recordsscheduler_error.2— the schedule is not an expression llmwiki can translate, or--yeswithout--forcefound this vault's schedule running from a different checkout.
Finding programs and stamping runs (#374). The scheduled job does not start from a terminal, so before running llmwiki the wrapper reads the login profile (~/.bash_profile, ~/.bash_login or ~/.profile, the first that exists, then ~/.zprofile through zsh when zsh is installed) in a child shell — stdin closed, at most 30 seconds where a timeout command exists (macOS ships none, so there the wait is unbounded), errors and output ignored — and keeps only the PATH it builds; ~/.bashrc / ~/.zshrc lines after an interactive-only guard are not read, which is what the recorded program folders cover; a profile that exits, fails or hangs cannot stop the job. It then puts in front the folders of the programs the vault's synth backend runs (claude; agent / cursor-agent) and of the interpreter, as found on the installing shell's PATH — the launcher's own folder, not the version a launcher symlink points at — recorded in the status file as program_dirs. It never copies the whole install-time PATH. With the claude backend and no synthesis.claude.path set, the path written there is the launcher too (~/.local/bin/claude), so a Claude Code self-update that deletes old versions does not break it. The wrapper also exports LLMWIKI_SCHEDULED_RUN=1; a run started that way stamps its end time and exit code into llmwiki-state.json (outcomes.scheduled), and an activated install records the schedule's interval there, which is how the Home problems banner tells a missed run. Re-run install-automation once after upgrading so an older wrapper gains these lines — until then Home shows Schedule — setup outdated and doctor reports automation.setup_outdated.
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, every install records scheduler_unit (this vault's unit base name, llmwiki-maintain-<slug>-<hash>), working_dir (the llmwiki checkout or install the job runs from), target_vault (the resolved vault the scheduled command names), adopted_legacy (true when this install switched off the legacy single schedule) and legacy_adopt_error (string when that failed, else null). Activation adds scheduler_activated (bool), scheduler_backend (systemd / launchd / schtasks), scheduler_units_dir (install path), scheduler_active (read-back when available), scheduler_error (string when activation failed), and installed_at (UTC timestamp, reset on every successful activation and kept otherwise; llmwiki doctor measures a schedule that never ran from it).
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.