llmwiki-cli

English | 日本語

Standalone CLI for llmwiki, runnable outside of Claude Code.

Requirements

• Python 3.12+
• Claude Code installed and on PATH — the Agent SDK spawns the claude binary as a subprocess. Install via:

  npm install -g @anthropic-ai/claude-code
  

  or follow the native installer at https://claude.com/claude-code.

Authentication

Primary: CLAUDE_CODE_OAUTH_TOKEN (recommended).

claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...

A one-year long-lived OAuth token that uses your Claude Pro / Max / Team / Enterprise subscription quota. No per-call API billing.

Fallback: ANTHROPIC_API_KEY (API billing) — issued at https://console.anthropic.com.

Resolution order: CLAUDE_CODE_OAUTH_TOKEN > ANTHROPIC_API_KEY.

Run

uvx (recommended, no install)

uvx llmwiki-cli lint
uvx llmwiki-cli ingest
uvx llmwiki-cli query "your question"
uvx llmwiki-cli docs "theme" -o out.md

Each run uses a fresh isolated environment. The first invocation resolves dependencies; subsequent runs start instantly from the uv cache.

uv run (as a project dependency)

For a project that declares llmwiki-cli in its pyproject.toml:

uv run llmwiki-cli lint

One-off usage without declaring the dependency:

uv run --with llmwiki-cli llmwiki-cli lint

Before publication / straight from the repo

Prior to PyPI release:

uvx --from . llmwiki-cli lint                                                  # local checkout
uvx --from git+https://github.com/ktrysmt/llmwiki-cli llmwiki-cli lint         # Git
uvx --from git+https://github.com/ktrysmt/llmwiki-cli@v0.1.0 llmwiki-cli lint  # pinned tag

Persistent install

uv tool install llmwiki-cli
# or
pipx install llmwiki-cli

Commands

llmwiki-cli ingest [path]                      # import + lint + fix pipeline
llmwiki-cli lint                               # read-only health check
llmwiki-cli query "question" [--write]         # natural-language query over the wiki
llmwiki-cli docs "theme" [-o out.md]           # single document
llmwiki-cli docs "theme A" "theme B" -o dir/   # multiple themes in parallel

--write on query enables the feedback loop: the LLM proposes relationship additions, new entities, contradiction flags, dormant promotions, and synthesis saves. All proposed items (4a-4e) are auto-applied without per-item confirmation.

Internals

Resolution order for the deterministic scripts (llmwiki-preprocess / llmwiki-makeindex / llmwiki-decay):

1. Bundled inside the installed wheel at llmwiki_cli/resources/bin/
2. PATH (when the llmwiki Claude Code plugin is installed)
3. Repository bin/ (for editable dev checkouts)

Under uvx / uv run everything resolves via (1), so users do not need anything beyond the CLI itself (except claude).

The wiki page schema is bundled at llmwiki_cli/resources/schema.md and embedded into LLM system prompts for Phase 1 / 3 / 4 of ingest and for query --write.

Release

Build, publish, and release shortcuts are provided via Makefile. Requires UV_PUBLISH_TOKEN (from https://pypi.org/manage/account/token/) exported in the current shell.

make build                       # build wheel + sdist into dist/
make publish                     # build + upload to PyPI
make release VERSION=0.1.1       # bump pyproject.toml, commit, tag, publish, push
make tag VERSION=0.1.1           # git tag only (no publish)
make verify                      # sanity-check via uvx --no-cache
make clean                       # remove dist/
make help                        # list targets

make release aborts if the working tree is dirty. It edits pyproject.toml, creates a v<VERSION> tag, publishes to PyPI, and pushes both the commit and tag to origin.

Changelog

v0.2.0

• ingest: added stats-based early-exit when there are no new/updated/missing files, no contradictions, and no decay candidates
• ingest: added a synthesis quality check after Phase 1 that reviews the top 3 updated pages for bidirectional Relations and Source Files table correctness, and applies fixes in-place
• ingest, lint, docs: now append a ## [YYYY-MM-DD] <cmd> | ... entry to .llmwiki/log.md at the end of each run
• lint: expanded the system prompt to explicitly enumerate every report category (orphan, broken links, stale, uncovered, contradictions with urgency tiers, decay, promotion, cross-entity, contradiction stats, provenance gaps)
• query --write: removed per-item confirmation — 4a–4e are all auto-applied (matches the updated plugin policy)

v0.1.0

• Initial release: ingest, lint, query, docs commands
• Auth via CLAUDE_CODE_OAUTH_TOKEN (preferred) or ANTHROPIC_API_KEY fallback
• Deterministic scripts bundled into the wheel at llmwiki_cli/resources/bin/; schema embedded at llmwiki_cli/resources/schema.md

License

MIT