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?

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/)
      │  primary: graph.snapshot.bin (RGCL v2 columnar mmap)
      │
      ├── find / callers / callees / relations / inventory / blast-radius / metrics / communities / clones / cpg / slice / inspect
      ├── check / review check / review paths / diff   (CI + temporal PR gate + snapshot compare)
      ├── update / watch / merge                       (incremental + multi-repo park-and-resolve)
      ├── semantic index + query                       (opt-in embedder)
      ├── export                                       (JSON, GraphML, Mermaid, Obsidian, …)
      └── serve                                        (optional HTTP dashboard + semantic API)

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

Capability designs for contributors: design/.

Discover depth (common flags)

rgctl discover . -l java,kotlin,python --with-cfg
rgctl discover . --with-git --git-since 90.days
rgctl discover . --scip index.scip
rgctl discover . -e node_modules,target,.git,vendor

Capability map (concepts only)

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

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 deep-analysis languages use custom tree-sitter plugins with grammar-verified crates/rgctl-lang-*/{id}-ast-coverage.json manifests, single-pass extract_all (ScopeStack + KindDispatchTable + parse_with_pool), and CFG/PDG support. Set RGCTL_AST_COVERAGE_STRICT=1 to fail the build on grammar/manifest drift.

Separately, languages.toml registers ~60 language and config/IaC plugins (Tier 1 + generic tree-sitter + regex + formats). Do not equate “Tier 1 deep analysis” with the full plugin catalog count.

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

Current Tier-1 deep-analysis ids include C, C++, C#, Go, Groovy, Java, JavaScript, Kotlin, PHP, Puppet, Python, Ruby, Rust, TypeScript (plus markdown as a doc plugin; ERB and others with coverage JSON as they land).

Where to go next