CLI command reference

This section documents every command registered by the codespine CLI (npx codespine ). There is one page per command; each explains the command’s arguments, options, underlying graph query, output format, and caveats in depth.

Invocation

The published binary is codespine. Every example in these documents runs it with npx (no global install required):


npx codespine <command> [arguments] [options]

The pipeline

The commands fall into groups that run roughly in order — each stage produces an artifact the next stage consumes:

enrich and cluster annotate the database in place.

Build the graph

Command	Purpose
`extract`	Parse a TypeScript project into a JSONL knowledge graph.
`load`	Import the JSONL graph into an embedded Kùzu database.

Enrich the graph

Command	Purpose
`enrich`	Ingest a V8 CPU profile and attach measured runtime metrics (`metadata.runtime`) onto nodes.
`cluster`	Detect code communities with the Leiden algorithm and attach the module index (`metadata.community`) onto nodes.

Query the graph

Command	Purpose
`find`	Resolve a name (substring) to node ids. The entry point for every other query.
`who-calls`	Direct callers of a symbol.
`calls`	What a symbol calls directly.
`references`	Everything that references a symbol or type (calls, type usage, heritage, instantiation, reads).
`neighbors`	One-hop neighbourhood of a node, in and out, all edge kinds.
`blast-radius`	Every symbol transitively impacted by changing a node.
`dead-exports`	Exported symbols with no inbound references.
`hotspots`	Rank nodes by optimization leverage — runtime self-time, fan-in, call-count, or blast radius.
`cost`	Propagate self cost into inclusive cost and rank nodes by share of total; or break one node’s cost into callee/caller attribution.

Verify & measure an edit

Command	Purpose
`verify`	Run the project’s `typecheck` + `test` scripts as one keep/revert gate for an edit; degrades to type-check-only, reported honestly, when there is no test script.
`benchmark`	Measure a target node’s runtime metric (profile → enrich → cost) over N runs and report the median + spread, with an advisory baseline→after delta.

Use the graph

Command	Purpose
`webview`	Serve the graph in an interactive web visualisation.
`report`	Write a `CODEBASE_BRIEF` — one snapshot of structure, impact, runtime, and boundary (markdown / JSON / PDF).
`install`	Install the agent’s slash commands and `codespine-query` skill into a project’s `.claude/`.

The autonomous optimization agent is not a CLI command. It is the /codespine-optimize Claude Code slash command (see Agent), which calls the query commands above to find a verified-safe edit and apply it.

Common conventions

Node ids always come from a query. Run find (add --json) or read an id out of another query’s output. Ids encode the declaration line (kind:relPath#name@line) and shift whenever the code moves, so never write them by hand and never reuse them across extractions.
-o, --output-folder <dir> defaults to ./.codespine on every command (the database is read from <dir>/graph.kuzu), matching load’s default output. Override it to query a database elsewhere.
--json is available on every query command and emits the exact machine-readable shape the optimization agent consumes.

See also: Getting Started, the Static Analysis guide (these commands organised by the analysis question they answer), and the Concepts.