Commands

Commands

Complete reference for the codegraph CLI. Every command is a subcommand of codegraph (for example codegraph extract, codegraph query "..."). Run codegraph --help for the generated summary, or codegraph <command> --help for a single command.

Most read commands operate on codegraph-out/graph.json by default; build it first with extract. See Quickstart for an end-to-end walkthrough.

Summary

Command	Purpose
extract	Build the graph for a directory and write codegraph-out/.
export	Re-emit an output format from an existing graph.json (no re-extraction), or push live to a database.
query	Find a relevant subgraph for a free-text query.
search	Structural search (CGQL) and named architectural patterns. Not text search.
path	Shortest path between two nodes.
explain	Show a node and its neighbours.
update	Incrementally rebuild after files change (or fully with --full).
watch	Watch the working tree and rebuild on change (debounced).
affected	Nodes that transitively depend on a node (reverse-impact).
diff	Time-travel: diff the graph between two git revisions (dependencies, removed APIs, drift, cycles, hotspots).
hook	Manage git hooks and the graph.json merge driver.
serve	Run the MCP server (stdio or HTTP).
ingest	Ingest an external source into the graph, or fetch a URL for the next extract.
install	Install the CodeGraph skill for a host assistant.
uninstall	Remove the CodeGraph skill for a platform (or all).
prs	Graph-aware PR dashboard and per-PR detail.
skill	Maintain the generated skill artifacts (dev/CI).
workspace	Multi-repo / monorepo federation.
global	Manage the cross-repo global graph store (~/.codegraph).
merge-graphs	Compose several graph.json files into one namespaced graph.
cache	Maintain the on-disk extraction cache.

There is also an internal merge-driver command. It is hidden from --help and invoked by git, not users; see hook.

extract

Scan a directory, build the knowledge graph, and write the artifact set to codegraph-out/.

Syntax:

codegraph extract [PATH] [--directed] [--obsidian] [--wiki] [--semantic]

Arguments and flags:

Name	Default	Description
PATH	.	Root directory to scan.
--directed	off	Produce a directed graph.
--obsidian	off	Also write an Obsidian vault (one note per node) under codegraph-out/obsidian/.
--wiki	off	Also write a Markdown wiki under codegraph-out/wiki/.
--semantic	off	Run the LLM semantic pass over documents/papers and enable the LLM dedup tiebreaker. Requires an API key in the environment (for example OPENAI_API_KEY). Makes paid API calls.

The default run is fully offline and needs no API key. It always writes graph.json, graph.html, GRAPH_REPORT.md, graph.graphml, graph.cypher, graph.dot, callflow.html, tree.html, graph.svg, and graph-3d.html into codegraph-out/. With --obsidian and --wiki it adds the obsidian/ and wiki/ directories. Markdown heading structure is always extracted; the LLM concept pass runs only with --semantic.

Example:

codegraph extract . --directed

See Extraction, Output-Formats, Semantic-Analysis, and Visualizations.

export

Regenerate one output format from an existing graph.json without re-extracting, or push the graph live to a database.

Syntax:

codegraph export <FORMAT> [--graph <PATH>] [--out <PATH>] [--repo <TAG>] [--push <URI>] [--user <USER>] [--password <PW>]

Arguments and flags:

