Introduction to rgctl

What rgctl is and how a code knowledge graph works — concepts before commands.

Hands-on: Installation · Guides (CoolStore) · User Guide (ecommerce-java).
Agents: agent-skill · USER_AGENTS_TEMPLATE · rgctl install --skill.
Contribute to rgctl: AGENTS.md. JSON: json-api.md.

What problem does rgctl solve?

Modern codebases are too large to hold in your head — or in an LLM context window. Changing a function raises reachability questions: who calls it, what depends on it, are security-sensitive paths involved, where is complexity concentrated?

rgctl turns the repository into a structured graph — functions, types, calls, imports, docs, and more — so you ask structural questions and get deterministic answers instead of grepping and guessing. Built in Rust for speed and predictable memory on large repos. Primary consumer output is compact -f json for agents and scripts.

What is a code knowledge graph?

Everyday idea	In rgctl
Places on the map	Nodes — functions, classes, files, modules, headings, …
Roads	Edges — typed relations (`CALLS`, `CONTAINS`, `IMPORTS`, `VIOLATES`, …)
The map file	Artifacts under `{repo}/.rgctl/` after `discover`

Reachability (who can reach whom along call paths) is pre-computed and stored compactly — that is why blast-radius stays fast on large graphs.

You do not need graph theory to use the CLI: indexing builds the map; commands query the map.

How the pieces fit

  Your repo (source)
      │
      │  discover  (cd repo && rgctl discover .   — or  rgctl -r PATH discover)
      ▼
  artifact root ({repo}/.rgctl/)
      │
      ├── find / callers / relations / blast-radius / metrics / communities / cpg / slice / inspect
      ├── check / pr-check / diff          (CI + snapshot compare)
      ├── semantic index + query           (opt-in embedder)
      ├── export                           (JSON, GraphML, Mermaid, Obsidian, …)
      └── serve                            (optional HTTP dashboard + semantic API)

Once (or after large changes): discover from the repo you mean to index — see Discovering and indexing for -r vs . pitfalls.
Many times: query commands read {repo}/.rgctl/. Prefer -f json and never scrape stderr (JSON API).
Agents: install the pack (rgctl install --skill --tools …) — single skill rgctl (agent-skill).
Dashboard: optional UI after discover --with-dashboard + serve — not required for structural answers.

Capability designs for contributors: design/.

Discover depth (common flags)

Flags	Use
(default)	Fast graph + metrics caches
`--with-cfg`	CFG/PDG archive (needed for `slice`, `inspect`, `cpg`, taint)
`--with-taint`	Discover-time taint (with CFG)
`--with-kantra`	Konveyor Kantra rule eval (Java-oriented; `VIOLATES` edges)
`--full`	Full pipeline (large corpora / Gate B style runs)
`--with-dashboard` / `--export-migration-hints`	Opt-in UI bundle / migration JSON

rgctl discover . -l java,kotlin,python --with-cfg
rgctl discover . -e node_modules,target,.git,vendor

Capability map (concepts only)

Step-by-step how-tos: Guides. Full CLI walkthrough: User Guide.

Capability	Intent
discover	Index repo → graph + analytics caches under `.rgctl/`
find / callers / relations / inventory	Structured graph queries (agent-facing)
blast-radius	Upstream impact / reachability for a symbol
slice / taint	Statement-level data/control dependence; source→sink
inspect	CFG / PDG / dominance for one function
cpg	Hybrid CALL + CFG/PDG façade (mutations, flows)
metrics / communities	PageRank, betweenness, label-propagation clusters
semantic	Opt-in natural-language / keyword search over functions
export	Subgraph / projection export (JSON, GraphML, Mermaid, Obsidian, …)
check / pr-check	CI policy on blast-radius; temporal PR gate (base/head snapshots)
diff	Compare two columnar snapshots (digest + `diff_snapshots`)
migration hints	Package roadmap JSON (`--export-migration-hints`)
Kantra	Migration-rule findings during discover (`--with-kantra`)
install	Bundle agent skills / optional policy into IDEs
serve	Foreground HTTP dashboard + semantic HTTP API for one repository

Markdown / docs: discover indexes .md / .mdx by default (headings, links, frontmatter). Use find / relations on module nodes and references edges; function semantic search stays separate. See guide.

Languages

Tier 1 support is custom tree-sitter plugins. What each plugin handles is declared in
crates/rgctl-lang-*/{id}-ast-coverage.json (grammar pin + named-kind → handler). Extensions and aliases live in languages.toml.

The website /docs/languages/ pages are generated from those JSON files at build time — do not maintain parallel hand-written coverage tables. Pointers for contributors: languages/README.md · tier-1-language-support.md.

Current Tier 1 ids include C, C++, C#, Go, Groovy, Java, JavaScript, Kotlin, PHP, Puppet, Python, Ruby, Rust, TypeScript (plus markdown as a doc plugin).

Where to go next

You want…	Go to
Install / verify the binary	Installation
Feature how-tos on CoolStore	Guides
Full CLI + ecommerce-java	User Guide
Agent pack (skills)	agent-skill
Paste into another repo	USER_AGENTS_TEMPLATE
Language support matrix	languages/README.md (JSON SSOT → website)
JSON fields / `schema_version`	json-api.md
HTTP `serve` API	HTTP Server and Dashboard
Latest release notes	v0.4.17
Contribute / cold profiles	AGENTS.md · docs hub — For contributors
Research map	further-reading.md