CLI Reference

Installation

npm install -g @intentweave/cli
iw --version

Or with npx:

npx @intentweave/cli <command>

CARI Commands (no LLM, no Neo4j)

`iw init`

Initialize an IntentWeave workspace.

iw init [directory]

Creates a .iw/ directory with config, cache, and index storage.

`iw index build`

Build the CARI index.

iw index build [options]

Option	Default	Description
`--depth <mode>`	`structured`	`structured` or `full` (body text + IDF)
`--include <glob>`	—	Only index matching files
`--exclude <glob>`	—	Skip matching files
`-v, --verbose`	off	Show per-stage progress

`iw index retrieve`

Ranked file retrieval.

iw index retrieve <query> [options]

Option	Default	Description
`--limit <n>`	`10`	Maximum results
`--scope <type>`	`all`	`code`, `docs`, or `all`

`iw index connections`

Cross-layer connection discovery.

iw index connections <entity> [options]

Option	Default	Description
`--limit <n>`	`15`	Maximum connections
`--include <type>`	all	`doc_cooc`, `co_change`, `code_import`

`iw index check`

CI drift detection.

iw index check [options]

Option	Default	Description
`--changed <files...>`	—	Changed files
`--severity <level>`	`info`	`info`, `warning`, `critical`
`-f, --format`	`text`	`text`, `json`, `github`

`iw index report`

Corpus-wide health dashboard.

iw index report

`iw index update`

Incremental index update.

iw index update [-v]

CARI Analysis Subcommands

All analysis queries are available as iw index subcommands:

Command	Purpose
`iw index clones`	Exact clone detection (identical body hash)
`iw index structural-clones`	Type 2 clones (same control flow, different identifiers)
`iw index circular-imports`	Import cycle detection
`iw index unused-exports`	Exported symbols never imported
`iw index hotspot-priority`	High-churn low-doc files ranked by urgency
`iw index todos`	TODO/FIXME/HACK/XXX inventory
`iw index module-coverage`	Documentation coverage % per directory
`iw index orphaned-sections`	Doc sections with all-ungrounded mentions
`iw index doc-completeness`	Per-doc completeness vs. referenced exports
`iw index cross-group-drift`	Cross-group entity coverage conflicts
`iw index mentions-of <id>`	Find doc mentions of a code or external entity
`iw index annotations-for <path>`	List all annotations for a documentation file
`iw index register-entities <file>`	Register external entities from JSON file
`iw index test-coverage`	Map test files to source files, find untested exports
`iw index hubs`	God-node / hub analysis (degree centrality)
`iw index communities`	Community detection (structural / semantic / temporal)
`iw index surprises`	Surprising connection ranking (composite score)
`iw index rationale`	WHY/NOTE/IMPORTANT/DESIGN rationale inventory
`iw index terminology`	Terminology inconsistency detection
`iw index dep-depth`	Transitive import depth + fan-in/fan-out risk
`iw index boundary-violations`	Cross-package internal import detection
`iw index layers-infer`	Auto-infer architectural layers from import graph
`iw index layers-check`	Validate imports against layer boundaries
`iw index layers-check --compare`	As-is vs. as-should layer comparison
`iw index conformance`	Interface conformance drift detection
`iw index dead-features`	Dead feature detection (unused + undocumented + stale)
`iw index api-surface`	API surface changelog (additions, removals, sig changes)
`iw index focus <target>`	Focused architecture view around a target entity
`iw index calls`	Query the call graph (all edges)
`iw index calls --caller-file`	Calls from a specific file
`iw index calls --callee-name`	All callers of a function
`iw index trace --entry`	BFS call-path trace from entry-point file
`iw index rule-coverage`	Packages with zero behavioral rules
`iw index export --book`	Insights Book (15+ chapters, primary deliverable)
`iw index export --html`	§10.1 interactive standalone HTML architecture report
`iw index export --focus <t>`	Focused Graphviz SVG architecture report
`iw intent check`	Check all intent domains (structural/behavioral/documentary)
`iw intent check --domain`	Target one domain: `structural`, `behavioral`, `documentary`, `all`
`iw intent check --baseline`	Regression gating: fail only if violations increased
`iw intent extract`	Extract rules from an ADR via LLM
`iw intent living`	Living documentation health (documentary domain)
`iw intent score`	Composite living documentation score (A–F, 4 dimensions)

