Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
CLI Reference
Every repowise command and flag. For a guided introduction, see the Quickstart.
Top-level commands (alphabetical): agents, ask, attribution, augment, changes, check, ci-summary, components,
config, context, corrections, costs, coverage, dead-code, decision, delete, distill, doc-drift,
doctor, events, expand, export, generate, generate-claude-md, health, hook, impacted-tests, init,
login, logout, mcp, next, overlap, packages, plugins, publish, reindex, report, restyle, risk,
saved, savings, search, security, serve, status, suspects, symbol, telemetry, uninstall, update,
watch, whats-new, whoami, why, wiki-styles, workspace. repowise --version prints the version.
repowise-augment and repowise-rewrite are separate console scripts (hook entry points, not run by hand).
Do you need an LLM key? Usually not; most commands only read the index.
initnever needs one: it calls an LLM only with a resolvable provider or--prose, else renders from structure.- LLM callers:
update(unless--index-onlyor--no-docs),generate,restyle,watch(when it regenerates a page),health --generate-code,workspace add --docs. - Index-only, no provider: everything else (
search,dead-code,doc-drift,health,risk,impacted-tests,decision,coverage,security,export,mcp,reindex,doctor, ...).
Contents
Grouped by task; PATH and flags are in each command's section.
- Indexing:
init,update,generate,restyle,wiki-styles,watch,reindex - Querying:
search,ask,context,symbol,why, sharedask/context/symbol/whyoptions,status,next - Health and risk:
health,health check,risk,overlap,dead-code,doc-drift,security,check,ci-summary,impacted-tests,coverage,components,packages,changes,suspects,events,report assessment,report estate - Decisions:
decision - Agent wiring:
agents,generate-claude-md,AGENTS.md,attribution - Hooks and distill:
distill,expand,saved,savings sync,corrections,hook install,hook status,hook uninstall,hook stats,hook backfill,hook rewrite,hook read-skeleton|search-digest|read-reread,hook health-gate,augment - Server:
serve,mcp - Workspace:
workspace list,workspace add,workspace remove,workspace scan,workspace update,workspace set-default,workspace diagnostics,workspace check,workspace metrics,workspace impacted-tests - Maintenance:
doctor,grammars fetch,whats-new,telemetry,plugins,config hints,login,logout,whoami,publish,delete,uninstall,costs,export
Workspace auto-detect (cross-cutting)
Most commands detect a workspace root and route to it, with a one-line [workspace] … notice.
A command that reads one repo (health, dead-code, events, next, doc-drift, coverage,
decision, impacted-tests, costs without --all) names it: [workspace] health reads one repo: carts (primary) of 5 in sockshop; pass --repo <alias> for another.
| Flag | What it does | Default |
|---|---|---|
--workspace / -w |
Force workspace mode; errors without .repowise-workspace.yaml. |
auto-detect |
--no-workspace |
Force single-repo mode. | auto-detect |
--repo <alias> |
Scope to one repo, where sensible. | all repos or primary, per command |
--all |
Fan out across every repo (costs, search). |
off |
--workspace:update,status,watch,doctor,generate-claude-md,hook(install, status, uninstall, rewrite, read-skeleton, search-digest, read-reread),report assessment/inventory/changes.--no-workspace: those, plussearch,dead-code,doc-drift,costs,health,next,mcp,ask,context,symbol,why.--repo:update,report, and the--no-workspaceextras exceptmcp.
Core Commands
repowise init [PATH]
Index a codebase and generate its wiki; the starting point.
repowise init # interactive
repowise init --provider codex_cli --codex --yes # authenticated Codex CLI
repowise init --no-prose -x vendor/ -x "*.gen.go" # free, wiki from structure
repowise init --provider openai --yes --no-save-key # CI: key never on disk
repowise init . --yes --repos api,web # workspace dir, two of its repos
Phases. (1) Ingestion: tree-sitter ASTs, file and symbol dependency graph, git history (churn, hotspots, ownership,
bus factor). (2) Analysis: dead code, decisions (inline markers, READMEs, git), Leiden communities, execution flows. (3)
Generation: file, module, repo pages (LLM, or structure with --no-prose). (4) Persistence: .repowise/wiki.db, search
indexes, editor files, MCP server, hooks.
Workspaces add repo scanning, per-repo indexing, cross-repo analysis (co-changes, contracts, package deps), workspace CLAUDE.md.
Model, content and scope
| Flag | What it does | Default |
|---|---|---|
--provider |
anthropic, openai, openrouter, gemini, deepseek, kimi, ollama, litellm, codex_cli, copilot_cli, claude_cli, opencode, edenai, mock. Terminals prompt for a missing key (openai: plus optional compatible base URL). |
from environment |
--model |
Model (e.g. claude-sonnet-4-6). |
provider default |
--embedder |
gemini, openai, openrouter, ollama, edenai, mock. |
auto-detect |
--prose / --no-prose |
The one LLM-spend knob; see notes. | prose when a key exists |
--index-only |
Deprecated hidden alias of --no-prose. |
|
--docs |
Deprecated hidden alias: llm = --prose, deterministic = --no-prose. |
|
--mode |
standard, or fast (graph and essential git; no per-file blame, co-change or LLM docs; for very large repos; upgrade with update --full). |
standard |
--reasoning |
auto, off/none, minimal, low, medium, high, xhigh, max (supported providers). |
auto |
--concurrency |
Max concurrent LLM calls. | 10 |
--wiki-style |
comprehensive, caveman (token-condensed, AI-first), reference (API manual), tutorial (beginner). Saved for update. WIKI.md. |
comprehensive; interactive full runs prompt |
--language |
en, ar, de, es, fr, hi, it, ja, ko, nl, pl, pt, ru, tr, zh. Saved for update. Code, paths, symbols untranslated. Advanced mode asks. Switch: init --force. |
en |
--onboarding / --no-onboarding |
Onboarding collection (up to 8 pages); see notes. | on |
--max-file-pages |
File-page cap by importance; 0: no cap, a page per eligible file. Saved to config.yaml. |
size policy (Page volume) |
--folder-coverage |
GLOB=PCT file-page floor for a folder, repeatable: src/core=1.0 gives every eligible file under src/core a page whatever the cap. Adds pages, never displaces. Saved as folder_coverage in config.yaml. |
none |
--test-run |
Model docs for top 10 files by PageRank. Not with --no-prose or --mode fast. |
off |
--dry-run |
Plan and cost estimate; no wiki. | off |
--exclude / -x |
Gitignore-style pattern. Repeatable. | |
--skip-tests |
No docs for test files. | off |
--skip-infra |
No docs for infra (Dockerfiles, Makefiles, Terraform). | off |
--include-submodules |
Include git submodules. | excluded |
--coverage-report |
LCOV, Cobertura, Clover, JaCoCo, Go coverprofile, Salesforce Apex JSON. Repeatable. Feeds code health only; every code file is documented regardless. | auto-discovered |
--commit-limit |
Max commits per file and for co-change; cap 10000. Saved. | 5000 |
--follow-renames |
Track renames via git log --follow (slower, more accurate). Saved. |
off |
--resume |
Continue a previous run; see notes. | off |
--force |
Regenerate all pages; see notes. | off |
--seed-from |
Explicit base checkout to seed from; rarely needed (linked worktrees auto-seed). WORKTREES.md. | auto-detected base |
--no-seed |
Full init even in a linked worktree. | seeding on |
Agent wiring and running
| Flag | What it does | Default |
|---|---|---|
--no-claude-md |
Skip CLAUDE.md; saves editor_files.claude_md: false. |
generated |
--agents / --no-agents |
Managed Codex AGENTS.md. Persists. |
config, else on |
--codex / --no-codex |
Project-local Codex MCP and hooks. Required for non-interactive runs. | prompt if Codex CLI is logged in |
--distill-hook / --no-distill-hook |
Distill hooks (Claude Code PreToolUse) compacting what the agent sees; notes, DISTILL.md. | off; interactive prompt (default No) |
--hook / --no-hook |
Post-commit repowise update hook; see notes. |
on |
--editor-setup / --no-editor-setup |
Editor wiring; see notes. | on |
--save-key / --no-save-key |
Save the run's key to .repowise/.env (git-ignored, owner-only); see notes. |
on |
--yes / -y |
No plan screen, all defaults; see notes. | off |
--all |
Folder of repos: index all (as do --yes and piped stdin, printing the repos taken). |
picker |
--repos |
Folder of repos: only these (api,web); see notes. |
picker |
--no-workspace |
Index only PATH from a workspace root. | auto-detect |
--progress |
rich: live checklist (TTY), else one line per step (max 100 columns). json: JSON event lines on stdout, ending in a summary. |
rich |
--no-cost-tracking |
Skip DB-backed LLM cost tracking. | tracking on |
-v, --verbose |
Per-phase internals, debug logs (else debug and info logs are suppressed). | off |
Flag notes
--prose/--no-prose. File, symbol, cycle (SCC), API, infra pages: always from structure, free.- Model set: subsystem (concept) tree, repo overview, architecture diagram, onboarding.
--prosewrites it (key needed);--no-proseleaves stubs. --no-prosemakes no model calls even with a key, so decision extraction from PRs, commits and comments waits;repowise generatefills both later.- Full-text search always; semantic search needs an embedder.
- Model set: subsystem (concept) tree, repo overview, architecture diagram, onboarding.
--onboarding. Slots: Project Overview, Architecture Guide, Getting Started, Codebase Map, Key Concepts, How It Works, Development Guide, Active Landscape; thin ones skipped.--resume. No-op when fully indexed. Skips done phases (indexing, analysis), keeps the git tier, writes only missing pages, never paying twice: for interrupted runs or failed pages (outage, rate limits). Per-page matching survives provider switches.--force. Re-indexes from scratch in the invoked mode, skipping worktree seeding. Never calls a model (--force --no-prosere-renders free);repowise update --fulldoes.--distill-hook. One consent, four behaviours: noisy commands (tests, builds, git, searches) run throughrepowise distill; whole-file Reads return a skeleton (hooks.read_skeleton); many-file greps a per-file digest (hooks.search_digest); re-reads of unchanged, unedited files a pointer (hooks.read_reread).--no-distill-hookalso gates the repo off in config, keeping a global hook inert.--hook. Asked interactively;--yesand non-interactive runs install it, printing the undo (repowise hook uninstall).- Workspace.
--distill-hookand--hookapply to every selected repo. --editor-setup. Machine-wide: Claude Code (~/.claude/settings.json) and Claude Desktop MCP entry, Claude Code PostToolUse/SessionStart hooks. Repo:.mcp.json,.claude/CLAUDE.md,.vscode/mcp.json,.vscode/extensions.json.--no-editor-setup. Writes only.repowise/(scratch checkouts, throwaway venvs, worktrees, CI); skips the post-commit hook (git hooks dir) and--distill-hookoffer (user-level hook).- One
repowiseMCP key per config, so a secondinitrepoints it;repowise mcp .prints config for manual setup. --no-distill-hook,--no-claude-md,--no-agentsstill save to repo config: they mean "never".REPOWISE_SKIP_EDITOR_SETUP=1: same switch, beats--editor-setup.
- One
--save-key. On so scriptedinitleaves an answering MCP server (env keys die with their shell). Read byrepowise mcp,serve,update; without itget_answerdegrades tono-llm-provider(retrieval-only).--no-save-keyorREPOWISE_NO_SAVE_KEY=1for per-process keys (CI secrets, shared machines); a No at the key prompt also wins.- Adds a
.gitignoreline, so use--no-save-keyfor--no-editor-setup's nothing-in-the-repo guarantee.
--yes. Model docs only with a configured provider (key in env or.repowise/.env), else from code; logged-in Claude Code, Codex or OpenCode needs--provider;--no-proseguarantees no model calls.- Accepts the cost prompt; advanced defaults (standard mode at any size, comprehensive style); connects detected agents; repoints the global MCP entry here, printing old and new.
- Installs the post-commit hook, not distill. With
--no-prose, replaces model-written docs unasked.
--repos. Alias, directory name, or relative path (for duplicates). First listed is a new workspace's primary; existing ones keep theirs. Unknown names stop the run, listing options.
Plan screen. TTY runs without --provider, --no-prose, --mode fast, --resume or --yes show scan, ETA, plan,
and an opt-in model line (adds, costs). EOF (agent-piped stdin): notice, then defaults. Keys:
- Enter: free run (docs from code).
m: pick a model.s: leave the global MCP entry.q: quit. e: edit plan (advanced options, agent checklist, post-commit hook,.git/info/excludefor machine-specific files, off).r: folder of repos (listed): pick repos and primary.
Page volume. File pages cost no tokens; caps cut wiki size, embeddings, retrieval noise. Thresholds from real repos:
- Over 2,000 documentable files (p95): the
estep offers the top 2,000 by importance, in pages and MB. No automatic cap. - Over 4,500 file pages (~40 MB, near p99): every run caps at 4,500 and says so; beyond it a wiki may not publish.
--max-file-pagessetsmax_file_pagesinconfig.yaml, honoured byupdate --fullandgenerate; hosted or scripted callers set it directly.
Cost gate. Confirms the estimate before spending (Yes up to $25, No above). No TTY: declines unprompted, keeps the index, renders the structural wiki.
Exit codes.
0ready;130interrupted (repowise init --resume); other non-zero: failure.2: gaps, all saved; the last line names the gap and fix (e.g. docs from code as the cost prompt needed a terminal: re-run with--yes). Also usage errors, before running.- Real-embedder vector-write failure (e.g. broken LanceDB): pages and full-text kept, index scope gets
search.semantic: unavailable, exit2names the fix (reinstall,repowise reindex). Keylessmocknever fails so. - Workspace
initexits2after saving every repo, naming those with gaps.updateexits1on a failed embed.
Driving init from an agent or script
repowise init --yes --no-prose --progress json: JSON lines on stdout, human text on stderr.
- Each line:
v(schema,1),event(stage,phase,warning, lastsummary).phase:state(start/done/failed),completed,total,unit,elapsed_s. summary:status(ready/degraded/interrupted/failed= exit0/2/130/other),mode(keyfrom index scope,label,run_mode),restart_required(restart or/mcpto load tools),spend(tokens,usd),warnings,files_written,next(commands,repowise servefirst).
Documentation output limit. max_tokens in .repowise/config.yaml (not a flag) caps each model page for init,
update, generate, restyle, workspace and server generation. See Configuration.
repowise update [PATH]
Refresh the index for files changed since the last sync, plus affected wiki pages in docs mode.
repowise update # diff since last sync
repowise update --since v1.0.0 --working-tree
repowise update --workspace --docs # every stale repo, docs forced
repowise update --repo backend # one workspace repo
repowise update --full --provider anthropic # fast index to full
| Flag | What it does | Default |
|---|---|---|
--provider / --model |
Override for this run. | persisted choice |
--reasoning |
Same choices as init. |
|
--since |
Git ref to diff from (overrides state.json). |
last sync |
--cascade-budget |
Max pages to regenerate. | auto-scaled |
--concurrency |
Max concurrent LLM calls. | 10 |
--yes / -y |
Skip the --full cost prompt. |
off |
--dry-run |
Preview only. | off |
--docs / --no-docs |
This run: --docs LLM-regenerates changed pages (even if indexed without docs); --no-docs = --index-only. |
docs_mode in .repowise/state.json (from init) |
--index-only |
No doc regeneration; in a workspace, for every stale repo. | off |
--working-tree |
Also index staged, unstaged, untracked work; see notes. | off |
--full |
Fast (--mode fast) index to full (below). Errors in workspace mode. |
off |
--workspace / -w |
All stale workspace repos plus cross-repo analysis; see notes. | auto-detect |
--repo |
One workspace repo by alias (implies --workspace). |
|
--no-cost-tracking |
Don't record spend; see notes. | tracking on |
--agents / --no-agents |
Managed AGENTS.md after update. Persists. |
|
-v, --verbose |
Changed-file list, per-phase internals (cascade budget, decision-marker and evolution counts, best-effort skip warnings, generation report), debug logs. | compact summary |
--progress |
rich bar, or json events on stdout for another process. |
rich |
What it refreshes. Graph, git metadata, health, dead code; on graph-shape changes, the knowledge graph (layers, guided tour, entry points) and knowledge-graph.json.
- Index-only runs reuse stored layer names and node summaries (no LLM call). Docs mode saves pages as they finish; reruns skip them by prompt hash.
- Failed best-effort steps (git metadata, decisions, dead code, ...) still exit 0, listed in the completion panel and
doneevent'sdegradedarray (--progress json); the next update retries. - Unindexed linked worktrees seed from the base checkout first (WORKTREES.md).
Flag notes
--working-tree. Uncommitted renames reach the graph. Off so hooks and plain runs stay commit-anchored. Workspace: uncommitted changes make a repo stale.repowise watchalways does this.--workspace. Each repo'sdocs_mode(docs_enabledbeside it) plus--docs/--no-docs/--index-onlypicks docs or index-only.--docsneeds each repo's provider and key (or--provider).- Docs repos run the full single-repo docs path (pages, diagrams, decisions); others the fast parallel index-only path.
- Entries without
.repowise/get first-time indexing (index-only, free,state.jsonmarker); docs follow on a later--docsrun ordocs_enabled.
--no-cost-tracking. No secondwiki.dbengine contending with generation; live readout stays,repowise costshistory is skipped. AlsoREPOWISE_NO_COST_TRACKING.
Session decisions. Docs-mode updates (and init) can mine local agent transcripts for user corrections, reasoned
choices, failed approaches replaced by working ones. Past deterministic gates and a verbatim-quote grounding check, 2+
sessions (or one direct correction) promote a decision (source: session). Local only; off by default: repowise decision source set session --on (CONFIG.md).
Upgrading a fast index to full (--full). A --mode fast index has the full graph and metrics, but essential git
only (last commits, no per-file blame or co-change) and no model docs. update --full upgrades incrementally:
- Backfills git to FULL from a resumable checkpoint, reuses the graph, builds missing docs, rebuilds full-text search, embeds pages if possible, recomputes health on FULL history.
- Records the transition first and checkpoints each stage: failure leaves the prior scope truthful and retryable, never marked full early.
- Reuses valid persisted provider, model, embedder; overrides explicit; shows model cost before paid generation. Unavailable embedding is stated in the scope with the fix,
repowise reindex. - No key needed: without a model, docs come from code (no spend), embedder stays free unless chosen; else the model writes them. One repo at a time (
--repo <alias>in a workspace).
Index scope and its MCP projection
Index scope (state.json:index_scope). Canonical index description for status --format json, /api/repos, agent guidance, MCP _meta.index_scope.
- Run mode, content provenance (
none,template,model), Git tier, configured commit cap, achieved Git coverage, configured/effective file-page caps, eligible/generated/omitted file-page counts, unavailable or skipped analysis, search availability, provider choices, upgrade state. - Older indexes show
unknown/null. Caps never count as achieved coverage, nor missing analysis as clean.
Index scope over MCP. A compact projection: run mode, provenance, Git tier, status, degraded analyses, canonical-object fingerprint.
status:complete(evidence exists and is clean),partial,degraded,upgrading,unknown(coverage never recorded).get_overview(include=["scope"]): full object plusfingerprint, so held copies check against later digests.- Since
_metacontract 3 acompletedigest is omitted; only gaps ride. REPOWISE_MCP_INDEX_SCOPE=fullalways sends the full object, as builds before_meta.contract_version2 did.
repowise generate [PATH]
Write subsystem (concept) pages with a model: the upgrade path for a --no-prose repo.
repowise generate # write the unwritten subsystem pages
repowise generate --path src/api
repowise generate --page module_page:src/api --cascade none # one page, nothing else
| Flag | What it does | Default |
|---|---|---|
--unwritten |
Pages still on a stub ("finish writing the wiki"). | on, non-interactive |
--all |
Every page; rewrites written prose. | off |
--stale |
Pages whose code changed since written. | off |
--path <glob> |
Pages under a prefix or glob. Repeatable. | |
--page <id> |
One page id. Repeatable; structural ids error. | |
--cascade none|dependents|full |
Dependent-page policy, below. | dependents |
--provider / --model / --reasoning |
LLM overrides. | |
--concurrency |
Max concurrent LLM calls. | 12 |
--dry-run |
Print plan and cost estimate only. | off |
--yes / -y |
Skip cost confirm and chooser. | off |
--verbose / -v |
Pipeline debug logs. | off |
- Selection flags combine as a union.
- Cascade (priced in the estimate). A rewritten page makes its layer page, overview, architecture and onboarding
pages drift.
none: dependents marked stale (truthful, free, instant).dependents: also regenerate summarizing overview / layer pages; rest stale.full: regenerate all; nothing stale. - Writes only model pages: the numbered concept tree above file level, overview, architecture diagram, onboarding.
Structural pages (file, symbol, API, infra, cycle) refresh on
repowise update, never an LLM re-render. - Reuses the index like
update --fullandrestyle: graph and git metadata rehydrate from SQL. No provider: an error naming the key-setup path. - Chooser. No selection flag on a terminal: shows written / unwritten / stale, asks about cascade only if it changes
the pages, then confirms cost. Piped,
--yesor flagged runs just use--unwritten.
Skipped decisions and embedding
A keyless or --no-prose index cannot read decisions from PRs, git history or code comments. The first generate (or
update --full) with a model runs those lanes once, priced on their own line; repowise status shows a Decisions row
until then.
generate embeds what it writes. Over embedder: mock in config.yaml it resolves a real embedder from the
environment and prints Embedder: openai (was mock, index-only's default). The new vector width rebuilds the store: the
whole wiki re-embeds (no LLM) and config.yaml records the embedder for later update runs.
repowise restyle [STYLE] [PATH]
Switch a repo's wiki style and regenerate every page in the new voice.
repowise restyle # show current style + options
repowise restyle caveman # condensed, AI-first
repowise restyle reference --yes # API-manual, skip the confirm
repowise restyle tutorial
| Flag | What it does | Default |
|---|---|---|
--provider / --model |
LLM overrides. | |
--concurrency |
Max concurrent LLM calls. | 12 |
--reasoning |
Reasoning mode, supported providers. | |
--verbose / -v |
Pipeline debug logs. | off |
--yes / -y |
Skip the confirmation. | off |
- Needs a provider and a wiki; rehydrates graph and git metadata from SQL (no re-resolution, no re-blame).
- On an
--index-only(template) repo it upgrades every page after a spend warning; for part, or the same style, userepowise generate. - Styles change voice and density, not headings, so search, table of contents and cross-links work. See WIKI.md.
Editing
wiki_styleinconfig.yamland runningupdatedoes not regenerate pages (it only re-scores health). Userestyle.
repowise wiki-styles [PATH]
List wiki styles (built-ins plus custom ones under .repowise/styles/) and the current one. No flags.
repowise wiki-styles
repowise serve [PATH]
Start the API server and web UI.
repowise serve --port 8080 --ui-port 8081
| Flag | What it does | Default |
|---|---|---|
--port |
API port. Env REPOWISE_PORT. |
7337 |
--host |
Bind host. | 127.0.0.1 |
--workers |
Uvicorn workers. | 1 |
--ui-port |
Web UI port. | 3000 |
--no-ui |
API only. | off |
--no-open |
Don't open the UI in a browser. It opens only in an interactive terminal outside CI, once the UI answers. Env REPOWISE_NO_OPEN. |
off |
--refresh-ui |
Re-download the UI tarball (skips sources 1 and 2). | off |
The UI needs Node >= 20, else API-only. UI sources, in precedence:
- Local build at
packages/web/.next/standalone/...in a checkout;npm run build(ifnpmexists) whenpackages/web/,packages/ui/src/orpackages/types/src/is newer. - Cached download at
~/.repowise/web/, keyed by CLI version in.version. - Fresh download of
repowise-web.tar.gzfrom the matching GitHub release.
repowise watch [PATH]
Watch for file changes and auto-update wiki pages. Ctrl+C stops.
repowise watch --debounce 5000 # 5s debounce
repowise watch --workspace --index-only
| Flag | What it does | Default |
|---|---|---|
--provider / --model |
LLM overrides. | |
--debounce |
Ms after the last change. | 2000 |
--workspace / -w |
All workspace repos. | auto-detect |
--no-workspace |
Single-repo mode. | auto-detect |
--index-only |
No LLM page regeneration per trigger (workspace mode always). | off |
--verbose / -v |
Pipeline and update debug logs. | off |
- Unlike the post-commit hook, indexes staged, unstaged and untracked files.
- Writes in
.repowise/,.git/,node_modules/, build output,CLAUDE.md,AGENTS.md,.mcp.jsonnever trigger. - With docs each trigger calls a model;
--index-onlykeeps index, graph and health current free, prose waits forrepowise update.
Query Commands
repowise search QUERY [PATH]
Search wiki pages by keyword, meaning, or symbol name.
repowise search "how are errors handled" --mode semantic
repowise search "AuthService" --mode symbol
repowise search "rate limit" --all # workspace, fan-out
| Flag | What it does | Default |
|---|---|---|
--mode |
fulltext, semantic, symbol, auto, concept, path, hybrid. |
fulltext |
--limit |
Max results. | 10 |
--all |
Every workspace repo, merged. | off |
Plus --repo, --no-workspace, --format and --full as in the shared options.
search_codebaseretrieval: full-text and vector fused, excludes and tombstones honoured, decision / test pages demoted unless asked for.fulltextandsemanticboth run the fusedconceptsearch; without an embedder the vector leg drops and--mode semanticsays so.autoroutes identifier to symbol, path to files, prose to concept, mixed tohybrid.- Hits:
score,title,page_type,path,snippet, pluscandidates(openable files). Symbol hits addname,qualified_name,kind,line,symbol_id. Synthesized answers:repowise ask.
repowise ask QUESTION
Answer a question about the codebase, with citations.
repowise ask "how is width resolved?" --scope packages/cli/
| Flag | What it does | Default |
|---|---|---|
--scope |
Restrict retrieval to a path prefix. | whole repo |
Plus the shared options.
get_answersynthesis (hybrid retrieval, then LLM): the one query command that costs an LLM call.confidence: highis content-grounded, citable directly. Low confidence returnsbest_guesses(a file plus why) instead of nothing.
repowise context TARGETS...
Triage card for files, modules or symbols: relationships and risk signals, not source bytes. Batch targets in one call.
repowise context src/api/routes.py src/api/auth.py
repowise context src/api/routes.py::login --include callers --include metrics
| Flag | What it does | Default |
|---|---|---|
--include |
Opt-in block, repeatable; values below. | |
--no-compact |
Add structure, imports, docstrings. | off |
--symptom |
Issue text, error or stack trace for --include suspects. |
Plus the shared options.
--include values: full_doc, ownership, last_change, callers, callees, references, metrics,
community, decisions, health, skeleton, skeleton+, doc_drift, symbols, changes, provenance,
suspects.
- Card: title, summary, layer, signatures with lines, hotspot and bug-fix history, doc freshness, skeleton shape.
--include skeletonadds the file body-elided and line-verified;--fullonly then carries one.
repowise symbol SYMBOL_ID
Read one function, class or constant with live-verified line bounds.
repowise symbol "src/api/routes.py::login"
repowise symbol "src/api/routes.py:140-180" # live range read
repowise symbol "repowise#a1b2c3d4e5f6" # a distill omission ref
| Flag | What it does | Default |
|---|---|---|
--context-lines |
Extra lines around the body (0-50). | 0 |
--query |
Omission refs: regex or substring filter on restored lines. |
Plus the shared options.
sourceis line-numbered like a file read;verified: truemeans bounds checked against the live file.- An ambiguous id (overloads, re-exports) returns every body. A truncated body carries a
continuationto pass back.
repowise why [QUERY]
Why the code is shaped this way (decisions, rationale, git archaeology); run before a refactor or pattern divergence.
repowise why "why the retry cap?" --target src/api/client.py
repowise why src/api/auth.py # governing decisions + origin story
repowise why # decision health dashboard
| Flag | What it does | Default |
|---|---|---|
--target |
File to anchor the search. Repeatable. |
Plus the shared options. A path without decisions falls back to git archaeology, so it is never empty.
Shared options: ask, context, symbol, why
Thin adapters over the same-named MCP tools.
| Flag | What it does | Default |
|---|---|---|
--path |
Repo or workspace root (a flag, since context's variadic targets would swallow a trailing [PATH]). |
cwd |
--repo |
Workspace repo alias. | |
--no-workspace |
Single-repo mode inside a workspace. | auto-detect |
--format |
table or json. |
table |
--full |
Raw tool payload, as an MCP client gets it (implies --format json). |
off |
--format json is a trimmed CLI projection (see each module's project()). Errors, not-founds, did-you-mean lists,
truncation markers, continuation tokens and ambiguity signals always survive. ask names omitted blocks in
dropped_blocks.
Measured sizes on this repository
Trimmed / --full: ask 3.4 / 19.5 KB; context (one file) 0.9 / 12.4 KB; why (question) 10.4 / 20.9 KB; why
(path) 10.4 / 28.5 KB; symbol 0.7 / 1.0 KB; search (8 hits) 4.9 / 6.8 KB; search --mode symbol 4.2 / 5.7 KB; risk --target (one file) 4.5 / 5.3 KB.
symbol drops only the envelope; search and risk --target drop ranking internals, so --full there means exactness, not size.
repowise status [PATH]
Show wiki sync state, page statistics, and coverage.
repowise status --workspace --format json
| Flag | What it does | Default |
|---|---|---|
--workspace / -w |
All workspace repos. | auto-detect |
--no-workspace |
Single-repo mode. | auto-detect |
--format |
table or json. |
table |
- Workspace: a Docs column (page count) and per-repo Docs status with skip reasons (e.g.
cost gate declined) and fix command. - Single repo: a Next block: count worth doing this week (or quarter if quiet) and the first; JSON
next_actions;repowise nextlists them.
repowise next [PATH]
The few things worth doing next, ranked from the index.
repowise next --horizon quarter --all
| Flag | What it does | Default |
|---|---|---|
--horizon |
week or quarter (90 days). |
week, or quarter if the week holds no work |
--all |
Up to 20 rows instead of 5. | off |
--repo |
Workspace: one repo by alias. | |
--no-workspace |
Single-repo mode. | auto-detect |
--format |
table or json (whole stored view). Hidden alias --json. |
table |
- Same stored actions as the web overview and MCP
get_overview(next_actions). - Groups Now, Worth planning, Improve what Repowise can see; rows give impact, facts, done-when, and any command.
- An index predating a store names it and suggests
repowise update. Under five commits, history-ranked rows are dropped and JSON setscontext.history_too_short.
Analysis Commands
repowise dead-code [PATH]
Detect dead and unused code.
repowise dead-code --safe-only --min-confidence 0.8 --repo backend
| Flag | What it does | Default |
|---|---|---|
--min-confidence |
Minimum confidence. | 0.4 |
--safe-only |
Only safe-to-delete findings. | off |
--kind |
unreachable_file, unused_export, unused_internal, zombie_package. |
all |
--format |
table, json, md. |
table |
--include-internals / --no-include-internals |
Private/underscore symbols. | off |
--include-zombie-packages / --no-include-zombie-packages |
Unused declared packages. | on |
--no-unreachable |
Skip unreachable files. | off |
--no-unused-exports |
Skip unused exports. | off |
--repo |
Workspace repo. | primary |
--no-workspace |
Force single-repo mode. | auto-detect |
-v, --verbose |
Live-analysis debug logs (table only). | off |
repowise doc-drift [PATH]
Docs the tree does not satisfy: a missing named path, a link to a renamed heading, a make target the manifest lacks.
repowise doc-drift --check --format sarif > drift.sarif
repowise doc-drift --check --baseline .doc-drift-baseline.json --since auto
| Flag | What it does | Default |
|---|---|---|
--min-confidence |
Hide findings below this. | show everything stored |
--kind |
path, link, anchor, command, symbol. Repeatable. |
all |
--document |
Only this document. Repeatable. | all |
--check |
CI gate on the working tree, no index; non-zero on failure. --kind symbol needs an index (else 2). |
off |
--fail-on-confidence |
With --check: fail at or above this. |
0.7 |
--baseline |
With --check: accept findings in this file; new ones fail. |
|
--write-baseline |
With --check: record findings to this file, exit 0. |
|
--fail-on-baseline-growth |
With --baseline: as in security check; base is --since, else the CI target branch. |
off |
--since |
With --check: gate only drift this change answers for; see notes. |
|
--format |
table, json, markdown, github (annotations; markdown to $GITHUB_STEP_SUMMARY if set), sarif, gitlab (GitLab Code Quality report). |
table |
--repo |
Workspace repo. | primary |
--no-workspace |
Force single-repo mode. | auto-detect |
--since: gates edited documents and anchors into them, documents naming deleted or renamed files, edited manifests' commands, symbols whose file is edited or removed. Bare ref:REF...HEADplus uncommitted;auto: CI target branch.- Without
--check: reads whatinit/updatestored, asget_health(include=["doc_drift"])does. - Checks only resolvable references (most are uncheckable by design); clean does not mean every sentence is true.
- Suggested fixes (never applied): module turned package, git rename, close heading or build target, renamed symbol.
Exit codes. Without --check: non-zero for no readable index or one predating drift storage (JSON names why; no
empty list). --check: 0 passed; 1 failed; 2 not evaluable (no git repository, unreadable baseline, undiffable
--since revision).
repowise risk [REVSPEC]
Score a commit or range with code-health's calibrated signals: pure git + learned constants, no LLM, no repowise init. Model: docs/layers/CHANGE_RISK.md.
repowise risk main..HEAD -x 'tests/' -x '*.spec.ts'
repowise risk --fail-above-percentile 95 --format github
REVSPEC. None: uncommitted work, else HEAD. HEAD: last commit. base..head: a branch as one change. base...head: from the merge-base, excluding commits landed on base.
| Flag | What it does | Default |
|---|---|---|
--path |
Git repository. | cwd |
--ext |
Comma-separated suffixes (.py, .ts,.tsx). |
all |
--exclude / -x |
Gitignore-style pattern omitted from change and baseline; repeatable; root .riskignore too. |
|
--baseline |
Recent commits sampled for the percentile; 0: absolute model-score band only. |
200 |
--target / -t |
History for these files, not a change (get_risk); repeatable. |
|
--changed-file |
With --target: PR mode; a directive leads: what may break, missing co-changes and tests, what to run. |
|
--fail-above-percentile |
CI size gate (0-100); see notes. | off |
--format |
table, json, markdown, github (::error:: on gate failure, else ::notice::; markdown to $GITHUB_STEP_SUMMARY). Last two: not for --target; no REVSPEC means the CI change. |
table |
--full |
With --target: full payload as JSON (implies --format json). |
off |
--fail-above-percentile: exit1above this percentile of recent commits (risk_percentile, not the 0-10 score),2with none (--baseline 0, under 8 commits). NoREVSPEC: CI target branch...HEAD. JSON:"gate": {"fail_above_percentile": P, "percentile": <unrounded>, "status": "pass" | "fail"}. About (100 - P)% fail by design; answer with a split or second reviewer, not a fix (no baseline).- Unreadable revspec: exit
2even ungated; JSON{"error", "message"}. - Headline: live percentile by size and spread among recent repo commits (size, not danger), then touched files' bug-fix record. Raw 0-10 score: secondary, corpus-anchored, high where commits run large. Drivers: versus the model's baseline commit.
--target: bug-fix pressure, churn trend, dependents, co-change partners, ownership; needsrepowise init;--pathis the repository.
Independent changes. With an index, says if the diff is one change
or several, linking files by indexed imports, calls, type references, co-change pairs and, for base..head, shared
commits (the author's grouping).
- Groups indexed non-test source files a resolver links; docs, config, data, tests list under
Left out of the grouping:(first ten). - Each group lists files and those alone holding it together;
Basis:names what was checked (a shared commit only if commits existed). - Silent for one change; no score; JSON
independent_changes.
repowise overlap
Other open branches editing the files this change edits.
repowise overlap --base main
| Flag | What it does | Default |
|---|---|---|
--base |
Base ref for both sides. | trunk from origin/HEAD, else main or master |
--branch |
The change. | HEAD |
--path |
Git repository. | cwd |
--limit |
Branches diffed, newest committer date first. | 50 |
--format |
table or json. |
table |
- Pure git (fresh clones work); an index orders shared files, adds history pairs.
- Rows give a basis (
same file,co-change pair, N of M commits), never a score. - Skips stacked branches (either way), noise paths, dependency manifests; no shared file, no row.
- Reports branches scanned of existing; one line if no overlap. Branch overlap.
repowise security
scan walks full git history for leaked secrets and risky patterns later removed; check gates a change in CI. init / update scan the working tree.
security scan
repowise security scan --history --since v1.0.0 --to HEAD
| Flag | What it does | Default |
|---|---|---|
--history |
Required; else a hint and exit (no working-tree rescan). | off |
--since <rev> |
Lower bound (exclusive). | all history |
--to <rev> |
Upper bound (inclusive). | HEAD / all history |
--path <dir> |
Repo path. | cwd / workspace primary |
--all-patterns |
Code smells (eval, os.system, weak hashes, …) besides leaked secrets (credential assignments, vendor key shapes). |
off |
--format |
table or json; deprecated alias --output wins. |
table |
Findings land in security_findings (idempotent; local server security API / UI); the command prints counts.
repowise security check [REVSPEC]
Gate a change on security findings it adds.
repowise security check origin/main...HEAD --format github --baseline .security-baseline.json
| Flag | What it does | Default |
|---|---|---|
--fail-on |
Exit 1 at this or above: high, med, low (secrets on test, fixture, spec, mock, example paths). |
high |
--baseline |
Accept findings in this file; new ones fail. | |
--write-baseline |
Add the change's findings to this file (keeping its and --baseline's); exit 0. |
|
--fail-on-baseline-growth |
With --baseline: exit 1 on findings the file lacks at the change's base (re-saving hides nothing); new baselines pass. |
off |
--path |
Path inside the repository. | cwd |
--staged |
Staged lines from the index (pre-commit hook): no history scan or REVSPEC; working-tree security.patterns. |
off |
--format |
table, json, markdown, github, sarif, gitlab (GitLab Code Quality report). |
table |
- CI-ready: git only (no index, database, API key); stores nothing. Keeps findings on changed lines of touched files at head; checks secrets per commit (added then deleted still fails). Snippets masked.
- REVSPEC:
origin/main...HEAD(pull-request view),base..head, or a commit; else base from CI pull-request variables (GitHub, GitLab, Jenkins, Bitbucket) or the remote default branch. - Custom secrets:
security.patterns. Usefetch-depth: 0. Scoping, GitHub Actions SARIF recipe: In CI.
Silencing a finding
A repowise-security-ignore comment silences its own line only (exact, case-sensitive; no next-line or whole-file form).
- Bare: every kind;
: kind, kind: those (custom:<name>for custom patterns); free text: nothing. - A secret from an earlier commit stays silenced only if that commit has the marker (squash or rotate).
- Silenced: never fail or enter
--write-baseline. JSON:gate.suppressed(no matched text),gate.suppressed_count; SARIF:inSource; table, markdown,github: counted; GitLab: omitted, count logged.
Exit codes. 0 passed; 1 failed; 2 not evaluable: no git repository, unknown revision, shallow clone missing
the merge-base or a change commit, unreadable baseline, invalid security.patterns, internal error, REVSPEC with
--staged.
repowise impacted-tests [REVSPEC]
Tests a change exercises, so CI runs "these 40 tests, not all 4,000".
repowise impacted-tests main..HEAD --format list | xargs pytest
repowise impacted-tests main...HEAD --format args --runner pytest --prioritize
| Flag | What it does | Default |
|---|---|---|
--path |
Repo path. | cwd / workspace primary |
--staged |
Staged changes (git diff --cached). |
on with no range outside CI (in CI: the pull request's change) |
--format |
table, json (report + selection), list (an id per line), args (runner arguments or :all; reasons on stderr). |
table |
--runner |
For args: auto (files when mixed), pytest (node ids or files), go (package dirs), jest (files; use --runTestsByPath), files. |
auto |
--explain |
Test file or node id: why (not) selected (changed file, evidence, import route, or rule), run-order place; JSON explain. |
|
--prioritize |
With args, list, json: whole suite, selected first; skips nothing; orders full runs. |
off |
REVSPEC: base...head (since the fork, as a pull request), base..head, or a commit; none: staged. Looks up
changed lines (no LLM, no network) in the per-test map from repowise coverage add, naming the
path that fired:
- per-test coverage: covering tests (
via: coverage); - a test file: itself (
via: changed-test); - no coverage rows, reached in the import graph: those tests (
via: import-graph), under "NOT coverage-backed"; - else a name match (
via: filename-pattern), same table; - nothing: "unknown, run the full suite" (never "no tests needed");
- no map: a prompt to
repowise coverage adda report with contexts, plus graph guesses.
Only coverage proves lines ran; passing others clears nothing. The map needs per-test contexts (coverage.py .coverage with dynamic contexts, per-test lcov); score at the ingested head.
Exit codes. --format args: 0 for a subset or all; 2 for an unreadable change (unknown revision, missing
history) or tests.* config. Full runs: CI.
JSON fields and run order
indexed_commit,map_current; per-fileselected.basis:full-run,no-tests-needed,test-tree,test-package,conftest,helper-importers,deleted-test,coverage,changed-test,call-graph,import-graph,filename-pattern,unknown,none(no index).- Per-test
selected.why: first changed file and evidence, or why it always runs. selected.broadcast: test file -> the conftest or test-package__init__.pyon a route keeping every test under it (sole reason to run).selected.import_closure: test file reached only via imports, over one file away, no call path -> distance. Agent views count both apart.
Run order (args, json; list keeps report order unless --prioritize), likeliest failure first:
- Tiers: edited by the change; map hits a changed line, then file; calls, fixtures or direct import reach it; reached via other files; runs with every subset.
- In a tier: failed last local pytest run (
.pytest_cache, repo-root ids), fewer hops (if measured), more co-changes with changed files, more changed files reached, path. - JSON
order:tier,hops,co_change,failed_last_run.--prioritizeruns a file selected by some node ids whole.
repowise health [PATH]
Per-file scores from 51 deterministic detectors, pure Python over tree-sitter + git; no LLM by default.
repowise health # KPIs + lowest-scoring files
repowise coverage add coverage.lcov && repowise health --recompute # or wait for the next update
Detectors: McCabe complexity, nesting, brain methods, LCOM4 cohesion, god classes, native clones, untested hotspots,
coverage gradient, function/ownership/churn/change-entropy organizational risk, test-quality smells, more. Guide:
docs/layers/CODE_HEALTH.md; internals:
docs/architecture/code-health.md.
| Flag | What it does | Default |
|---|---|---|
--file <path> |
One file in depth (relative path). | |
--module <prefix> |
Files under this path prefix. | all |
--scope |
all or production: files every figure covers (production scores lower with no defect: tests score higher). |
all |
--counts |
everything or code_shape (drops the git-derived half, which rises as a file is worked on: is the code itself improving?). |
everything |
--refactoring-targets |
Stored queue: per file, graph-aware plans (Extract Class / Helper / Method, Move Method, Split File) as ordered steps, Break Cycle advisory; MCP and web UI order. Needs repowise init; REFACTORING.md. |
off |
--recompute |
Analyze the working tree in-process (slow on large repos; needed without an index); see notes. | off |
--score <path> |
Score on-disk files pre-update or PR; repeatable. Bytes give structure, the index the rest (history, coverage, test pairing, dependents, clone partners), as the next update would, so an unedited file scores what the index stores; no index: code shape. JSON: files, score_change, clone_source. |
|
--against <rev> |
With --score: before, after, change, nloc-weighted average at <rev>. |
|
--generate-code <selector> |
Patch for one path::symbol target; the only LLM flag (needs a provider). |
|
--plan <id> |
Stored plan as an agent prompt; JSON: recipe (preconditions, steps, postconditions). Reads the index. | |
--trend |
Last 10 snapshots + alerts (declining / predicted decline). | off |
--badge |
shields.io badge URL/JSON. | off |
--format |
table, json, md. |
table |
--repo |
Workspace repo. | primary |
--no-workspace |
Force single-repo mode. | auto-detect |
--verbose, -v |
Pipeline debug logs. | off |
--recompute: whole-repotableruns write scores, findings, trend snapshot to the index;json,md,--file/--modulenever do. Applies--scope/--countsto--refactoring-targets.- Default: reads, never writes, what
init/updatestored (MCP and web UI rows, withrepowise coverage addcoverage).repowise status:Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: <path>). - Preview languages: a dim line per layer and language, e.g.
Refactoring on Java: preview, measured 22% precision on 55 judged plans from 2 Java repos, 2026-10-15(repowise dead-codetoo). Previews: health on C++; refactoring, performance, dead code on Java, C#, C, C++ (dead code also Kotlin, Swift); none held back.
repowise health check [REVSPEC]
Gate a change on code-health findings it introduces.
repowise health check origin/main...HEAD --format sarif > health.sarif
| Flag | What it does | Default |
|---|---|---|
--fail-on |
introduced or worsened. |
introduced |
--fail-at |
Lowest failing severity: medium, high, critical. |
high |
--diff-risk |
warn, error, off; LEVEL for all three rules, RULE=LEVEL for one; repeatable. |
warn |
--path |
Path inside the repository. | cwd |
--format |
table, json, markdown, github, sarif, gitlab (GitLab Code Quality report). |
table |
Git only (no index, database, API key); matches changed files' base and head findings by file, marker, symbol, never line:
- Introduced on changed lines, at
--fail-ator above: fails. - Worsened, at
--fail-ator above: warns; fails with--fail-on worsened. - Either below
--fail-at, or in a test file: warns. - Moved or renamed with its code, off changed lines, or not code shape (performance, history, coverage): context only.
Diff-risk rules read changed text in any supported language; markers moved with their code to another file are ignored.
added-suppression: new lint, type-check, coverage or repowise suppression comment or attribute, or biomarker newly disabled in.repowise/health-rules.json.weakened-tests: new unconditional skip or focus marker, fewer test cases or assertions, looser coverage threshold.test-only-branch: new test-environment check in production code.
REVSPEC as for security check. Both sides use the base's
.repowise/health-rules.json; a change cannot loosen its gate. An unread code file (unparsable, over 1.5 MB) warns;
touching no readable file passes with a note.
Exit codes. 0 passed (warnings included); 1 failed; 2 not evaluable: no git repository, unknown revision, no
merge-base in a shallow clone, invalid health-rules.json at the base, over 300 changed code files, no readable changed
code file, internal error.
repowise decision
Manage architectural decision records.
repowise decision list
repowise decision show ID
repowise decision add # interactive
repowise decision add --title T --decision D # no prompts, lands proposed
repowise decision add --agent SLUG --title T --decision D --rationale R --affects PATH # an agent's own record
repowise decision candidates # awaiting review; these govern nothing
repowise decision confirm ID... # accept: this makes them govern
repowise decision reaffirm ID... # renew an accepted decision after re-reading it
repowise decision dismiss ID... # tombstone (sticky; never re-proposed)
repowise decision merge ID INTO_ID # fold into an accepted decision (--agent signs)
repowise decision dedupe # fold duplicate candidates (dry run unless --apply)
repowise decision split ID # flag as bundling two choices; never splits it
repowise decision deprecate ID # optionally naming its successor
repowise decision health
repowise decision status # what capture did and cost
repowise decision export # accepted decisions to .repowise/decisions.yaml
repowise decision import # reconcile the store to that file
repowise decision migrate # classify pre-split rows (dry run unless --apply)
repowise decision config show # resolved capture policy
repowise decision config preset NAME # default | off | local_only | balanced | full
repowise decision config discovery # broad discovery call budget
repowise decision config agent-acceptance --on|--off # may an agent grant authority? (on)
repowise decision config capture-prompt --on|--off # agent records what it committed (on);
# --on installs the shell hook
repowise decision source list # source registry and state
repowise decision source set SRC --on|--off # switch one source
repowise decision source set SRC --llm|--no-llm # switch only its model stage
repowise decision llm --on|--off # all decision-extraction model calls
Every subcommand takes --format (table default, or json) and an optional [PATH] last.
add
| Flag | What it does | Default |
|---|---|---|
--title |
Short title. | |
--decision |
What was chosen. | |
--context |
What forced it. | |
--rationale |
Why. | |
--alternative |
Rejected alternative. Repeatable. | |
--consequence |
Accepted tradeoff. Repeatable. | |
--affects |
File or module governed. Repeatable. | |
--tag |
Tag. Repeatable. | |
--evidence-commit |
Commit it was made in. Repeatable. | |
--kind |
architectural governs code; agreement governs how work is done (no files, never checked against code). |
architectural |
--agent |
Record as this agent's (source agent, e.g. claude_code); acceptance then needs evidence. |
|
--session |
The agent session recording it. Needs --agent. |
--titleplus--decision: no prompts, prints the new id. Any flag, or--format json, without both is refused.- Flag-driven records land
proposed, interactiveactive; promote withrepowise decision confirm <id>.
candidates
| Flag | What it does | Default |
|---|---|---|
--state |
open, accepted, merged, needs_split, dismissed, all. |
open |
--lane |
Extraction lane: pr, session, session_discovery, comment, git_archaeology, adr, inline_marker, conventions, cli. Not the Decisions page review lanes. |
all lanes |
--limit |
Max listed. | 30 |
confirm, reaffirm, dismiss, deprecate, merge, split
| Flag | What it does | Default |
|---|---|---|
--reason TEXT |
confirm: rationale, or why a constraint needs none; corrects the record. reaffirm: why it still holds. dismiss, deprecate: why. split: what the two choices are. |
|
--scope PATH |
confirm: file or module governed. Repeatable; replaces the proposed scope. |
proposed scope |
--evidence REF |
confirm, reaffirm: commit, file or link. Repeatable. |
|
--as NAME |
confirm: accepter other than git identity. |
git identity |
--superseded-by ID |
deprecate: lineage edge to the replacement; deprecated id keeps resolving. |
|
--agent SLUG |
Sign as an agent (e.g. claude_code). Granting is refused only under agent-acceptance --off. |
|
--session ID |
Signing agent session. | |
--yes / -y |
dismiss: skip the prompt (as does --format json). |
off |
--preview |
Not split: report each id's outcome, write nothing. |
off |
confirmaccepts candidates; on an already accepted decision it refuses and points atreaffirm.reaffirmrefuses a candidate.mergeneeds an accepted target: confirm the target first, or merge the other way.- A dismissed or deprecated candidate records its signer on its review row.
- With
--format json, every verb butsplitreturns{action, preview, results, succeeded, failed}, even for one id.
dedupe, migrate, export, import
| Flag | What it does | Default |
|---|---|---|
--apply |
dedupe, migrate: write the plan; else report only. |
off |
--tau |
dedupe: cosine fold threshold, 0.5 to 1.0. |
0.83 |
--limit |
dedupe: clusters listed. migrate: reasons listed. |
10 |
--force |
export: overwrite a committed manifest from a store that accepted nothing. |
off |
--dry-run |
import: write nothing. |
off |
list
| Flag | What it does | Default |
|---|---|---|
--status |
active, proposed, deprecated, superseded, dismissed, all. |
all |
--source |
adr, agent, cli, comment, commit, conventions, git_archaeology, inline_marker, llm_inferred, pr, session, all. |
all |
--proposed |
--status proposed. |
off |
--stale-only |
Only accepted decisions at needs_review, the set decision health counts as stale. |
off |
--limit |
Max rows listed. | 100 |
--all |
Every matching row; overrides --limit. |
off |
- The table ends with
Showing N of M decisionswhen rows were cut, elseM decisions.; JSON carriestotal(rows matching the filters) andtruncated.
Capture control
| Flag | What it does | Default |
|---|---|---|
--dry-run |
config preset, config discovery, source set, llm: print the change, write nothing. |
off |
--format |
json returns the full source registry. |
table |
--max-sessions |
config discovery: session deltas one broad call reads (1-24). |
12 |
--max-input-tokens |
config discovery: input-token ceiling per broad call (2000-60000). |
30000 |
config discoverywithout budget flags prints the resolved policy. Broad discovery is thesession_discoverysource: off indefault, on inbalancedandfull.
Acceptance. Only confirm promotes to active; extraction, recurrence across sessions and confidence stop at proposed.
confirmneeds a reason, a scope and an evidence reference (flags supply what is missing), else refuses. JSON refusal:{"error": "acceptance_refused", "blockers": [...]}, exit 1 (not a crash).candidateslists first what the contract would accept at the last index;Acceptablereadsyesorconfirm's blockers (JSON:blockers).list --statusfilters a status column kept for pre-split readers, not "what governs";candidatesis the authoritative unaccepted list. The Decisions page shows five lanes over the acceptance join.confirmanddismisstake many ids, each applied independently: a refused id commits the rest and exits 1.--previewruns the contract, then rolls back.- JSON: one id emits
{"id", "status", "action"}; several, or--preview, emitaction,preview,succeeded,failedandresults[](given,id,title,ok, thenaction/statusorerror/blockers, e.g."no scope: name the files or modules it governs").
status. Policy, preset; per source: state, why no call, what it captured and when; five review lanes, backlog
acceptable today versus blocked, its age; staging queues; decision-extraction model spend. No run ledger: spend is
all-time with the last call named; a queue the store predates reads absent, not zero.
repowise decision status
Decision capture
Capture on · LLM extraction on · preset default
Source Status Records Accepted Last seen Why
inline_marker enabled 4 2 2026-08-31 Runs with model structuring.
pr skipped_no_provider 213 0 2026-08-31 No LLM provider is configured.
session_discovery disabled 0 0 - This source is switched off.
Scripting. Unknown id: confirm, dismiss, deprecate, show exit non-zero with {"error": "decision_not_found", "decision_id": "..."}. JSON list gives full ids (table: 8-character prefixes); JSON show / health skip display
caps.
repowise coverage
Ingest coverage reports and gate a change on patch coverage in CI.
repowise coverage add [PATHS...] # ingest (+ per-test map when contexts exist)
repowise coverage status # ingested coverage + "Test-to-code map" counts
repowise coverage check [REVSPEC] # gate a change on patch coverage (CI)
repowise coverage suggest-gates
repowise coverage add web.lcov api.lcov # merged, hit wins
repowise coverage add 'artifacts/**/lcov.info' # every shard
repowise coverage add web/coverage/lcov.info=web # paths relative to web/
pytest --cov=<package> --cov-context=test # .coverage with contexts (needs pytest-cov)
repowise coverage add .coverage # per-test map
init / update auto-ingest; add is the manual path. Per-file line/branch coverage clears untested_hotspot for tested files wherever their tests live.
| Flag | What it does | Default |
|---|---|---|
--path |
Repo path. | add: cwd / workspace primary; status: cwd |
--format |
add: force a parser (lcov, cobertura, clover, repowise-json, go-coverprofile, jacoco, apex). status: table or json. |
add: auto-detect; status: table |
--strict |
add: also exit non-zero when some report files do not map. |
off |
--allow-partial |
add: store even when over half does not map; rows flagged partial. |
off |
--verbose / -v |
add: debug logs. |
off |
PATH: report path or quoted glob, relative to cwd, as incheck --report; read asPATH=PREFIX(likepath_prefixincoverage.paths) only when it matches nothing. No match exits 2. Success syncs the opt-in hookhooks.coverage_reingest.- Over half unmapped: stores nothing, exits
1, suggests acoverage.strip_prefixorcoverage.path_prefix.init/updatekeep nothing from it, so their re-read clears an--allow-partialfragment. - Formats: LCOV, Cobertura, Clover, JaCoCo XML, Go coverprofile (
go test -coverprofile), Salesforce Apex JSON. With no path, discoverscoverage/lcov.info,.coverage,coverage.out,target/site/jacoco/jacoco.xmland similar. - Test-to-code map (which test covers which lines: "which tests exercise this change"): from a context-recorded
.coverageor per-test lcov; without contexts, per-file only. Separate from the per-file aggregate andhealth..coveragelacks executable lines, so gives only this map;coverage lcovexports per-file data.
repowise coverage check [REVSPEC]
Gate a change on its patch coverage: the share of changed executable lines the tests ran.
repowise coverage check origin/main...HEAD --report coverage/lcov.info --fail-under 80
repowise coverage check origin/main...HEAD --report 'artifacts/**/lcov.info' --min-coverable-lines 5
Needs only git and a report (no index, no LLM key). Paths resolve against git ls-files, added files included.
| Flag | What it does | Default |
|---|---|---|
--report |
Path or glob, relative to cwd; PATH=PREFIX as in add. Repeatable, merged hit-wins. |
coverage.paths, else discovery |
--report-format |
Force a parser (as add --format). |
auto-detect |
--fail-under |
Exit 1 below this % (0-100). Unset anywhere: no gating. | coverage.fail_under |
--min-coverable-lines |
Fewer changed measured executable lines: reported, never fails (too_small). |
coverage.min_coverable_lines |
--fail-under-risky |
Exit 1 when risky files' % is below this. | coverage.fail_under_risky |
--fail-under-branches |
Exit 1 when branches taken on changed lines are below this % (0-100); never blended. | coverage.fail_under_branches |
--base-report |
Report at the base (merge-base for A...B), read like --report, repeatable. Adds project. |
|
--max-drop |
Exit 1 when project coverage drops over this many points (0-100). Needs --base-report or an index ingest at the base. |
coverage.max_drop |
--path |
Path inside the repo. | cwd |
--format |
table, json, markdown, github. |
table |
--report:**skips dependency, cache, build dirs;=splits on the last one.- Risky: index hotspots or bug magnets, else the top bug-fix quartile. No risky or no branching changed line:
no_data, exit0. - REVSPEC:
base...head(since the fork, the PR view),base..head, or one commit; explicit in CI. Omitted:<base>...HEAD, base fromGITHUB_BASE_REF,CI_MERGE_REQUEST_TARGET_BRANCH_NAME,CHANGE_TARGETorBITBUCKET_PR_DESTINATION_BRANCH(asorigin/<name>), elseorigin/HEAD, localmain/master,origin/main/origin/master; else exit 2. - Reports:
--report, elsecoverage.pathsin.repowise/config.yaml, else (withcoverage.auto_discover)coverage/lcov.info,coverage.xml,coverage.out,**/target/site/jacoco*/jacoco.xml, root-modulebuild/reports/jacoco/**/*.xml; nested Gradle modules need--report. Config is read at the git toplevel, even with--path. - Export
.coveragewithcoverage lcovorcoverage xml. A new untested file must still be in the report; see Coverage reports per language.
File statuses. Changed comment or blank lines count as neither.
| Status | Meaning | Counts toward the % |
|---|---|---|
measured |
Named; some changed lines executable | Yes |
no_coverable_changes |
Named; no changed line executable | No |
not_in_report |
Measured extension, not named (e.g. new untested file) | No, listed "not in report", never 0% |
no_line_data |
Named without an executable-line set | No |
- Out of scope, only counted: changed tests, unmeasured types (docs, config). Left out, counted as ignored:
coverage.ignore(gitignore syntax) matches. - Go coverprofile paths under a
go.modmodule path map to its directory, unless a per-report prefix orcoverage.path_prefixis set. - Percentages floor to one decimal (79.99% shows 79.9%); the gate uses the unrounded value.
Risk and hints. Risk per file: git bug-fix history, plus hotspot, bug-magnet and dependent counts with an index (a
missing one never fails). Risky files first; worded "Risk" column. With an index, each uncovered range names a test to
extend ("Extend" column, annotation suffix, JSON hints): "extend tests/test_auth.py (inferred: calls reach login)",
"(measured: runs other lines of login)", "(inferred: imports this file)", "no test reaches this; add one". Hints never
change the verdict.
Path-scoped gates. Each coverage.gates entry (name, paths as gitignore-style globs from the repo root,
optional fail_under 0-100 and informational) judges its matching measured changed files like the whole change; a
file can count in several.
- The whole change's small-change tolerance applies: every gate (risky too) reads
too_smallunder it. - Matched unmeasured files:
unmeasured_file_count, outside the %. - A failing non-informational gate makes
gatefailand leads the headline with its counts. - Table lists every gate; markdown up to 10, failing first. See Path-scoped gates and
repowise coverage suggest-gates.
github format, in order: up to 10 ::warning annotations (riskiest file, then largest range; risky ones titled
"Uncovered change in a risky file") plus a ::notice counting the rest; ::error:: per failing gate (whole,
non-informational path, risky, branch); ::notice:: per informational gate below threshold, tolerance-exempted gate, or
set but unapplied branch gate; "Partly taken branch" ::warning per partly taken range (same cap); markdown to
$GITHUB_STEP_SUMMARY when set. Markdown and github also list files that lost coverage outside the change.
json fields
- Top:
patch_coverage_pct,covered_line_count,coverable_line_count,threshold,min_coverable_lines,gate(pass,fail,no_data,not_set,too_small;failif any gate fails). file_counts:measured,not_in_report,no_line_data,no_coverable_changes,stale_file(stored coverage only, always 0 here),out_of_scope.files[]:file_path,status,changed_line_count,coverable_line_count,covered_line_count,patch_coverage_pct,uncovered_ranges,branch_taken,branch_total,partial_ranges(0/empty without branch data);risk(fix_pressure,dependents,hotspot,bug_magnet,basis,risky,reasons);hints(null without index; per range:range,symbol,tests,basisper_test/call_graph/import_graph/none,total).scope:label,source_formats,reports,report_path_count,unmatched_report_path_count,ignored_file_count,config_errors,branch_data(per_line,none,stored_before).path_gates[]:name,paths,informational,measured_file_count,unmeasured_file_count;risky:file_count. Both also carrycovered_line_count,coverable_line_count,patch_coverage_pct,threshold,gate.project(null without base):basis(base_report,history),base_commit,head_commit,base/head(covered_line_count,coverable_line_count,coverage_pct),delta_pct(points),max_drop,gate,incomparablereasons,outside_change_note,outside_change[](null on history basis or when most files do not line up:file_path,statuschanged/no_longer_measured,newly_uncovered_ranges,newly_uncovered_line_count,newly_covered_line_count,base_pct,head_pct,causes(kindtest_deleted/test_modified/dependent_changed,path,basisper_test/graph/name)).branches(null with no branch data and no branch gate):branch_taken,branch_total,branch_coverage_pct,partial_line_count,threshold,gate.
Exit codes. 0 pass or nothing to judge (no threshold, no measurable lines, under tolerance). 1 a gate fails
(--fail-under, non-informational path gate, --fail-under-risky, --fail-under-branches, --max-drop). 2 could
not run:
Exit 2 cases
- No report, a
--reportmatching nothing, none readable or matching a repo file, all incoverage.ignore; unknown revision, no merge-base (shallow clone), single commit at a shallow boundary, not a git repo. - Malformed
coverage.fail_under/coverage.min_coverable_lines/coverage.fail_under_risky/coverage.fail_under_branches, or an unusablecoverage.gatesentry (named). --fail-under-riskyon a shallow clone or a measured file with unreadable risk, unless the flat, a path or the branch gate already failed (then1).--fail-under-brancheswithout per-line branch data (no_branch_data); from config alone, a note, exit0.--max-drop/--base-reportwith a base missing, incomparable, or with no coverable line on a side (same exception); fromcoverage.max_dropalone, a note, exit0.
Shallow clones. Shallow CI clones lack the merge-base (exit 2); fetch full history. Action, GitLab template, recipes: Repowise in CI.
repowise coverage suggest-gates
Propose path-scoped gates for coverage.gates.
repowise coverage suggest-gates --format json
| Flag | What it does | Default |
|---|---|---|
--path |
Path inside the repo. | cwd |
--format |
yaml (paste below coverage:) or json: {"sources": [{"source", "detail", "gates": [{"name", "paths"}]}]}. |
yaml |
Sources, in order, each labelled in a comment:
- CODEOWNERS: first of
.github/CODEOWNERS,CODEOWNERS,docs/CODEOWNERS,.gitlab/CODEOWNERS; a gate per owner. A later, possibly overlapping pattern not theirs (owner-less too) becomes a!exclusion;*drops earlier gates, makes none; a fully overridden owner gets none. Handles escaped spaces, tab-separated comments, GitLab[Section] @ownersdefaults. - Top-level packages from
git ls-files: each directory underpackages/,apps/,services/,libs/with a non-test source file, else each top-level source directory. - Graph communities (indexed): 3+ source files, over their directories, named by common directory; 10 largest, minus package-gate glob duplicates. Comment names the indexed commit, or no index, unreadable, no communities.
Output. First two sources need no index. Writes nothing, sets no fail_under. Pastes below coverage:; repeated names get -2, so it is valid config as printed.
repowise components
Validate, list and audit ownership of declared components.
repowise components check --format json
repowise components ownership
| Flag | What it does | Default |
|---|---|---|
--path |
Repo path. | cwd |
--format |
table or json. |
table |
check: validates.repowise/components.yamland a repo-rootcatalog-info.yaml(Backstage, see CONFIG.md) against git-tracked files. Exits 1 on any error (CI-ready).list: declared and derived components with file counts.ownership: declared owners (catalogspec.owner, CODEOWNERS,.repowise/teams.yaml) against indexed commits of the last 90 days. Flags a high or critical component with no active declared owner or bus factor 1, an owner with no recent changes, a catalog entry claiming no files.
Ownership matching
- An owner with no identity in indexed history is unknown, never inactive;
critical_no_active_ownerdoes not fire when every declared owner is unknown. - Individuals match only by exact git email or forge noreply login. A bare
@nameoutside.github/CODEOWNERSnaming no declared team stays unresolved (on GitLab it may be a group). - Findings name components and teams; individuals are counted, never named.
repowise packages
Find third-party package imports; export or join package data. See PACKAGE_USAGE.md.
repowise packages where requests
repowise packages export -o usage.cdx.json
repowise packages import sbom.json
| Flag | Subcommands | What it does | Default |
|---|---|---|---|
--path |
all | Repo path. | cwd |
--format |
all | text or json; export: cyclonedx. |
text; export: cyclonedx |
--output / -o |
export |
Output file. | stdout |
where NAME(name orecosystem:name): importing files with import line, component, owner teams and reachability, each with basis.export: declared packages and import sites as CycloneDX 1.6 JSON (evidence.occurrences). Not an SBOM.import FILE: joins your Syft, SPDX, CycloneDX or OSV JSON to usage by package name. Fetches nothing, matches no vulnerability.
repowise changes
List, show and export merged changes read from git at each index and update.
repowise changes list --needs-attention
repowise changes show pr-123 --format in-toto
A change is one first-parent commit, identified by its message's PR or MR number, then Gerrit Change-Id, then merge or
commit sha. A merge lands its branch's commits; rebase merges give one change per commit.
| Flag | Subcommand | What it does | Default |
|---|---|---|---|
REF |
show |
Id (pr-123) or any sha the change landed. |
|
--path |
all | Repo path. | cwd |
--category |
list |
Category (feature, fix, ...). | |
--shape |
list |
merge, squash or commit. |
|
--grep |
list |
Substring of title, id or a file path. | |
--needs-attention |
list |
Kept checklist flags an item. Builds none, so unopened, unexported changes are skipped. | off |
--limit / --offset |
list |
Page size / skip. | 30 / 0 |
--since / --until |
export |
Merged on or after / before (UTC, --until exclusive). |
|
--format |
all | table, json (show: versioned record); show adds in-toto (Statement v1, commits as subjects); export is json (JSON Lines) or csv (row per change and item). |
table; export: json |
--evidence / --no-evidence |
show |
Print the checklist. | on |
--refresh |
show, export |
Rebuild checklists. | off |
Evidence checklist: components touched, declared owners, suggested reviewers, reaching tests, contracts, consumers
in other repos, decisions crossed, health delta, AI provenance, diff size rank. Items carry a status (ok, attention,
unknown) and basis. Built on first read and kept; export streams each change with it, building a missing one in a
few seconds.
Outcomes item
The last item, outcomes, is reread whenever HEAD moves. It quotes reverts naming the change and later descendant
commits naming it as their fix's cause (Fixes: <sha>, "regression from/in/since", "caused by", "broken by"). It also
counts the change's files that got fix commits within 30 days (changes.outcome_fix_days in .repowise/config.yaml):
where fixes landed, never that the change caused them.
repowise suspects
Rank changes merged in a window against a symptom: where to start reading.
repowise suspects --symptom "TypeError in checkout" --trace trace.txt
| Flag | What it does | Default |
|---|---|---|
--symptom |
Issue text or error message; first 20,000 characters read. | |
--files |
A file involved. Repeatable, up to 50. | |
--trace |
Stack trace file. | |
--since |
Merged on or after (UTC). | 14 days before --until |
--until |
Merged before (UTC); when the symptom was seen. | now |
--limit |
Changes ranked. | 10 |
--path |
Repo path. | cwd |
--format |
table or json. |
table |
- Rows list fired signals (text match, import distance, co-change, recency, trace hits) with evidence. Order is where to read first, never a cause;
git bisect runconfirms one. - Text match dominates and most regressions surface after 14 days, so an unlisted change is not cleared: widen
--since. Results and bisect recipe: CHANGES.md.
repowise check [REVSPEC]
Evaluate .repowise/policies.yaml (see CONFIG.md) against a change.
repowise check origin/main..HEAD --sarif-file check.sarif
| Flag | What it does | Default |
|---|---|---|
--path |
A path inside the repository. | cwd |
--policies |
Policy file. | .repowise/policies.yaml |
--sarif-file |
Also write SARIF 2.1.0 (code scanning, reviewdog). | |
--junit-file |
Also write JUnit from the same run. | |
--format |
table, json, sarif or junit. |
table |
- Evaluates components touched, tags, git-marker provenance; with an index also reaching tests, decisions crossed, bus factor.
- Gate rules run
security check,coverage checkordoc-drift --checkexactly as alone; with no policy file gates run as alone andcheckreports nothing to evaluate. - Exit
0nofailrule fired;1one did;2invalid policy or an unevaluablefailgate. - OPA.
evidencefrom--format jsonis OPAinput: one checklist item per kind (components_touched,provenance,reaching_tests,decisions_crossed,contracts) with status, basis, per-file details.opa eval --input check.json --data policy.rego 'data.repowise.deny'runs Rego overinput.evidence.items, beside or instead ofpolicies.yaml.
repowise ci-summary DIR
Combines the gates a CI job ran into one verdict table, appended to the GitHub job summary, and prints the combined verdict (pass, warn or fail). Each gate run with --format github while REPOWISE_GATE_SUMMARY_DIR names a directory leaves its result there, and each --gate NAME=EXIT_CODE reconciles one with its exit code; a gate that left nothing reads as could not evaluate. --comment-file writes a pull-request comment that also lists each gate's findings, --previous (the comment it replaces) adds how many findings were resolved since, and --comment-key keeps one comment per working directory.
repowise ci-summary DIR --gate NAME=EXIT_CODE... [--comment-file FILE] [--previous FILE] [--comment-key KEY]
repowise events
List typed events recorded between consecutive index runs, oldest first.
repowise events --since 7d --kind bus_factor_drop
| Flag | What it does | Default |
|---|---|---|
--path |
Repo path. | cwd |
--repo |
One workspace repo (implies workspace mode). | primary repo |
--no-workspace |
Force single-repo mode. | auto-detect |
--since |
7d, 12h or ISO date. |
|
--kind |
Only this kind. Repeatable. | all kinds |
--limit |
1 to 10000. | 200 |
--format |
table, json or jsonl. |
table |
Kinds: ownership_shift, owner_inactive, bus_factor_drop (critical components), new_hotspot (off by default),
contract_added, contract_broken, decision_stale, dead_code_growth, test_reach_drop.
- Each
initandupdatesnapshots every component (ownership counts, bus factor, hotspots, dead code, governing decisions, provided contracts, test reach) under its analyzer and parser stamp. - Same stamp as the previous run: what moved becomes an event. A stamp change, or a run after one with no snapshot
(events off, snapshot failed), starts a baseline. Already snapshotted commits (even
--working-tree) are skipped. - Stored as CloudEvents JSON lines in
.repowise/events.jsonl.
Contract kinds (workspace only)
- Measured after the cross-repo pass extracts contracts at the run's commit; outside a workspace they never fire.
- Index-only
update(post-commit hook) skips that pass, leaving contracts unavailable; contract kinds compare with the last earlier measured run, passing over those. - Known limit: consumer counts are read at the provider's runs, so a consumer-only change moves no event.
- Known limit: past
compact_after_days, one run per week is kept; the comparison run can be dropped, falling back to an older measured run or none.
Config: events: in .repowise/config.yaml.
| Key | What it sets | Default |
|---|---|---|
enabled |
On or off. | |
retention_days |
Days kept. | 365 |
compact_after_days |
Age after which runs keep one per week. | 30 |
kinds |
Per-kind switches. | |
sinks |
jsonl, or stdout for CI. |
jsonl |
Web UI: Commits page Events view, newest first; GET /api/repos/{id}/events adds snapshot_runs, empty_reason
(baseline_only before two snapshots, nothing_moved, no_match) and empty_note (this command's empty-list
sentence).
repowise report assessment [PATH]
One hand-off document for a repo or every workspace repo.
repowise report assessment --format html --out assessment.html
repowise report inventory --format csv
repowise report changes --since all --no-build
| Flag | What it does | Default |
|---|---|---|
--sections |
Comma-separated section ids. | all |
--format |
json, markdown, html, csv, or a plugin renderer. |
markdown |
--out |
Output file. | stdout |
--workspace / --no-workspace |
Every workspace repo / force single repo. | auto-detect |
--repo |
Workspace repo alias. |
- Items keep OpenSSF Scorecard keys (
name,score0 to 10 or -1 inconclusive,reason,details,documentation) plusmethodandbasis. Counts and lists havescore: null; missing or held-back evidence is -1, never a low score; basisunresolvedmeans missing. - Owners are counted, never ranked or named. Local paths removed.
- JSON is canonical (
schema_version: 1). HTML is one file, inline CSS, no scripts, all fetches blocked: opens offline, prints as is.
Sections
| Section | Measures | Basis |
|---|---|---|
components |
NLOC-weighted health, catalog facts, components ownership findings |
measured; gated where language health is held back |
inventory |
Owner teams, languages, entry points, imported packages (package usage) | measured; owners declared |
hotspots |
High recent churn files | measured |
bus-factor |
Fewest primary owners holding over half of owned files; 1 or 2 named in summary unless the catalog marks them | measured; inferred under five owned files |
dead-code |
Open findings by tier; no safe_to_delete |
inferred; gated for held-back languages |
test-reach |
Ingested line coverage and test-reached production files, separate items | measured, inferred |
contracts |
Provided contracts and other-repo consumers | measured when workspace store matches the indexed commit |
decisions |
Accepted governing decisions, and stale ones | declared |
outcomes |
Changes later reverted or named as a fix's cause; from checklists kept on Change Records, omitted when none | declared |
provenance |
Commits in the last 90 indexed days with known source (count, not score); agents and models listed, not counted | measured, declared; unresolved with no markers |
trend |
Moves since a same-stamp snapshot 90+ days older, by events rules, for enabled kinds |
measured |
Per-component sections open with a summary row counting components by outcome. A component gets its own item only for an
ownership finding, bus factor 2 or less where the catalog gives criticality or tags, hotspots, a stale decision,
provided contracts, or unresolved or gated evidence; the rest are named in the summary and JSON data keeps all
figures.
Extending. Sections are Sections on SeamRegistry("report-section"), one per module in
repowise/core/report/sections/; plugins register the same way. Absent data returns None and omits the section (like
outcomes before any checklist is opened). Renderers live on SeamRegistry("report-renderer"), chosen by --format.
No modernization candidates: no signal measures them.
repowise report inventory [PATH] renders inventory alone, for software inventory review (PCI DSS 6.3.2). Same
flags as assessment minus --sections. JSON data keeps all owner teams, languages, entry points and packages; text
lists components with no owner team.
repowise report changes [PATH]: change-management audit evidence (SOC 2 CC8.1, ISO 27001 A.8.32, PCI DSS 6.5).
| Flag | What it does | Default |
|---|---|---|
--since |
Merged on or after (UTC); all for every change. |
90 days before newest indexed commit (or --until, when earlier) |
--until |
Merged before (UTC). | |
--format, --out, --workspace / --no-workspace / --repo |
As assessment. |
|
--refresh |
Rebuild every checklist in the period. | off |
--no-build |
Use kept checklists only; rest count unknown. | off |
- Per change: components and owning teams, review record ("not recorded in git" unless
Approved-bytrailers or achange-metadatasource supply one), measured and inferred reaching tests, policy verdict (condition rules of.repowise/policies.yaml, else "no policy configured"; gates not re-run), provenance, later revert or fix-cause naming. - A period summary and a method appendix (what git alone cannot attest) both state the window. Unknown counts apart, never as failure; people counted, never named.
- Shares the
changes exportevidence pass: missing checklists are built and stored a few at a time, after stderr says how many and how long.
repowise report estate [PATH]
One document for a whole workspace, read from what repowise update --workspace stored; nothing is extracted again.
repowise report estate --format html --out estate.html
| Flag | What it does | Default |
|---|---|---|
--sections, --format, --out |
As assessment. |
all, markdown, stdout |
| Section | Holds | Basis |
|---|---|---|
estate-summary |
Repos configured, indexed, read and in the graph; contracts read at an older commit than the index; services; the graph's evidence state with its reasons | measured; services inferred; unresolved when evidence is insufficient |
estate-map |
Service dependency edges by kind with strategy and confidence; architecture score, propagation cost, core, cycles, roles | inferred; score unresolved when evidence is insufficient, and named partial beside it when partial |
estate-contracts |
Providers, consumers and links by type and repo pair; HTTP calls read, located but unresolved, and files calling out through code no extractor reads; each consumer that matched no provider in another service (consumer, file, target, contract id), capped with a count of the rest; calls to public hosts counted apart | measured |
estate-health |
Per repo: average file health from the workspace store's newest snapshot; churn hotspots (recent commit churn, not defects) and bug magnets from each index, with their top files; a repo with fewer than 2 commits indexed is listed as not measured | measured; unresolved without the store or any history |
estate-seams |
Service pairs joined by an edge, ranked by link confidence x reach x (1 + co-change no contract explains), every input shown per pair; a fixed heuristic, not a calibrated risk | inferred; unresolved when evidence is insufficient |
estate-start |
Services ranked by how many others a change to them reaches; per repo, the most central production files with the least written documentation | inferred |
Outside a workspace it exits 1. A member with no index is listed as not indexed; one whose index was
written by an older repowise is listed as behind (run repowise update there), and one whose index
cannot be opened as unreadable. A section is a Section(scope="workspace", report="estate") in
repowise/core/report/sections/; it runs once with a WorkspaceReportContext.
The local server returns the same document as JSON at GET /api/workspace/estate, and the web UI
shows it on the workspace Estate report page. Both call report/estate.py::build_estate_document.
repowise distill <command>
Run a command and print a compact, reversible rendering of its output. Guide: DISTILL.md.
repowise distill pytest -x
repowise distill git status
| Flag | What it does | Default |
|---|---|---|
--source |
Hidden ledger surface label; the rewrite hook sets hook-bash / hook-powershell. On Windows, hook-bash runs POSIX syntax in a POSIX shell, not cmd.exe. |
cli |
- Drops noise (pass parades, progress spam, boilerplate); errors, failures, summaries and exit code survive.
- Dropped content goes to
.repowise/omissions/behind an inline[repowise#<ref>: ...]marker. Any filter problem prints raw output. - Honors
distill:in.repowise/config.yaml(master switch, disabled filters, omission-store sizing).
repowise expand REF
Restore the output behind a [repowise#<ref>: ...] omission marker.
repowise expand a1b2c3d4e5f6 -q "FAILED"
| Flag | What it does | Default |
|---|---|---|
REF |
12-hex ref or a whole pasted marker. | |
--query / -q |
Only lines matching this regex (or substring). | all lines |
Checks the repo's store, then the user-level fallback store.
repowise saved [PATH]
Input tokens your coding agent never had to read, and their worth.
repowise saved --by surface
repowise saved --missed
| Flag | What it does | Default |
|---|---|---|
--by |
operation, surface, agent, model, day. |
operation |
--since |
ISO date; rounded up to whole days, that day included. | |
--model |
Prices --missed estimates only. |
latest agent session model, else claude-sonnet-4-6 |
--missed |
Distillable-looking commands not rewritten. | off |
--missed-days |
--missed window. |
7.0 |
--format |
table or json (table, net and advisories in one document). |
table |
- Same ledger and report service as the savings endpoint and dashboard overview. Covers
repowise distill, tool-result hooks, MCP calls. - Measured (known before and after) and inferred (exploration replaced) savings are the two parts of the total, shown with it.
- Each event uses its recorded rate; rateless savings count as unpriced, never valued at today's model.
repowise savings sync [PATH]
Record savings agents were shown but the ledger never banked.
repowise savings sync --dry-run
| Flag | What it does | Default |
|---|---|---|
--dry-run |
Report, write nothing. | off |
--budget |
Seconds of transcript reading; raise for a big backlog. | 20.0 |
--format |
table or json. |
table |
Reads only transcript text appended since the last run. Non-zero deferred means the budget ran out; run again.
repowise corrections [PATH]
Mine local agent transcripts for recurring command fumbles. See DISTILL.md.
repowise corrections --write
| Flag | What it does | Default |
|---|---|---|
--days |
Transcript window. | 30 |
--write |
Opt-in: maintain the "Known command corrections" block in .claude/CLAUDE.md / AGENTS.md. |
off |
--min-count |
Occurrences a rule needs for --write. |
2 |
--format |
table or json. |
table |
A fumble: same base command run consecutively, first failing, a later variant succeeding (wrong tool, path, unknown flag, missing argument). Local, report-only by default.
repowise costs
Show LLM spend tracking.
repowise costs --all --by model
| Flag | What it does | Default |
|---|---|---|
PATH / --repo-path |
Repository path. | cwd |
--since |
ISO date. | |
--by |
operation, model, day. |
operation |
--repo |
One workspace repo (implies workspace mode). | primary repo |
--all |
Every workspace repo. | off |
--no-workspace |
Force single repo. | auto-detect |
--format |
table or json. |
table |
repowise export [PATH]
Export wiki pages to files, or the architecture model as Structurizr DSL.
repowise export --format html -o ./wiki/
repowise export --format structurizr --standalone -o arch/
| Flag | What it does | Default |
|---|---|---|
--format |
markdown, html, json, structurizr. |
markdown |
--output / -o |
Output directory; for structurizr, a .dsl path names the file. |
.repowise/export |
--full |
JSON: add decisions, dead code, hotspots, provenance. | off |
--standalone |
structurizr: full workspace with default views (renders alone), not a fragment. |
off |
--components |
structurizr: component level, one box per directory. |
off |
--no-externals |
structurizr: omit third-party dependencies. |
externals included |
--force |
structurizr: overwrite a file Repowise did not write (--standalone writes workspace.dsl, maybe yours). |
off |
structurizr writes one file (repowise-model.dsl by default), not pages. See Structurizr DSL export.
Workspace Commands
Full multi-repo guide: Workspaces.
repowise workspace list
Show workspace repos and their index status.
repowise workspace list
repowise workspace add <path>
Add a repo to the workspace and index it.
repowise workspace add ../new-service --alias api-gateway
repowise workspace add ../shared --no-index # register only
| Flag | What it does | Default |
|---|---|---|
--alias |
Short name. | directory name |
--index / --no-index |
Run the index pipeline; --no-index only registers. |
on |
--docs / --no-docs |
Model writes docs / index only. Ignored with --no-index. |
docs built from code, no model calls |
--provider / --model |
Override (--provider also means model docs). |
primary repo's |
--concurrency |
Max concurrent LLM calls. | 10 |
--save-key / --no-save-key |
Save this run's provider key to the repo's git-ignored .repowise/.env, so its MCP server can answer. As in init. |
on |
--verbose, -v |
Debug logs. | off |
- Provider, model, embedder and excludes inherit from the primary repo's
.repowise/config.yaml. - To make it the default:
repowise workspace set-default.
repowise workspace remove <alias>
Remove a repo from the workspace; files stay.
repowise workspace remove api-gateway
repowise workspace scan [PATH]
Find repos in the workspace directory not yet added.
repowise workspace scan --yes
| Flag | What it does | Default |
|---|---|---|
--yes / -y |
Add all without prompting. | off |
--exclude |
Skip paths matching this glob, relative to the workspace root (e.g. 'test-repos/*'). Repeatable. |
|
--verbose, -v |
Debug logs. | off |
repowise workspace update
The same command as repowise update --workspace, with the same flags. It updates the stale repos, then re-runs the cross-repo analysis when a repo changed or the contracts: or conformance: settings did.
repowise workspace update --index-only
repowise workspace set-default <alias>
Set the default repo for MCP queries.
repowise workspace set-default api-gateway
repowise workspace diagnostics
Explain the cross-repo contract link count: per-repo provider/consumer counts, unmatched consumers by reason, orphan providers (never consumed).
repowise workspace diagnostics --repo api --format json
| Flag | What it does | Default |
|---|---|---|
--repo |
One repo alias. | all |
--format |
table or json (--json deprecated alias). |
table |
repowise workspace check
Architecture lint: declared conformance: rules and dependency cycles over the system graph. Exits 1 on any finding (CI gate).
repowise workspace check --format json
| Flag | What it does | Default |
|---|---|---|
--breaking / --no-breaking |
Also fail on breaking contract changes (a removed endpoint or retyped field another repo still calls), read from the last repowise update --workspace report; nothing to declare. --no-breaking: your rules only. |
on |
--format |
table or json (--json deprecated alias). |
table |
repowise workspace metrics [PATH]
Architecture-complexity metrics over the system graph; run repowise update --workspace first.
repowise workspace metrics --format json
| Flag | What it does | Default |
|---|---|---|
--format |
table or json (--json deprecated alias). |
table |
Reports propagation cost (system coupling), the cyclic core (services in circular groups) and a deterministic 1-10 score, from structural edges only (no co-change), with declared conformance violations folded in.
repowise workspace impacted-tests <repo:path>...
List consumer-repo tests worth running for changed provider files.
repowise workspace impacted-tests backend:app/routers/users.py --target-repo frontend --format list
| Flag | What it does | Default |
|---|---|---|
--path |
Workspace root. | auto-detect from cwd |
--call-depth |
Call graph depth, 1-8. | 3 |
--import-depth |
Import fallback depth, 1-3. | 1 |
--no-measured / --no-inferred |
Drop coverage-backed / graph-inferred picks. | off |
--min-confidence |
Min contract link confidence, 0.0-1.0. | 0.0 |
--target-repo |
Consumer aliases. Repeatable. | all |
--format |
table, json, or list (repo:test-file lines). --json deprecated alias. |
table |
Each consumer call site is measured, inferred, none or unresolved; see Cross-repo test impact.
Auto-Sync Commands
All sync methods (hooks, file watcher, webhooks, polling): Auto-Sync. hook install, status
and uninstall take an optional PATH plus --workspace/-w (every workspace repo) or --no-workspace (single
repo); default auto-detect.
repowise hook install
Install a post-commit hook that runs repowise update in the background.
repowise hook install --workspace --security
| Flag | What it does | Default |
|---|---|---|
--security |
Add a marked pre-commit block running repowise security check --staged: exit 1 (finding at high+) blocks, exit 2 or no repowise passes. Skip once: git commit --no-verify. |
off |
repowise hook status
Report whether the post-commit hook and --security block are installed.
repowise hook status
repowise hook uninstall
Remove the post-commit hook and any --security block.
repowise hook uninstall
repowise hook stats
Per surface: what the Claude Code agent hooks said, whether the agent acted, invocation counts and wall time, from .repowise/sessions/sessions.db.
repowise hook stats --format json
| Flag | What it does | Default |
|---|---|---|
--format |
table or json (raw per-surface rows). |
table |
Notices that ask nothing (stale-read, silent read-after-served) show n/a, not a rate.
repowise hook backfill
Replay Claude Code transcripts into the ledger so hook stats has pre-upgrade history. Local, single-pass, re-runnable
(firings keyed by text hash); usually one-time, as repowise update classifies recent sessions.
repowise hook backfill --days 30
| Flag | What it does | Default |
|---|---|---|
--all-projects |
Include this repo's worktrees. | this checkout |
--days |
Transcripts modified in the last N days. | all |
--reset |
Clear hook-surface rows (never decisions) first; once, after upgrading from a release keyed by hook input, not emitted text. | off |
repowise hook rewrite install|uninstall|status
Manage the Distill command-rewrite hooks (Claude Code + Codex PreToolUse): noisy commands (tests, builds, git
status/log/diff, searches, listings) run as repowise distill <command> (errors-first) with no prompt by default
(permission: allow).
repowise hook rewrite install # writes ~/.claude/settings.json (idempotent)
repowise hook rewrite uninstall # removes only the repowise entries
| Flag | What it does | Default |
|---|---|---|
--workspace / -w, --no-workspace |
Every workspace repo / single repo (all three). | auto-detect |
--allow-rule / --no-allow-rule |
install: seed a Bash(repowise distill:*) / PowerShell(repowise distill:*) allow rule, needed only under permission: ask. |
off |
installtakes an optionalPATHand re-enablesdistill.commandswhere aninitopt-out turned it off.uninstallremoves the global entries and the AGENTS.md awareness section; repo config stays. Posture (permission: ask | allow, per-family overrides):distill.commandsin.repowise/config.yaml, see DISTILL.md.- Codex (
~/.codexexists): also writes~/.codex/hooks.json(Codex ≥ 0.137 only; older versions cannot apply a rewrite) and a hook-free "Output Distillation" section inAGENTS.md. Codex cannot approve a rewrite, so onlyallowfamilies rewrite;askpasses through.statusshows what your build supports (DISTILL.md).
repowise hook read-skeleton|search-digest|read-reread
Toggle the Claude Code read and search surfaces per repo. Each has install, uninstall, status, optional PATH, -w/--no-workspace.
repowise hook read-reread status -w
| Group | Config key | What install turns on |
|---|---|---|
read-skeleton |
hooks.read_skeleton |
Unbounded Read of a large indexed file returns signatures, bodies elided with the line range to read each; a second Read returns it whole. |
search-digest |
hooks.search_digest |
A grep over many files returns per-file match counts and anchor lines plus a dropped-tail count; single-file -C/-A/-B untouched. |
read-reread |
hooks.read_reread |
Re-reading an unchanged, unedited file returns a notice naming the earlier read; changed content comes in full, flagged; reading again returns content. |
- No hook to install:
init's PostToolUse hook carries all three; these set the verdict in.repowise/config.yaml(initsets it from--distill-hook). uninstallreturns whole results (the digest rides alongside again).statussays on/off and, when off, points torepowise saved. With no.repowise/it asks forrepowise init.
repowise hook health-gate install|uninstall|status
Opt-in, off by default: Claude Code's git commit and git push in this repo run
repowise health check first and are denied when the gate fails (exit 1). Optional
PATH, -w/--no-workspace.
installsetshooks.health_gate: truein.repowise/config.yamland adds a PreToolUse entry to the repo's.claude/settings.local.json;uninstall(andhook uninstall) removes both.initandupgradenever write either.- A commit is checked on the staged change, including
git addearlier in the same command and-a; a push on@{u}...HEAD, else the default branch's merge-base.--amend, pathspecs, merges in progress, other branches, tags,--delete, and agit addafter another command in the chain pass unchecked, as does anything that keeps the check from finishing within 20 s.
Utility Commands
repowise mcp [PATH]
Start the MCP server. Without PATH, walks up from cwd to the nearest .repowise repo (so Codex config can use args = ["mcp"] with cwd at the repo root).
repowise mcp --transport sse --port 7338
repowise mcp --tools "+get_dependency_path,-get_dead_code"
| Flag | What it does | Default |
|---|---|---|
--transport |
stdio (editors), streamable-http (HTTP clients), or sse (legacy). |
stdio |
--port |
HTTP/SSE port. | 7338 |
--host |
HTTP/SSE bind; 0.0.0.0 without REPOWISE_API_KEY warns that every tool is unauthenticated and network-accessible. |
REPOWISE_HOST, else 127.0.0.1 |
--tools |
Comma list = allowlist; +/- adjust defaults; lean selects the six-tool agent-lean profile. Overrides config. |
mcp.tools config block |
--all |
Every tool, including opt-in and workspace. | off |
--no-workspace |
Nested repo ignores the enclosing workspace's default. | auto-detect |
Tool list: MCP Tools.
repowise generate-claude-md [PATH]
Generate CLAUDE.md; init and update keep it current. Text above the Repowise markers is kept; between them updates from the index.
repowise generate-claude-md --stdout
| Flag | What it does | Default |
|---|---|---|
--output |
Custom path. | .claude/CLAUDE.md |
--stdout |
Print, don't write. | off |
--workspace / -w, --no-workspace |
Workspace file at the root (contracts, co-changes, per-repo summaries) / single repo. | auto-detect |
--verbose / -v |
Debug logs. | off |
AGENTS.md
repowise init --codex writes a managed AGENTS.md; repowise update refreshes it with editor_files.agents_md or --agents. Text outside the markers is kept.
repowise agents
Wire agents after init: Claude Code, Codex, VS Code, Cursor, OpenCode, Hermes, GitHub Copilot CLI, Kiro, and any host
via print-config. With no subcommand, lists each agent for the cwd repo: tier, installed or not, every wiring.
repowise agents --format json
repowise agents add [PATH] --target=opencode --scope=project
repowise agents remove [PATH] --target=hermes --scope=user
repowise agents refresh [PATH]
repowise agents print-config claude-code [PATH]
| Flag | What it does | Default |
|---|---|---|
--format |
Listing and add/remove/refresh: table or json (writes: every file and outcome). |
table |
--target |
add/remove: comma-separated ids or auto/all/none. Required for remove (destructive). |
add: prompts, installed pre-ticked |
--scope |
add/remove/refresh: project (repo), user (machine), both. |
both |
--yes / -y |
add: never prompt. |
off |
print-config --scope |
project or user snippet. |
project |
print-config --format |
table: bare paste-ready snippet; json: with target, scope, repo, docs URL. |
table |
refreshonly repoints wired agents (after an upgrade or repo move), never adds, sorepowise doctor --repaircalls it.print-configprints the MCP entry, writing nothing, for hosts like Cline, Windsurf, Zed, Gemini CLI.
Support matrix: Agent integrations.
repowise reindex [PATH]
Re-embed all wiki pages; embedding calls only, no LLM. A full run with a real embedder marks semantic search available again, clearing a failed init/update record.
repowise reindex --embedder gemini --batch-size 50
| Flag | What it does | Default |
|---|---|---|
--embedder |
gemini, openai, openrouter, ollama, edenai, mock, auto. |
auto |
--batch-size |
Batch size. | 32 |
repowise doctor [PATH]
Health-check the setup.
repowise doctor --workspace --repair
| Flag | What it does | Default |
|---|---|---|
--repair |
Rebuild FTS, re-embed missing pages, sync workspace drift, drop dead workspace entries. | off |
--workspace / -w, --no-workspace |
Workspace table (dir exists, git repo, state.json ↔ config drift) then per-repo checks / single repo. | auto-detect |
--format |
table or json. |
table |
--quick |
Skip the slow checks: starting the MCP server (mcp-responds) and reconciling the vector and full-text stores (vector-store-sync, fts-index-sync, coordinator-drift). Not with --repair. |
off |
--format jsonprints{"ok": bool, "checks": [...]}. Each check carries a stableid(kebab case, such aspost-commit-hookormcp-responds), a displayname, alevel(ok,warnorfail),ok(false only forfail), adetailand afix: the exact command that resolves it, ornull. Match onid; names can change. Awarnnever changes the exit code. With--workspace, ids repeat once per repo andnamestarts with the repo's alias.- Vector store fails when
.repowise/lancedbwon't open, naming the error. An open store with no indexable pages reports all missing;--repairwon't re-embed it with a paid embedder, it prints the count and points torepowise reindex. CLI version(best-effort, vs PyPI): upgrade command (uv tool upgrade repowise,pipx upgrade repowise,python -m pip install -U repowise), therepowiseonPATHand the launching command. Never updates, never fails offline. After upgrading, restart Claude/Codex/Cursor or any MCP client.- Distill: validates
distill:(unknown keys, bad permission values, unknown filters, non-positive store sizing); shows omission store size vs cap and whether the opt-in rewrite hook is installed (absence passes).
repowise grammars fetch DIR
Download the grammars that otherwise download on first use (COBOL, Apex) into DIR, printing each with its cache
state. Exits 1 if any fails. Copy DIR to the offline machine and set REPOWISE_GRAMMAR_DIR to it.
repowise grammars fetch ./grammars
repowise whats-new
Release notes since you last looked, then marks the current version seen. Offline, from the bundled changelog.
repowise whats-new --version 0.21.0
| Flag | What it does | Default |
|---|---|---|
--version X.Y.Z |
One release. | unseen releases |
--all |
Full history. | off |
--format |
table or json (summary, highlights, stats per release). |
table |
- Each release: highlights and a "By the numbers" line (pull requests, contributors, files and lines changed). The panel caps at 5 releases, 8 bullets each.
repowise updateshows a short panel after an upgrade;updateandserveprint a non-blocking line when PyPI is newer. See docs/reference/UPGRADING.md.
repowise telemetry
Inspect and control anonymous, opt-out usage telemetry.
repowise telemetry status # enabled or not, and why
repowise telemetry disable # or: enable
repowise plugins
List plugins from repowise.plugins entry points and REPOWISE_PLUGINS: loaded or why not, seams registered,
implementation per seam. Plugin commands load only for an unknown command name or a command listing.
repowise plugins --format json
| Flag | What it does | Default |
|---|---|---|
--format |
table or json. |
table |
See the plugin author guide.
repowise attribution
Inspect and clear AI attribution. Settings: CONFIG.md attribution:.
repowise attribution status [PATH] [--format json] # what is on, capture per agent, coverage, last backfill
repowise attribution backfill [PATH] --agent claude-code,codex [--format json]
repowise attribution purge [PATH] [--yes]
backfill(on request; agents bothcaptureandagentsallow): hashes lines of edits to this repo (worktrees too) from local Claude Code/Codex transcripts, binds them to commits within 14 days after, prints commits scanned, bound, coverage before/after. The nextupdatere-reads git history once to label them. First run reads all transcripts (about 4 minutes for 7 GB on a laptop), later runs only new ones.purgedeletes index labels,.repowise/attribution/and git-ai notes Repowise wrote; history, trailers and others' notes stay.
repowise config hints on|off
Toggle the repowise.dev hint: one dim stderr line with a link at a helpful moment (finished init, slow update); max
one per run, each once a week. Never with --format json, in CI, non-terminal stderr, signed in, or from mcp,
serve, watch, hooks.
repowise config hints off # also: REPOWISE_NO_HINTS=1 or DO_NOT_TRACK=1
repowise login
Sign in to repowise.dev (browser OAuth with PKCE; tokens in ~/.repowise/credentials.json). Not an LLM key; adds hosted
repos, reindex from local tools and account status in doctor. Local features never need it.
repowise login --with-token
| Flag | What it does | Default |
|---|---|---|
--with-token |
Paste an API key (rw_live_...): stdin when piped, else prompt. For SSH/headless. |
off (browser) |
--device-name |
Machine label in connected apps. | hostname |
repowise logout
Sign out here: best-effort server revocation, local credentials always removed.
repowise logout
repowise whoami
Show the signed-in account.
repowise whoami
repowise publish [PATH]
Have repowise.dev index the GitHub origin (nothing uploads: pushed work only; no GitHub remote, no publish). Signs in
first if needed. About 10 minutes; prints (and opens) the indexing page, plus the repo page and MCP address for
Claude.ai or ChatGPT.
repowise publish --ref release --no-open
| Flag | What it does | Default |
|---|---|---|
--ref |
GitHub branch or tag. | current branch if pushed, else default |
--no-open |
Don't open the browser. | off |
--format |
table or json (one object, never a browser sign-in; signed out = signed_out). |
table |
Refusals say why and link the fix: private repo on free → repo page (Pro trial, 10 days free, card required, plus GitHub App install); paid without the App → install link; free 2-repo limit → trial checkout.
repowise delete [REPO_ID]
Delete a repo's index and stored intelligence (wiki, graph, embeddings, git metadata); source files untouched. Works on a shared REPOWISE_DB_URL database with no local .repowise/wiki.db.
repowise delete --path /workspace/api -f
| Flag | What it does | Default |
|---|---|---|
--force / -f |
No confirmation. | prompts |
--path / -p |
Pick the repo whose stored local_path matches (no numbered choice on shared PostgreSQL). |
list all, prompt |
repowise uninstall [PATH]
Remove what repowise wrote; report what stays and why. Wider than delete (index rows only). Terminal, no flags: shows the inventory and asks. The four groups are chosen independently; without a terminal, name what to remove (--all, --keep-index).
repowise uninstall --keep-index # drop the wiring, keep the index
repowise uninstall --all --dry-run --format json
| Group | What it covers |
|---|---|
agents |
Every wired agent, both scopes, via each target's uninstall |
repo-files |
Managed blocks in .claude/CLAUDE.md, AGENTS.md |
index |
The repo's .repowise/ |
global |
~/.repowise/: login, caches, telemetry preference |
| Flag | What it does | Default |
|---|---|---|
--all |
Everything, including index and machine-wide state. | off |
--keep-index |
Reinstall case: wiring and generated blocks only. | off |
--dry-run |
Plan only. | off |
--format table|json |
json: plan, every path, outcome. |
table |
- No
--yes: a partial uninstall is no safe default. No terminal and no scope: prints inventory, removes nothing, exits non-zero. - Never pre-selected: the index (costly to rebuild),
~/.repowise/(shared by every repo). Never touched: the package (pip, uv, pipx) and Claude Code plugin (/plugin uninstall); it prints each command. - One agent only:
repowise agents remove --target=<id>.
Exit codes (each refusal prints its reason on the row):
| Code | Meaning |
|---|---|
0 |
All selected removed. |
1 |
A removal failed. |
3 |
A removal was refused; something remains. |
4 |
No scope and nobody to ask. |
repowise augment
Context enrichment run by init's Claude Code and Codex hooks, not by hand.
repowise augment --client codex # payload on stdin
| Flag | Meaning | Default |
|---|---|---|
--client |
codex or cursor, passed by those hooks. |
Claude Code |
--coverage-only |
Only the shell-tool coverage re-ingest (repo-local hook). | off |
--verbose, -v |
Debug logs. | off |
- Claude Code: search enrichment, stale-wiki checks, decisions: relevant standing decisions at session start (ranked, hard token cap, silent below the floor), one "governed by" line per decision per session on editing a governed file.
- Codex:
SessionStartandPostToolUseguidance. - Shown decisions land in
.repowise/sessions/sessions.db; the nextupdatejudges followed or contradicted and adjusts staleness.
repowise-augment / repowise-rewrite
Console scripts installed with the CLI, not subcommands, not run by hand: repowise-augment is the import-isolated augment hook entry; repowise-rewrite backs repowise hook rewrite install.