Skip to content

CLI Reference

Jump to bottom
Stas edited this page Mar 15, 2026 · 1 revision

CLI Reference

Global flags

These flags apply to every subcommand:

Flag Short Default Description
--repo <PATH> -r . Path to the repository to analyze
--db <PATH> -d .cartograph/db.sqlite Path to the Cartograph database

The database is created automatically on first use. The path is relative to the working directory, not to --repo.

Example — custom paths:

cartograph --repo ~/projects/myapp --db ~/carto/myapp.sqlite index

Subcommands

index

Parse the repository structure and mine git history. Writes results to the database.

cartograph [--repo PATH] [--db PATH] index

What it does:

  1. Layer 1 — Structure: tree-sitter-rust walks all .rs files, extracts module declarations and use statements, and stores them as Imports edges in the graph.
  2. Layer 2 — Dynamics: runs git log --name-status (capped at 10,000 commits), computes co-change frequency for every file pair, and writes CoChangesWith edges. Then runs git blame to attribute ownership per file as OwnedBy edges.

Re-run index any time to refresh. Entities and edges are upserted — safe to run repeatedly.

Output:

Indexing /path/to/repo...
  Structure: done
  Git history: 412 commits
  Co-changes: 873 pairs
  Ownership: done
Index complete.

If the repo has no git history, Layer 2 steps are skipped with a note.

blast-radius

Show all entities reachable from a given entity in the dependency graph.

cartograph [--repo PATH] [--db PATH] blast-radius <ENTITY> [--depth N]
Argument Default Description
ENTITY required File path or entity name
--depth N / -d N 3 Maximum traversal depth

Output columns: ENTITY, DEPTH, EDGE (the edge kind that creates the connection)

ENTITY                                   DEPTH      EDGE
------------------------------------------------------------
src/store/mod.rs                         1          imports
src/query/blast_radius.rs                2          imports
src/main.rs                              3          imports

Notes:

  • Traversal follows Imports and DependsOn edges outward (downstream).
  • Depth 1 = direct dependencies of the queried entity. Depth 3 = three hops.
  • Use a higher depth with caution on large, highly-connected codebases.

deps

Show direct dependencies of an entity — one hop upstream or downstream.

cartograph [--repo PATH] [--db PATH] deps <ENTITY> [--direction upstream|downstream]
Argument Default Description
ENTITY required File path or entity name
--direction / -d downstream downstream = what this entity depends on; upstream = what depends on this entity

Output columns: ENTITY, KIND

ENTITY                                   KIND
--------------------------------------------------
src/store/schema.rs                      File
src/query/mod.rs                         Module

co-changes

Show files that statistically co-change with the given entity — appear together in git commits.

cartograph [--repo PATH] [--db PATH] co-changes <ENTITY>
Argument Default Description
ENTITY required File path or entity name

Output columns: ENTITY, CONFIDENCE

ENTITY                                   CONFIDENCE
-------------------------------------------------------
src/store/schema.rs                      1.00
src/historian/mod.rs                     0.75

Confidence is normalized across the entire repository — 1.0 is the most frequently co-changed pair. A score of 0.75 means that pair co-changed 75% as often as the top pair.

Requires Layer 2 data (git history). Returns empty if index was run on a repo with no git history.

who-owns

Show code ownership for an entity, derived from git blame.

cartograph [--repo PATH] [--db PATH] who-owns <ENTITY>
Argument Default Description
ENTITY required File path or entity name

Output columns: OWNER (author email), CONFIDENCE

OWNER                          CONFIDENCE
---------------------------------------------
alice@example.com              1.00
bob@example.com                0.55

Ownership is blame-derived: the author who last touched the most lines scores highest. Multiple owners may appear for files with shared history.

Requires Layer 2 data.

hotspots

Show the most highly-connected files in the codebase — those with the highest combined in-degree and out-degree in the dependency graph.

cartograph [--repo PATH] [--db PATH] hotspots [--limit N]
Argument Default Description
--limit N / -l N 20 Number of results to return

Output columns: ENTITY, CONNECTIONS

ENTITY                                   CONNECTIONS
-------------------------------------------------------
src/store/graph.rs                       24
src/lib.rs                               18
src/main.rs                              14

High connection counts indicate files that transitively affect large portions of the codebase — good candidates to review carefully before making changes.

serve

Start the MCP stdio server. Exposes all five Cartograph queries as MCP tools for consumption by Claude Code or any MCP-compatible client.

cartograph [--repo PATH] [--db PATH] serve

The server uses stdio transport and speaks the Model Context Protocol. It does not print to stdout (stdout is reserved for MCP framing); logs go to stderr.

See MCP Server for full setup instructions and tool documentation.

Environment variables

Variable Effect
RUST_LOG Controls log verbosity. E.g. RUST_LOG=debug cartograph index. Logs are written to stderr.

Exit codes

Code Meaning
0 Success
1 Error (printed to stderr)

Clone this wiki locally