Name	Default	Description
FORMAT	required	One of: json, html, svg, graphml, cypher, dot, callflow (alias callflow-html), tree, 3d (alias force3d), obsidian, wiki, report, neo4j, falkordb.
--graph	codegraph-out/graph.json	Source graph.json.
--out	alongside the source graph.json	Output file or directory.
--repo	none	Scope to one federated member (its repo tag) before exporting.
--push	none	For neo4j/falkordb: push live to this URI (for example bolt://localhost:7687 or falkordb://localhost:6379) instead of writing the cypher script. Requires building with --features push.
--user	neo4j	Auth user for --push (Neo4j).
--password	none	Auth password for --push (or set NEO4J_PASSWORD / FALKORDB_PASSWORD).

Notes: report recomputes communities and analysis from the loaded graph. export json --repo X with no --out is rejected, because the default output name would overwrite the source graph.json with a scoped subgraph; pass --out to write the scoped graph elsewhere. Live --push requires a build with --features push; otherwise neo4j/falkordb write the cypher script.

Example:

codegraph export svg --out diagram.svg
codegraph export neo4j --push bolt://localhost:7687 --password secret

See Output-Formats and Workspaces-and-Federation.

query

Find a relevant subgraph for a free-text query.

Syntax:

codegraph query <TEXT> [--graph <PATH>] [--max-nodes <N>] [--repo <TAG>] [--dfs]

Arguments and flags:

Name	Default	Description
TEXT	required	Free-text query.
--graph	codegraph-out/graph.json	Source graph.
--max-nodes	30	Maximum nodes in the returned subgraph.
--repo	none	Scope to one federated member (its repo tag).
--dfs	off	Expand the subgraph depth-first instead of breadth-first (favors deep call chains over broad neighbourhoods).

Prints the matched seed nodes and the resulting subgraph (nodes and labelled edges). If nothing matches, it reports no matches.

Example:

codegraph query "auth token refresh" --max-nodes 50

See Querying.

path

Shortest path between two nodes, each given by id or label.

Syntax:

codegraph path <FROM> <TO> [--graph <PATH>] [--repo <TAG>]

Name	Default	Description
FROM	required	Source node id or label.
TO	required	Target node id or label.
--graph	codegraph-out/graph.json	Source graph.
--repo	none	Scope to one federated member (its repo tag).

Prints the path as labels joined by arrows, or a message if one or both endpoints cannot be resolved or no path exists.

Example:

codegraph path "LoginController" "Database"

See Querying.

explain

Show a node and its immediate neighbours.

Syntax:

codegraph explain <NODE> [--graph <PATH>] [--repo <TAG>]

Name	Default	Description
NODE	required	Node id or label.
--graph	codegraph-out/graph.json	Source graph.
--repo	none	Scope to one federated member (its repo tag).

Prints the node's label, source file, community (if assigned), and each neighbour with the edge direction and relation.

Example:

codegraph explain "PaymentService"

See Querying.

search

Structural search over the graph with CGQL (a small Cypher-inspired query language), or a built-in architectural pattern. This is not text search: it matches on structure (kind, visibility, lines-of-code, fan-in/out, degree, community) and relationships.

Syntax:

codegraph search [QUERY] [--pattern <NAME>] [--list-patterns]
                 [--explain] [--save <NAME>] [--saved <NAME>] [--list-saved]
                 [--graph <PATH>] [--repo <TAG>] [--json] [--limit <N>]

Name	Default	Description
QUERY	none	A CGQL query (omit when using --pattern/--saved/--list-patterns).
--pattern	none	Run a built-in pattern instead of a query.
--list-patterns	off	List the built-in patterns and exit.
--explain	off	Print the query plan (scan, joins, filter, project/aggregate) without running it.
--save	none	Save the given query under a name (codegraph-out/cgql/<name>.cgql).
--saved	none	Run a previously saved query by name.
--list-saved	off	List saved query names and exit.
--graph	codegraph-out/graph.json	Source graph.
--repo	none	Scope to one federated member (its repo tag).
--json	off	Emit results as JSON.
--limit	50	Max rows to display.

CGQL

MATCH pattern [WHERE expr] RETURN items [LIMIT n]

• pattern is (var:kind) node patterns joined by relationships -[:rel]->, <-[:rel]-, or -[:rel]- (either direction). The :kind and relationship name are optional.
• Variable-length paths: a relationship may repeat: -[:calls*1..3]-> (1 to 3 hops), * (1 to 8), *2 (exactly 2), *2.. / *..3. Bounded by a cap so a cycle always terminates; matches by reachability within the range.
• Node properties usable in WHERE / comparisons: kind, name, file, lang, visibility, loc, fan_in, fan_out, degree, community.
• Operators: =, !=, <, <=, >, >=, and =~ (regex on a string property); combine with AND / OR / NOT and parentheses.
• RETURN takes bound variables (RETURN a, b), or an aggregation: RETURN c.community, count(c) groups by the property and counts per group; count(*) totals. (A var.field projection returns the distinct values.)

Evaluation is lenient: a comparison against a missing property (e.g. loc on a node with no span, or any property on a graph built before metadata enrichment) simply does not match, rather than erroring.

Examples:

codegraph search "MATCH (c:class) WHERE c.loc > 500 AND c.fan_out > 20 RETURN c"
codegraph search 'MATCH (c:struct) WHERE c.name =~ "Extractor$" RETURN c'
codegraph search "MATCH (a:class)-[:implements]->(b:interface) RETURN a, b"
codegraph search "MATCH (a)-[:calls*1..3]->(b) RETURN a, b"   # transitive callers
codegraph search "MATCH (c:class) RETURN c.community, count(c)" # group + count
codegraph search "MATCH (c:class) WHERE c.loc > 500 RETURN c" --explain
codegraph search "MATCH (c:class) RETURN c" --save big_classes
codegraph search --saved big_classes

Named patterns

codegraph search --list-patterns lists them; --pattern <name> runs one:

Pattern	Matches
god-class	Classes over 500 LOC with more than 20 outgoing dependencies.
singleton	Classes that hold or return an instance of their own type.
factory	Functions/methods returning an abstract type with 2+ implementations.
observer	Subject classes holding a field of an interface implemented by 2+ types.
service-locator	Classes accessed from 3+ distinct communities.

The patterns are structural heuristics over the enriched graph; their precision depends on how much kind/visibility a language extractor supplies (see [Extraction]). service-locator requires community assignments (build with codegraph extract).

codegraph search --pattern god-class
codegraph search --pattern singleton --json

See Querying, Extraction, and Analysis-and-Reports.

update

Incrementally rebuild the graph after files change, or do a full rebuild.

Syntax:

codegraph update [PATHS...] [--full] [--directed] [--force]

Name	Default	Description
PATHS...	none	Changed file paths (repo-relative). Empty plus no --full triggers a full rebuild.
--full	off	Rebuild every code file from scratch (preserves semantic nodes).
--directed	off	Build directed when there is no existing graph to inherit from.
--force	off	Bypass the shrink guard.

Behavior: when no paths are given on the command line (and not --full), changed paths are read from the CODEGRAPH_CHANGED environment variable (newline-delimited), which is how the post-commit hook passes them. The command inherits the existing graph and its directed flag when present, serializes concurrent rebuilds with a lock (queuing paths if another rebuild holds it), and writes the same artifact set as extract.

Example:

codegraph update src/auth.rs src/db.rs
codegraph update --full

See Incremental-Updates.

watch

Watch the working tree and rebuild incrementally on change, debounced.

Syntax:

codegraph watch [--directed] [--force]

Name	Default	Description
--directed	off	Build directed when there is no existing graph to inherit from.
--force	off	Bypass the shrink guard on each rebuild.

Watches the current directory recursively, debounces a burst of saves into one rebuild, ignores the output/VCS/build subtrees (so writing graph.json cannot self-trigger), and rebuilds on changed code and Markdown (.md, .mdx, .qmd) files. Stop with Ctrl-C.

Example:

codegraph watch --directed

See Incremental-Updates.

affected

List nodes that transitively depend on a node (reverse-impact analysis).

Syntax:

codegraph affected <NODE> [--graph <PATH>] [--depth <N>] [--relation <REL>]...

Name	Default	Description
NODE	required	Node id, label, bare name, source file, or unique label substring.
--graph	codegraph-out/graph.json	Source graph.
--depth	2	Max hops to walk backward.
--relation	structural impact relations	Restrict to these edge relations; repeatable.

When no --relation is given, the default structural impact relations are: calls, references, imports, imports_from, re_exports, inherits, extends, implements, uses, mixes_in, embeds, depends_on, reads_from. Containment relations (such as contains/method) are intentionally excluded. Output lists each affected node with the relation it was reached through and its source location.

Example:

codegraph affected src/config.rs --depth 3
codegraph affected "User" --relation calls --relation references

See Querying and Analysis-and-Reports.

diff

Time-travel: compare the code graph at two git revisions and report what changed architecturally.

Syntax:

codegraph diff [REV1] [REV2] [--since <DATE>] [--root <DIR>] [--directed] [--scope <PREFIX>] [--top <N>] [--module-depth <N>] [--json] [--report <PATH>] [--html <PATH>] [--no-cache]

Name	Default	Description
REV1	required*	Base revision (for example HEAD~10, a branch, or a SHA). *Optional when --since is given.
REV2	working tree	Target revision; omit to compare the base against the current working tree.
--since	none	Resolve the base from a date (latest commit on HEAD at or before it, by commit date). Mutually exclusive with REV1.
--root	.	Repo root.
--directed	off	Build a directed graph for each revision.
--scope	none	Limit reports to source files under this repo-relative path prefix.
--top	20	Max rows per ranked section.
--module-depth	2	Path-component depth defining a "module" (for example 2 => crates/foo).
--json	off	Emit the full report as JSON.
--report	none	Also write a Markdown report to this path.
--html	none	Also write a self-contained, theme-aware HTML report to this path.
--no-cache	off	Always rebuild; skip the per-commit snapshot store.

Each revision is materialized into a throwaway git worktree and built with the same pipeline as extract (nothing is written into your working tree). Built graphs are cached per commit SHA under codegraph-out/history/, so the first diff of a cold repo builds two full graphs and later diffs of the same commits are near-instant. The report has five sections:

• Added / removed dependencies — module-to-module dependency edges that appeared or disappeared.
• Removed APIs — code symbols that were referenced from another file and are now gone (an export-surface heuristic).
• Architectural drift — change in module coupling (cross-module edge fraction) overall and per module, plus community count.
• New cycles — dependency cycles present in REV2 but not in REV1.
• Hotspots of change — files ranked by line churn (git diff --numstat) plus graph node churn.

Example:

codegraph diff HEAD~10 HEAD
codegraph diff v1.2.0 main --report drift.md
codegraph diff HEAD --scope crates/auth --json
codegraph diff --since 2026-01-01 --html drift.html

See Analysis-and-Reports and Incremental-Updates.

refactor

Safe refactor: plan a single-symbol rename and verify the graph after an AI agent applies it. CodeGraph never edits source itself; it produces an execution plan for the agent (Claude / Codex / Cursor) and then checks invariants.

refactor rename

Syntax:

codegraph refactor rename <NAME> --to <NEWNAME> [--id <NODEID>] [--file <SUBSTR>] [--root <DIR>] [--graph <PATH>] [--out <DIR>] [--min-confidence <F>] [--json]

Name	Default	Description
NAME	required	The symbol to rename (its name, or a node id).
--to	required	The new name.
--id	none	Disambiguate by node id when the name matches several definitions.
--file	none	Disambiguate by file-path substring.
--root	.	Repo root; referencing files are read from here for column-accurate sites.
--graph	codegraph-out/graph.json	Graph to plan against.
--out	codegraph-out/refactor	Output directory for the plan.
--min-confidence	0.8	Minimum per-site confidence score [0,1] to land in edits vs review.
--json	off	Emit the plan as JSON to stdout.

The symbol is resolved to a definition node. If the name matches several definitions the command lists the candidates (with --id hints) and exits — ambiguity is surfaced, never silently guessed. The plan recovers concrete edit sites: the definition plus every resolved reference. Call sites get a column-accurate span from the AST cache (member calls fall back to line-only); other references (inherits/implements/uses) use the edge line and are flagged for the agent to locate the token. A whole-word textual scan additionally enumerates references the conservative graph does not record as edges (type annotations, enum-variant paths); these land in review (disable with --no-text-scan). Sites carry a repo tag on a federated graph, so a cross-repo rename is surfaced (verify is single-repo in v1).

Each site is scored (EXTRACTED / INFERRED / AMBIGUOUS); low-confidence or ambiguous sites are routed to a review list instead of edits. A name collision (the new name already exists) is flagged. Two artifacts are written, plus a before-graph.json snapshot used by verify:

• plan.json — machine-readable: target, new name, overall confidence + score, blast radius, ordered edits, and a review list.
• plan.md — agent-readable narrative: definition first, references grouped by file, the review list, and the exact verify command.

Examples:

codegraph refactor rename UserService --to AccountService
codegraph refactor rename User --to Account --file models/   # disambiguate
codegraph refactor rename Confidence --to Trust --id src_confidence_confidence --json

refactor move / extract

Relocate a symbol's definition to another module. move targets an existing file; extract a new one. The symbol name is unchanged — what changes is where it lives and the imports that reach it.

codegraph refactor move <NAME> --to <FILE> [--id <ID>] [--file <SUBSTR>] [--root <DIR>] [--graph <PATH>] [--out <DIR>] [--json]
codegraph refactor extract <NAME> --to <NEWFILE> [ ...same flags... ]

The plan identifies the definition block to cut (its span), the destination, one import-update site per referencing file, the resolved usages for context, and a destination name collision if any. Verify with --relocate.

codegraph refactor move parse_config --to crates/core/src/config.rs
codegraph refactor extract Helper --to src/helpers.rs

refactor verify

Syntax:

codegraph refactor verify --plan <PLAN.JSON> [--root <DIR>] [--relocate] [--json]

Run after the agent applies the plan's edits. It rebuilds the current source and checks invariants against the pre-edit snapshot, exiting non-zero on failure. For a rename:

• definition-renamed — the old definition is gone and the new one exists at the target's file (matched by full path + kind).
• references-preserved — every file that referenced the old symbol still references the renamed one (compares the set of referencing files, naming any that went missing).
• no-lost-nodes — no located code nodes were dropped (guards against an accidental deletion during the rename).
• no-new-cycles — no dependency cycle exists that was absent before.

For a move/extract (--relocate): definition-relocated (the definition now lives in the destination file, not the old one), references-preserved, and no-new-cycles.

Scope (v1): a single named symbol; rename/move/extract. Cross-repo is surfaced in the plan but verify rebuilds a single repo. No signature changes. The plan format is designed to extend further.

See Analysis-and-Reports.

hook

Manage git hooks (post-commit/post-checkout) and the graph.json merge driver.

Syntax:

codegraph hook <ACTION>

Actions:

Action	Description
install	Install the hooks and register the merge driver (idempotent).
uninstall	Remove the hooks (and the CodeGraph blocks from any shared hook files).
status	Show which hooks are currently installed.

Each action prints the per-hook installed/not-installed state. The hooks keep graph.json current after commits and checkouts; the merge driver union-composes both sides so graph.json never conflicts during merges.

Example:

codegraph hook install
codegraph hook status

See Incremental-Updates.

serve

Run the MCP server exposing read-only graph tools (and PR tools) to an AI assistant.

Syntax:

codegraph serve [--graph <PATH>] [--http <ADDR>] [--api-key <KEY>] [--source-root <DIR>]

Name	Default	Description
--graph	codegraph-out/graph.json	Graph to serve.
--http	none (stdio)	Serve over HTTP at this address (for example 127.0.0.1:8765) instead of stdio. The MCP endpoint is /mcp.
--api-key	none	Require this API key for HTTP requests (or set CODEGRAPH_API_KEY).
--source-root	dir above codegraph-out/	Trusted root for resolving a node's source file in the get_source tool (path-traversal jailed).

Defaults to stdio transport. The MCP server reports protocol 2025-06-18 and exposes 17 read-only tools, prompts, completions, resource templates/subscriptions, and structured tool output. When serving HTTP on a wildcard address with no API key, it prints a warning.

Example:

codegraph serve
codegraph serve --http 127.0.0.1:8765 --api-key secret

See MCP-Server and Assistant-Integration.

ingest

Ingest an external source into the graph, or fetch a URL into codegraph-out/ingested/ for the next extract.

Syntax:

codegraph ingest <SOURCE> [SOURCE-ARGS]

Sources:

Source	Argument	Description
cargo	<PATH>	A Cargo workspace root; adds crate nodes and internal-dependency edges.
mcp	<FILE>	An MCP config file (.mcp.json, claude_desktop_config.json, etc.).
scip	<FILE>	A SCIP-index JSON file (simplified shape); adds symbol nodes and edges.
pg	[DSN] (default empty)	A live PostgreSQL database; adds table/view/function nodes and foreign-key edges. Empty DSN uses PG* env vars. Requires --features pg.
url	<URL>	A URL, fetched (SSRF-guarded) into codegraph-out/ingested/.
office	<FILE>	An office spreadsheet (.xlsx/.xls/.ods), converted to markdown in codegraph-out/ingested/. Requires --features office.
gws	<FILE>	A Google-Workspace pointer (.gdoc/.gsheet/.gslides), exported to markdown via the gws CLI. Requires --features gws.
media	<FILE>	A local audio/video file, transcribed to markdown. Requires --features media.

The cargo, mcp, scip, and pg sources merge their nodes/edges into codegraph-out/graph.json and rewrite the artifacts. The url, office, gws, and media sources write into codegraph-out/ingested/ and require a follow-up codegraph extract (or update) to index. Feature-gated sources error with a rebuild hint when the feature is not compiled in.

Example:

codegraph ingest cargo .
codegraph ingest url https://example.com/spec.html

See Ingestion.

install

Install the CodeGraph skill for a host assistant in the current directory.

Syntax:

codegraph install [PLATFORM] [--global]

Name	Default	Description
PLATFORM	claude	One of: claude, agents, codex, opencode, gemini, cursor, copilot, kilo.
--global	off	Codex only: register the MCP server in the global ~/.codex/config.toml (per-repo server) for the Codex desktop app, instead of the project .codex/.

codex gets extra wiring: a native MCP server and a SessionStart hook (project .codex/ by default, or a global per-repo server with --global for the desktop app). Prints the files written.

Examples:

codegraph install claude
codegraph install codex            # Codex CLI (project .codex/)
codegraph install codex --global   # Codex desktop app (global ~/.codex)

See Assistant-Integration.

uninstall

Remove the CodeGraph skill for a platform.

Syntax:

codegraph uninstall [PLATFORM] [--all] [--global]

Name	Default	Description
PLATFORM	claude	The platform to remove (same set as install).
--all	off	Uninstall from every supported platform (ignores PLATFORM).
--global	off	Codex only: remove this repo's server from the global ~/.codex/config.toml.

Example:

codegraph uninstall cursor
codegraph uninstall codex --global
codegraph uninstall --all

See Assistant-Integration.

prs

Graph-aware PR dashboard, single-PR detail, triage, and conflict views. Requires the gh CLI.

Syntax:

codegraph prs [NUMBER] [--repo <OWNER/NAME>] [--base <BRANCH>] [--graph <PATH>] [--triage] [--conflicts]

Name	Default	Description
NUMBER	none	PR number for a detailed view; omit for the dashboard.
--repo	current directory's repo	Target repo owner/name.
--base	the repo's default branch	Base branch to filter to.
--graph	codegraph-out/graph.json	Graph used for blast-radius (communities + node count).
--triage	off	Ranked actionable PRs with blast radius (deterministic; no LLM).
--conflicts	off	PRs that touch the same graph community (merge-order risk).

With no number and no flags it prints the open-PR dashboard. A number shows that PR's detail including graph blast radius. --conflicts and --triage are dashboard-level views and take precedence over a PR number. Graph blast radius is attached only when a graph.json is present. For LLM-summarized triage, use the MCP server's triage_prs tool.

Example:

codegraph prs
codegraph prs 142
codegraph prs --triage

See PR-Dashboard.

skill

Maintain the generated skill artifacts (development/CI). Checks for drift against the committed snapshots, or re-blesses them after an intentional change.

Syntax:

codegraph skill <ACTION>

Action	Description
check	Re-render the skill artifacts and fail if they differ from the committed expected/ snapshots (CI anti-drift guard).
bless	Rewrite the committed expected/ snapshots from the current render.

Example:

codegraph skill check

See Development.

workspace

Multi-repo / monorepo federation: discover members, build a federated graph, and scope queries to a repo.

Syntax:

codegraph workspace <ACTION>

Actions:

Action	Syntax	Description
init	init [--scan-repos [DIR]] [--depth <N>] [--max <N>]	Write codegraph-workspace.toml, auto-discovering members. --scan-repos also scans a parent dir for sibling git repos and appends [[repos]] entries (bare flag scans the parent of the current repo). --depth defaults to 3, --max defaults to 50.
add	add <TARGET>	Add a member: an existing local path becomes a members entry, a git URL becomes a [[repos]] entry.
discover	discover [PATH] [--depth <N>] [--max <N>]	Scan a parent dir for sibling git repos and federate them without writing a manifest. PATH defaults to the parent of the current repo; --depth defaults to 3, --max to 50.
build	build [--changed] [--directed]	Build all members and federate into codegraph-out/graph.json. --changed only rebuilds members that changed; --directed produces a directed federated graph.
federate	federate <DIR>	Compose from a directory of published <member>/graph.json artifacts.
sync	sync	Pull remote git members, then rebuild deltas.
status	status	Show each member's change status (no build).
list	list	List the workspace members (local members and remote repos).

build, federate, discover, and sync write the federated graph artifacts plus a surfaces/ directory of per-member export surfaces, and print a build summary (node/edge/community counts, cross-repo links, per-member sizes).

Example:

codegraph workspace init --scan-repos
codegraph workspace build --directed
codegraph workspace status

See Workspaces-and-Federation.

global

Manage the cross-repo global graph store at ~/.codegraph.

Syntax:

codegraph global <ACTION>

Action	Syntax	Description
add	add <GRAPH> [--as <TAG>]	Add (or update) a repo's graph.json under a tag. The tag defaults to the graph's grandparent directory name. Skipped when the source is unchanged.
remove	remove <TAG>	Remove a repo's nodes from the global store.
list	list	List the repos in the store with node/edge counts and source path.
path	path	Print the global graph path.

Example:

codegraph global add ./codegraph-out/graph.json --as backend
codegraph global list

See Workspaces-and-Federation.

merge-graphs

Compose several graph.json files into one namespaced graph.

Syntax:

codegraph merge-graphs <GRAPHS...> [--out <PATH>]

Name	Default	Description
GRAPHS...	required (at least one)	The graph.json files to merge. Each file's tag is its grandparent directory name.
--out	codegraph-out/merged-graph.json	Output path.

Prints the number of graphs merged, the output path, node/edge totals, and the tags. Errors if no graphs are given.

Example:

codegraph merge-graphs repo-a/codegraph-out/graph.json repo-b/codegraph-out/graph.json --out merged.json

See Workspaces-and-Federation.

cache

Maintain the on-disk extraction cache at codegraph-out/cache.

Syntax:

codegraph cache <ACTION>

Action clear:

codegraph cache clear [PATH] [--recursive]

Name	Default	Description
PATH	.	Repo/workspace root whose codegraph-out/cache to remove.
--recursive	off	Also remove every codegraph-out/cache found beneath PATH (federated member caches), via a bounded, noise-pruned walk that skips node_modules and .git.

The AST cache normally self-invalidates when extractors change; use clear for a guaranteed cold start or suspected corruption. Only the regenerable codegraph-out/cache subtree is ever removed.

Example:

codegraph cache clear
codegraph cache clear . --recursive

See Extraction.

merge-driver (internal)

codegraph merge-driver <BASE> <CURRENT> <OTHER> is a git merge driver for graph.json. It is hidden from --help and invoked by git as %O %A %B, not by users. It union-composes both sides into CURRENT so graph.json never conflicts. It is registered automatically by codegraph hook install.