All subcommands support --db <path> and -f, --format <text|json>. Some also accept -n, --limit or --kind.

These queries are also available as MCP tools (e.g., cari_clones) and via the @intentweave/index programmatic API.

`iw index layers-infer`

Auto-infer architectural layers from your import graph topology.

iw index layers-infer [options]

Option	Default	Description
`--db <path>`	`.iw/index.db`	Path to CARI index
`-f, --format`	`text`	`text` or `json`

Uses topological sort of the import DAG to assign depth ranks, then buckets files into layers (foundation at 0, entry points at the top). Outputs layer definitions with file assignments.

`iw index layers-check`

Validate all imports against inferred or configured layer boundaries.

iw index layers-check [options]

Option	Default	Description
`--db <path>`	`.iw/index.db`	Path to CARI index
`--allow-skip-layer`	off	Don’t flag skip-layer imports
`--compare`	off	Show as-is vs. as-should delta view
`-f, --format`	`text`	`text` or `json`

Detects:

Reverse imports — lower layer importing from higher layer
Skip-layer imports — layer N importing from layer N+2 (skipping N+1)

Each violation includes source file, target file, source layer, target layer, and a human-readable reason.

`iw index export --html`

Generate a standalone interactive HTML architecture report.

iw index export --html [options]

Option	Default	Description
`-o, --output <path>`	`architecture.html`	Output file path
`--db <path>`	`.iw/index.db`	Path to CARI index
`-m, --mode <mode>`	`structural`	Community mode: structural, semantic, temporal
`--provider <name>`	—	LLM provider for layer naming (`openai`)
`--model <name>`	`gpt-4o-mini`	Model for LLM naming
`--api-key <key>`	`$OPENAI_API_KEY`	OpenAI API key (if not env var)

The report combines data from layers, communities, dependencies, and boundary violations into three interactive views:

Layers — tiered layout with import edges (violations in red)
Communities — force-directed layout coloured by community, with switchable modes (structural, semantic, temporal) and vertical slice highlighting
Dependencies — root-focused tree for any selected file

Features: directory aggregation, zoom/pan, edge filtering, search, hover tooltips with per-file metrics, and optional LLM-generated names for layers and directories.

`iw index conformance`

Detect interface conformance drift — when a class claims to implement an interface but method signatures have diverged.

iw index conformance [options]

Option	Default	Description
`--db <path>`	`.iw/index.db`	Path to CARI index
`-f, --format`	`text`	`text` or `json`

Reports: missing methods, missing properties, and signature mismatches.

`iw index dead-features`

Combine three signals to surface likely dead features.

iw index dead-features [options]

Option	Default	Description
`--db <path>`	`.iw/index.db`	Path to CARI index
`--min-signals <n>`	`2`	Minimum signals to report (1–3)
`--staleness <months>`	`6`	Months since last modification
`-n, --limit <n>`	`100`	Maximum results
`-f, --format`	`text`	`text` or `json`

Signals: (a) unused export, (b) undocumented symbol, (c) stale file (no commits in N months).

`iw index api-surface`

Track exported symbols over time via git history. Detects additions, removals, and signature changes per release.

iw index api-surface [options]

Option	Default	Description
`--db <path>`	`.iw/index.db`	Path to CARI index
`--baseline <ref>`	latest git tag	Git ref to compare against
`-f, --format`	`text`	`text` or `json`

Example output: “+40 added, −14 removed, ~1 signature changed across 28 files”.

`iw index focus`

Focused architecture view around a target file or symbol.

iw index focus <target> [options]

Option	Default	Description
`--db <path>`	`.iw/index.db`	Path to CARI index
`--hops <n>`	`2`	Expansion depth from target
`--max-nodes <n>`	`20`	Maximum nodes in the view
`-f, --format`	`text`	`text` or `json`

