CLI Commands

cr is the CodeRadius command-line interface. It ingests source code and infrastructure declarations into a graph database, then answers architecture questions against that graph: what a service depends on, what breaks if you change a file, which governance rules are violated. This page is the full command reference.

Install it from source (requires Bun ≥ 1.0 and Node.js ≥ 22):

git clone https://github.com/coderadius-ai/coderadius.git
cd coderadius && bun install && bun link

Quick Start

# Start infrastructure
cr up

# Analyze your codebase architecture
cr analyze code ./services/*

# Open the Architecture Dashboard
cr ui

# Predict blast radius of code changes
cr blast

# Connect coding agents to the graph
cr mcp configure

Global Usage

cr [command] [subcommand] [options]
cr --version
cr --help

Command categories:

Legacy aliases: sync (→ analyze), eval blast (→ blast), chat (→ ask), start (→ up), stop (→ down), doc (→ docs), team-alias (→ config team-alias), completion (→ config completion) all still work. They're hidden from --help; use the canonical names in new scripts, but old CI pipelines and tutorials referencing these don't break.

Init

Initializes the CodeRadius workspace for the current directory or user environment.

What it does:

1. Creates ~/.coderadius/config/settings.json with an LLM provider choice: Google AI Studio (default), Anthropic Claude, OpenAI, Ollama, Google Vertex AI, or AWS Bedrock
2. Creates ~/.coderadius/config/credentials.json (chmod 600) for API keys
3. Interactively generates a .crignore file using AI analysis of the current directory tree to exclude frontend noise, vendored dependencies, and generated files
4. Optionally installs shell autocompletion for cr

cr init

This command is interactive. It requires no flags but walks you through several prompts.

Example session:

  ◆ Which LLM provider would you like to use?
  │  ● Google AI Studio (API key, simplest)
  │  ○ Anthropic Claude
  │  ○ OpenAI
  │  ○ Ollama (local, no API key needed)
  │  ○ Google Vertex AI (GCP project required)
  │  ○ AWS Bedrock (uses AWS CLI credentials)

  ◆ Fast model (bulk code analysis): gemini-2.5-flash

  ◆ Do you want to run the AI now to generate a .crignore?
    Yes / No

Picking vertex additionally prompts for a Google Cloud Project ID. Picking bedrock reuses your existing AWS CLI credentials; no separate prompt.

Note: After running cr init, your configuration is stored globally at ~/.coderadius/config/settings.json. You can override it on a per-project basis using a local .env file. The format uses a concise provider/model string syntax.

Models are configured per tier: fast covers high-volume work (ingest, mcp), smart covers quality work (chat, doc). A per-action key (e.g. "chat": "...") overrides its tier:

{
    "ai": {
        "fast": "vertex/gemini-3.1-flash-lite",
        "smart": "vertex/gemini-3.1-pro",
        "embedding": "openai/text-embedding-3-small"
    }
}

Architecture Analysis

Commands for analyzing codebases and building the architectural graph. All analysis commands are subcommands of cr analyze.

Analyze Code

The primary analysis command. Analyzes source code directories, parses configuration files, extracts tainted functions, and upserts all results into the Memgraph graph database. The --depth flag controls analysis depth.

cr analyze code [paths...] [options]

Arguments:

Options:

Depth Levels

Examples:

# Analyze the current directory (default: semantic depth)
cr analyze code

# Analyze multiple service roots
cr analyze code ./services/payments ./services/identity ./services/notifications

# Analyze all repos in a directory (glob)
cr analyze code ./repos/*

# Structure-only scan (no LLM, fast)
cr analyze code ./repos/* --depth structure

# Full data contract extraction
cr analyze code ./services/* --depth contracts

# Force complete re-analysis (no cache)
cr analyze code ./services/* --force

# CI mode: output JSON telemetry to stdout
cr analyze code --source-strategy ci --json

# Increase LLM parallelism for faster extraction
cr analyze code ./services/* --llm-concurrency 10

# Read targets from a file instead of the shell expanding globs
cr analyze code @targets.txt

Telemetry Output:

After a run, the CLI prints an ingestion report:

• Performance: duration, LLM time, parsing time, files processed/skipped, functions ingested/unchanged
• Pipeline Funnel: functions parsed, dropped (untainted / all gates), survivors per gate (UseCase, Convention, Synthetic, Taint, DI, Framework, API Client), cache hits, static bypass rate, retries/failures
• Agentic Metadata: entities enriched vs. attempted, enrichment time, failure buckets
• Token Usage: input/cached/output tokens, cache hit rate, per-phase breakdown
• Economics: LLM cost, embedding cost, total estimated cost

Analyze Infra

Ingests infrastructure declarations only: message broker definitions, Helm/Kubernetes manifests, Docker Compose files, CI configs, and agentic tooling. Parses no source code and makes zero LLM calls. Accepts directories (scanned for structural files) as well as standalone files (routed directly to the matching structural plugin).

cr analyze infra [paths...] [options]

paths... also accepts an @file argument (e.g. @targets.txt), read as a newline-delimited path list, same shorthand as cr analyze code.

Options:

Examples:

# Ingest all infra declarations found in the repo fleet
cr analyze infra ./repos/*

# Ingest a single broker definitions file directly
cr analyze infra ./infra/rabbitmq-definitions.json

Analyze Traces

Analyzes runtime telemetry (distributed traces) from Datadog or Jaeger exports. Overlays the trace topology on top of the static graph, validating the static architecture against real runtime behavior.

cr analyze traces --file <path> [options]

Options:

Example:

# Analyze a Datadog traces export
cr analyze traces --file ./traces/datadog-export.json

# Analyze a Jaeger export
cr analyze traces --file ./jaeger-traces.json

Analyze Vuln

Scans all package dependencies in the graph for known vulnerabilities (CVEs) by querying the OSV.dev public database. Creates Vulnerability nodes and links them to affected Package nodes with version-aware edges.

Vulnerability enrichment also runs automatically during every cr analyze code run. Use this standalone command to re-scan on demand without re-analyzing the codebase. See Vulnerability Scanning for the full guide: graph model, dashboard surfaces, governance policies, and air-gapped operation.

cr analyze vuln [options]

Options:

Privacy: only public package names and versions are sent to OSV.dev. Source code, file paths, and repository metadata never leave the machine.

Examples:

# Scan all packages in the graph for vulnerabilities
cr analyze vuln

# Force refresh from OSV (bypass 24h cache)
cr analyze vuln --refresh

# Offline mode: use only cached vulnerability data
cr analyze vuln --offline

Graph impact:

Example Cypher query (which services have critical CVEs in production deps):

MATCH (v:Vulnerability)<-[hv:HAS_VULNERABILITY]-(p:Package)<-[dep:DEPENDS_ON]-(s:Service)
WHERE v.severity = 'CRITICAL' AND dep.isDev = false
  AND dep.installedVersion IN hv.vulnerableInstalledVersions
RETURN s.name, p.name, v.osvId, v.cvssScore

Impact Evaluation

Predicts the architectural blast radius of a code change in memory, without modifying the production graph. Returns a structured finding report at three severity levels (DANGER, WARNING, INFO) and emits a semantic exit code so CI / agents can branch without parsing the text output.

cr blast [path] [options]

The repo path is a positional argument and defaults to the current directory, matching the cr analyze convention. Pass an explicit path to evaluate a different workspace.

Exit codes:

Options:

Examples:

# Standard usage (current directory, default base origin/main)
cr blast

# Analyze a sibling repo
cr blast ../orchestrator

# Override base / head refs
cr blast --base main --head feature/redis-auth

# Describe the intent for better LLM context
cr blast -m "Migrate auth module to Redis"

# Output markdown for CI comment injection
cr blast --format markdown > report.md

# Analyze specific files without git
cr blast --files "src/payments/PaymentController.php"

# Advisory mode (never blocks CI)
cr blast --advisory

See Impact Evaluation for full integration instructions for GitHub Actions, GitLab CI, and Bitbucket Pipelines.

Governance Policies

The cr policy command group verifies governance rules against the architecture graph, prunes saved policies from it, and exports built-in packs for local customization.

cr policy verify

Runs governance rules against the architecture graph. With no --rules-path, it runs the built-in packs (including agent-readiness); pass --rules-path to run a custom file or directory. Returns violations at configurable severity levels.

cr policy verify [options]

Options:

Examples:

# Run the built-in packs (no path needed)
cr policy verify

# Re-run only the agent-readiness checks and persist results into the graph
cr policy verify --tag agent-readiness --output graph

# Run rules from a custom directory
cr policy verify --rules-path ./policies/

# Output as SARIF (for IDE integration)
cr policy verify --rules-path ./policies/ --output sarif --out results.sarif

# Fail on warnings too
cr policy verify --fail-on warning

On completion, cr policy verify touches /tmp/health-check; this backs a Kubernetes CronJob readiness probe when the command runs as a scheduled job. Harmless outside that context, but worth knowing if you're inspecting /tmp.

cr policy prune

Removes PolicyRule catalog nodes and their PolicyEvaluation results from the graph. Dry-run by default: pass --force to delete. There is no automatic orphan GC (tags are many-to-one and cannot identify a pack scope), so removing a rule from a pack and reflecting it in the graph is an explicit operation.

Examples:

# Preview which rules a pack would reap (orphans within its tag scope)
cr policy prune --rules-path ./policies/

# Delete specific rules and their validations
cr policy prune ar-tier-declared --force

cr policy export

Copies a built-in policy pack to a local directory so you can customize the rules. On the next cr policy verify run, the local copy takes priority over the built-in pack.

cr policy export <pack-name> [options]

Examples:

# Export the agent-readiness pack for local customization
cr policy export agent-readiness

# Re-export, overwriting local edits
cr policy export agent-readiness --force

Architecture Dashboard

Generates the Architecture Dashboard, a single self-contained HTML file covering AI tooling observability, package dependencies, data gravity, governance alerts, and blast-radius topology.

cr ui [options]

Options:

Example:

# Generate the dashboard and auto-open it
cr ui

# Generate with a timestamped filename
cr ui --out ./reports/health-$(date +%Y-%m-%d).html

# Focus the dashboard exclusively on the blast radius topology
cr ui --focus blast

# Output raw JSON for CI pipelines
cr ui --json

See Architecture Dashboard for a full explanation of the dashboard domains and components.

Docs

Commands for generating and managing architecture documentation. All doc commands are subcommands of cr docs.

Generate Specifications

Generates an architecture document for one or more target services (up to 10), including C4 diagrams and architectural risk analysis. Uses the LLM configured during cr init.

cr docs generate [options]

Options:

Example:

# Interactive service selection
cr docs generate

# Target a specific service
cr docs generate --target payments-service

# Document multiple services in one platform document
cr docs generate --target orders-api,payments-service,shipping-service

# Generate for a specific service, output to a custom path
cr docs generate --target orders-api --output ./docs/architecture/orders.md

# Skip risk analysis (faster)
cr docs generate --target payments-service --skip-risk

The generated document includes:

• C4 Context and Container diagrams (Mermaid format)
• List of inbound consumers and outbound dependencies
• Architectural risk metrics: Blast Radius Score, downstream services impacted, critical data dependencies
• LLM-generated narrative describing the service's purpose, responsibilities, and risk profile

Agentic Chat

Opens an interactive terminal chat session with the CodeRadius Architect Agent, an LLM-powered agent with full access to your architectural graph via MCP tools.

cr ask

You can ask the agent questions like:

• "Which services consume the payments queue?"
• "What would break if I rename the customerId field in the orders table?"
• "Which teams have the highest SPOF exposure in the architecture?"

MCP Server

Commands for managing the Model Context Protocol (MCP) server integration with IDE agents.

Start Server

Starts the CodeRadius MCP server on stdio for IDE agent integration.

cr mcp start

Configure IDE

Interactive wizard that auto-detects installed IDE environments (Cursor, Windsurf, Claude Desktop, Claude Code, Gemini CLI, Antigravity) and injects the MCP server configuration automatically.

cr mcp configure

Note: For full MCP documentation on available tools, security model, IDE configuration examples, and debugging tips, see the dedicated MCP Server page.

Infrastructure Management

Commands for managing the local infrastructure (Memgraph graph database).

Start Database

Starts the Memgraph graph database container using Docker and initializes the database schema.

cr up

What it does:

1. Runs preflight checks (Docker installed, daemon running, workspace initialized, port available)
2. Creates or restarts the Memgraph container on bolt://localhost:7687
3. Initializes the database schema (uniqueness constraints and secondary indexes). Vector indexes are created lazily on the first cr analyze code/cr analyze infra run, once the configured embedding model's dimension is known

Note: Requires Docker to be running. If Memgraph is already running, this command is idempotent.

Stop Database

Stops the Memgraph container. Data is persisted in Docker volumes by default.

cr down [options]

Example:

# Stop, preserving data
cr down

# Stop and wipe all data
cr down --clean

State Management

Export and import architecture graph snapshots. Useful for sharing state between environments, version-controlling your graph, or disaster recovery.

State Export

Dumps the architecture graph to a .cypherl snapshot file (one Cypher statement per line, Git-diffable).

cr state export [options]

Example:

# Export to default file
cr state export

# Export to a specific path
cr state export --out ./backups/graph-$(date +%Y%m%d).cypherl

State Import

Restores the architecture graph from a .cypherl snapshot. By default, the existing graph is wiped before importing.

cr state import <file> [options]

Example:

# Restore from a snapshot (wipes current graph)
cr state import ./state.cypherl

# Additive import (layer on top of existing graph)
cr state import ./second-env.cypherl --no-wipe

# CI mode (no confirmation)
cr state import ./state.cypherl --force

Configuration Validation

Validates the repo's declarative coderadius.yaml without running an analysis: strict schema checking (typos surface as errors) plus a semantic dry-run against the repo (sections that match nothing produce warnings). Offline by design: no graph, no LLM. Exits 0 when the schema is valid (warnings allowed) and 1 when invalid. CI/pre-commit friendly.

cr validate [options]

Examples:

# Validate the current repo
cr validate

# Validate a sibling repo, machine-readable
cr validate --repo ../orders-service --json

Data Pruning

Destructive operations for removing data from the graph or cache. Use with caution: these operations cannot be undone.

Prune Graph

Permanently deletes all nodes, relationships, and indexes from the Memgraph database. Requires explicit confirmation.

cr prune graph [options]

After pruning, run cr analyze code to repopulate the graph.

Prune Cache

Clears all local caches (embeddings, classifiers, OSV, datastore assignments) and downloaded repositories. The next analysis run will re-analyze everything from scratch.

cr prune cache [options]

Prune All

Wipes the graph database AND deletes all local caches in a single operation.

cr prune all [options]

Grounding Review

Read-only commands for inspecting the trust attribution of entities in the graph. See the Grounding & Trust Tiers guide for the conceptual model.

Review Pending

Lists every inferred entity flagged with needsReview = true, grouped by node label. The engine flags entities when it cannot decide between competing signals, when a sanitizer fallback fires on a weak source, or when a mutation runs without a grounding argument (defensive catch).

cr review pending [options]

The command is read-only: it prints the triage list and exits. To act on a flagged entity, either accept the engine's inference (no action), tighten the source code so a static extractor catches it, or declare the entity in coderadius.yaml to override the tier with a declared source.

# All pending entities
cr review pending

# Only flagged MessageChannels
cr review pending --label MessageChannel

# Only LLM-inferred entities with quality medium or above
cr review pending --quality-at-least medium --source llm

# LLM-inferred OR heuristic-inferred (anything not from AST or composite)
cr review pending --source llm --source heuristic

Diagnostic Coverage Dump

The diagnostic script scripts/diag-graph-coverage.ts dumps every inferred entity in the graph with its grounding columns. Useful for sanity-checking an analysis, comparing two ingestion runs, or finding stale entities filtered by source.

bun run scripts/diag-graph-coverage.ts [options]

# Production-trust baseline: only what the AST extractor verified directly
bun run scripts/diag-graph-coverage.ts --source ast

# Trust above the noise floor
bun run scripts/diag-graph-coverage.ts --quality-at-least high

# Find what the LLM inferred for a single repo (so you can sanity-check it)
bun run scripts/diag-graph-coverage.ts --repo my-repo --source llm

Catalog Drift

Compares catalog-declared truth (Backstage, Cortex) against the code-extracted graph: ghost services (in catalog, not in code), orphan services (in code, not in catalog), and grounded dependency drift. Declared references that cannot be grounded to a real node are reported as unverifiable, not as drift.

cr drift [options]

Examples:

# Full drift report
cr drift

# Only Backstage-declared entities, unlimited rows, machine-readable
cr drift --source backstage --limit 0 --json

Configuration

Commands for managing settings, team aliases, and shell completion.

Show Config

Displays the current resolved configuration: the merged result of global settings (~/.coderadius/config/settings.json), local .env file, and environment variables. Shows resolved provider and model per action context (default, ingest, chat, doc, mcp), plus a From column with the provenance of each resolved model (built-in (fast), ai.smart, ai.chat, env, ...).

cr config show [options]

Print CI Environment

Prints the environment variables a CI pipeline needs to reproduce your local LLM configuration, as shell export lines: MODEL_PROVIDER, MODEL_NAME, the provider-specific credentials, and the embedding model when it uses a different provider. Secret values are never printed; they appear as <set-your-key> placeholders.

cr config env

The command takes no options. Pipe the output into your CI secret manager or a .env template and fill in the placeholders.

Team Alias Management

Manages AI-proposed team identity aliases. During analysis, CodeRadius may detect that multiple repository-level organization names refer to the same logical team. These proposals are surfaced as "phantom teams" that can be approved or rejected.

# List all pending team alias proposals
cr config team-alias list
cr config team-alias list --pending  # Only pending

# Approve a phantom team alias
cr config team-alias approve "platform-payments"

# Reject a phantom team alias
cr config team-alias reject "platform-payments-old"

Shell Completion

Manages shell autocompletion for the cr CLI.

# Install autocompletion into your shell profile (.bashrc / .zshrc)
cr config completion --setup

# Remove autocompletion from your shell profile
cr config completion --cleanup

After running --setup, restart your terminal or source your profile file. Tab completion will then work for all cr commands and subcommands.

Environment Variables

CodeRadius reads the following environment variables, either from your shell, a local .env file, or the global ~/.coderadius/config/credentials.json:

Per-action overrides: MODEL_PROVIDER, MODEL_NAME, and EMBEDDING_MODEL each have an _<ACTION> variant that wins over the general one for that action: MODEL_PROVIDER_INGEST, MODEL_NAME_CHAT, EMBEDDING_MODEL_DOC, etc. ACTION is one of INGEST, CHAT, DOC, MCP. Use this to run, say, a cheaper model for bulk ingestion and a stronger one for cr ask.

Concurrency and Rate Limiting

Two independent knobs govern LLM traffic during ingestion: a concurrency limiter (in-flight requests) and a requests-per-minute limiter (provider quota). Both auto-tune by default; you only need these variables to override the auto-tuned bounds or to pin a hard cap.

The rate limiter is disabled under vitest unless an LLM_RATE_* variable is explicitly set, so test suites are unaffected.