Indexing: init, update, reindex

repowise init#

Generate the wiki for a codebase. Runs full AST parsing, graph analysis, git history indexing, dead-code detection, and page generation.

init never requires an API key. With a provider resolvable it writes the wiki with a model; without one it renders the whole wiki from the parsed structure and exits 0. See Deterministic wiki. A keyless run ends with one line naming what more is available: repowise generate writes the subsystem pages with a model (a key, or --provider ollama for a local model), and repowise reindex adds semantic search. repowise status prints the same line.

A logged-in Claude Code, Codex or OpenCode is offered with its plan quota, call count and time, Claude Code first. It is used only when you pick it or pass --provider, never by default.

repowise init [PATH] [OPTIONS]

repowise init                                     # current dir
repowise init /path/to/repo --provider anthropic
repowise init -x vendor/ -x 'src/generated/**'    # multiple excludes
repowise init --yes                               # non-interactive; no key needed
repowise init --yes --no-prose                    # guarantee no spend
repowise init --prose --provider anthropic        # write the subsystem pages as prose
repowise init --mode fast                         # very large repos: Index only
repowise init --test-run                          # 10 files, smoke test
repowise init . --yes --repos api,web             # workspace, two of its repos
repowise init --yes --no-prose --progress json    # agents and scripts

The plan screen#

repowise init on a terminal, with none of --provider, --no-prose, --mode fast, --resume or --yes, opens one screen: the repo scan, an ETA, the plan, and an opt-in model line with what a model adds and costs. Type a key and press Enter.

While it runs, init shows a checklist of every step with counts, time and what comes next. If the screen reads EOF (an agent piping stdin), init prints a notice and continues with defaults.

Cost gate. Before any tokens are spent, init shows the estimate and asks. With no terminal it declines, keeps the index, builds the documentation from code, and exits 2 naming --yes. The default answer is Yes up to $25 and No above that.

Exit codes#

A run whose page vectors fail to write (a real embedder, a broken LanceDB install) keeps its pages and full-text index, exits 2, and names the fix: reinstall, then repowise reindex. A workspace init exits 2 after saving every repo and names the repos with gaps. repowise update exits 1 on a failed embed.

Driving init from an agent or script#

repowise init --yes --no-prose --progress json writes only JSON lines to stdout; human text goes to stderr. Every line has v (schema version, 1) and event:

The summary's status is ready, degraded, interrupted or failed, matching exit 0, 2, 130 or any other code. mode carries key, label and run_mode; spend carries tokens and usd; restart_required means the editor needs a restart or /mcp to load the tools; next lists commands, repowise serve first.

Modes#

init, status and update name an index by its mode.

Semantic search sits on top of either documentation mode and is added with repowise reindex --embedder <name>. Every upgrade reuses the existing index and shows a cost estimate before any model call.

Provider, model and base URL#

Every command that calls a model, repowise serve chat and jobs, and the MCP server resolve the provider, model and base URL in one order. The first match wins:

1. --provider / --model, or a per-request choice in the web UI
2. provider, model and <provider>: {base_url: ...} in .repowise/config.yaml
3. the global default saved from the web UI settings
4. REPOWISE_PROVIDER / REPOWISE_MODEL and the provider's *_BASE_URL variable
5. whichever provider API key is set

Choosing a model or base URL for a repo in the web UI writes that repo's config.yaml, so the CLI picks it up. See Environment variables.

repowise update#

Incremental update for files changed since the last sync. Detects changed files via git diff, re-parses them, rebuilds the affected slice of the dependency graph, and regenerates the affected pages.

repowise update [PATH] [OPTIONS]

repowise update                          # incremental from current HEAD
repowise update --since main             # diff against main
repowise update --workspace              # all stale repos
repowise update --repo backend           # one workspace repo
repowise update --dry-run                # see what would regenerate
repowise update --working-tree           # bring uncommitted edits into the index
repowise update --full                   # Index only to a full index, no key
repowise update --full --provider anthropic   # straight to Written by <model>

A typical single-commit update touches 3 to 10 pages in under 30 seconds. A working-tree-only update skips the history and analysis phases: a 2-file edit on a small repository refreshes in about 4.5 s. MCP responses mark which served files carry uncommitted edits.

History depth. Git analysis reads the newest 5,000 commits by default, so churn, hotspots, co-change, Change Records and suspects cover a real span of history on active repositories. An index whose config.yaml records a lower commit_limit keeps it, and update names that value once; set commit_limit: 5000 there to read the wider window. The first update after raising it re-reads history once, with no model calls.

--full with a model configured is also the wholesale way to write the subsystem pages across documentation built from code. For a slice at a time, use repowise generate below.

repowise generate#

Write the subsystem (concept) pages with a model, on demand. This is the upgrade path for a repo indexed without a key: it fills the subsystem stubs with model prose, one page, one directory, or the whole concept layer at a time, each behind a cost estimate, and rewrites already-written pages. It writes only the model-written pages (the concept tree and the overview); naming a structural page such as a file page is an error, since those refresh on repowise update.

It reuses the persisted index. The graph and git metadata are rehydrated from SQL, so only the per-file parse and the generation for the pages you selected run. A provider is required here, and a missing one is an actionable error naming the key-setup path.

repowise generate [PATH] [OPTIONS]

repowise generate                     # every unwritten subsystem page, one cost estimate
repowise generate --path src/api      # just the subsystem pages under one directory
repowise generate --all               # rewrite the prose on every subsystem page

Selection names which subsystem pages to write, combined as a union: --unwritten / --all / --stale / --path / --page.

Run repowise generate with no selection flag on a terminal and it prints the wiki's state and writes every unwritten subsystem page behind a single cost estimate, asking about cascade only when it changes which pages get written. Piped runs, --yes, and flagged runs stay non-interactive with the same --unwritten default.

Cascade. Rewriting a subsystem page makes the pages that summarize it drift: its layer page, plus the repo overview, architecture and onboarding pages. --cascade none marks them stale, dependents (the default) also regenerates the overview and layer pages that summarize it, and full leaves nothing stale. The cost estimate includes the cascade fallout, so it does not under-quote.

Decisions a keyless index skipped. An index built without a model cannot read decisions from PRs, git history or code comments. The first generate (or update --full) with a model runs those lanes too and prices them on their own line of the estimate. repowise status shows a Decisions row while they are pending.

repowise reindex#

Rebuild the vector search index from existing wiki pages. No LLM calls, only embedding API calls. Fast and cheap. Use when you switch embedders, suspect FTS/vector drift, or want semantic search on an index built without an embedder. Every run names the embedder it uses.

repowise reindex [PATH] [OPTIONS]

repowise reindex
repowise reindex --embedder openai --batch-size 50

repowise restyle#

Switch a repo's wiki documentation style and regenerate every LLM page in the new voice. Reuses the persisted graph and git metadata (no re-blame); the only unavoidable rework is re-parsing files for ASTs, the same cost as repowise update --full. This is an LLM-generation command (a cost), unlike init/update/reindex above.

repowise restyle [STYLE] [PATH] [OPTIONS]

repowise restyle                        # show current style + available choices
repowise restyle caveman                # switch and regenerate every page
repowise restyle reference --yes --provider anthropic

STYLE is one of comprehensive, caveman, reference, tutorial. With no STYLE, prints the current style and exits.

repowise wiki-styles#

List the available wiki documentation styles, and which one the current repo uses.

repowise wiki-styles [PATH]

repowise wiki-styles