`iw index export --focus`

Generate a focused Graphviz SVG architecture report.

iw index export --focus <target> [options]

Option	Default	Description
`--hops <n>`	`2`	Expansion depth
`--max-nodes <n>`	`20`	Maximum nodes
`-o, --output`	`focus.html`	Output file path

Knowledge Graph Commands (require Neo4j)

`iw run`

Extract knowledge from documents.

iw run [files...] [options]

Option	Default	Description
`-t, --track <track>`	`main`	`main`, `open`, `both`
`--provider <name>`	`smart-mock`	`smart-mock`, `openai`
`--model <name>`	`gpt-4o-mini`	OpenAI model
`-i, --incremental`	off	Content-addressed cache
`--persist`	off	Auto-persist to Neo4j
`--force`	off	Ignore cache
`-p, --profile <name>`	`standard`	Extraction profile
`--concurrency <n>`	`5`	Parallel LLM calls
`--from-fx <source>`	—	Skip FX, reuse cached output
`-v, --verbose`	off	Stage details

`iw query`

Query the knowledge graph.

iw query <question> [options]
iw query --cypher <cypher> [options]

Option	Default	Description
`-s, --session`	—	Neo4j session scope
`-f, --format`	`table`	`table`, `json`
`-o, --output`	—	Write to file
`-v, --verbose`	off	Show generated Cypher

`iw context`

Build RAG context.

iw context <topic> [options]
iw context -e <entity> [options]
iw context --all [options]

Option	Default	Description
`-s, --session`	—	Session scope
`-e, --entity`	—	Seed entity
`--hops <n>`	`2`	Expansion depth
`--all`	off	Dump everything
`--code-refs`	off	Include source references
`-f, --format`	`text`	`text`, `json`
`-o, --output`	—	Write to file

`iw impact`

Semantic impact analysis.

iw impact <files...> [options]

Option	Default	Description
`-s, --session`	—	Session scope
`--hops <n>`	`2`	Ripple depth
`-f, --format`	`text`	Output format
`-o, --output`	—	Write to file

`iw intent living`

Documentation freshness analysis. Three modes (least → most infrastructure):

--lite — Zero-infra keyword scan (no index needed)
(default) — CARI-backed analysis from .iw/index.db (no Neo4j)
--neo4j — Full KG-based analysis (requires Neo4j + persisted KWG)

iw intent living [files...] [options]

Option	Default	Description
`--db <path>`	`.iw/index.db`	Path to CARI index (default mode)
`--neo4j`	off	Full KG mode — requires Neo4j
`-s, --session`	—	Session ID (required for `--neo4j` only)
`--only`	all	Specific detectors: doc-code,temporal,deps,doc-doc
`--lite`	off	Lightweight keyword-only mode
`-f, --format`	`markdown`	Output format: markdown \| json
`-o, --output`	—	Write to file
`-v, --verbose`	off	Show progress

`iw persist`

Write to Neo4j.

iw persist [run-id] [options]

Option	Default	Description
`--latest`	off	Persist most recent run
`--file <path>`	—	Persist from specific file
`-v, --verbose`	off	Details

`iw xlink`

Cross-layer code linking.

iw xlink [directory] [options]

Option	Default	Description
`-s, --session`	—	Session scope
`--persist`	off	Write links to Neo4j
`-v, --verbose`	off	Details

`iw mcp`

Start MCP server for GitHub Copilot.

iw mcp [options]

Option	Default	Description
`-s, --session`	—	Default session
`-v, --verbose`	off	Log invocations

Environment Variables

Variable	Default	Description
`NEO4J_URI`	`bolt://localhost:7687`	Neo4j URI
`NEO4J_USERNAME`	`neo4j`	Neo4j user
`NEO4J_PASSWORD`	(required for KG)	Neo4j password
`NEO4J_DATABASE`	`neo4j`	Neo4j database
`IW_SESSION`	`default`	Default session ID
`OPENAI_API_KEY`	(optional)	For `--provider openai` + NL queries
`IW_LLM_MODEL`	`gpt-4o-mini`	LLM model