CLI Commands

SDL-MCP ships a full-featured CLI that covers initialization, indexing, serving, health checks, CI integration, and direct tool access. All commands share a common set of global options and follow the same config lookup order.

Architecture

  Command Line
      │
      ▼
  ┌───────────────────────────────────────────────┐
  │  CLI Parser (Node.js parseArgs)                │
  │  Global options: --config, --log-level, --help │
  └───────────┬───────────────────────────────────┘
              │
  ┌───────────▼───────────────────────────────────┐
  │  Command Router                                │
  ├─────────────────┬─────────────────────────────┤
  │ init   doctor   │ index  serve   tool          │
  │ info   version  │ export import  pull          │
  │ health summary  │ benchmark:ci                 │
  └─────────────────┴──────────┬──────────────────┘
                               │ (tool command)
                               ▼
  ┌────────────────────────────────────────────────┐
  │  Tool Dispatch (same as MCP server)             │
  │  Zod validation → Handler → Formatted output   │
  │  Formats: json | json-compact | pretty | table  │
  └────────────────────────────────────────────────┘

Run Without Installing

If you prefer not to install SDL-MCP globally, prefix every command with npx --yes sdl-mcp@latest.

npx --yes sdl-mcp@latest version
npx --yes sdl-mcp@latest doctor
npx --yes sdl-mcp@latest info

Global Options

These options apply to every command.

Flag	Description	Default
`-c, --config <PATH>`	Explicit config file path	Auto-resolved
`--log-level <level>`	`debug`, `info`, `warn`, or `error`	`info`
`--log-format <format>`	`json` or `pretty`	`pretty`
`-h, --help`	Show help	—
`-v, --version`	Print version	—

Config lookup order (when --config is omitted):

SDL_CONFIG environment variable (or SDL_CONFIG_PATH)
Local config in the current working directory (./config/sdlmcp.config.json)
Global config path (default user-level location; overridable via SDL_CONFIG_HOME)
Package-local fallback (<sdl-mcp package root>/config/sdlmcp.config.json)

Commands

sdl-mcp init — Bootstrap config and optionally auto-index

Initialize configuration, detect your repo and languages, and optionally generate client-specific MCP config files and agent enforcement assets.Syntax

sdl-mcp init [options]

Options

Flag	Type	Description	Default
`--client <name>`	string	Target MCP client: `claude-code`, `codex`, `gemini`, `opencode`	—
`--repo-path <PATH>`	string	Path to repository root	Current directory
`--languages <list>`	string	Comma-separated language codes: `ts`, `tsx`, `js`, `jsx`, `py`, `go`, `java`, `cs`, `c`, `cpp`, `php`, `rs`, `kt`, `sh`	Auto-detected
`-f, --force`	boolean	Overwrite existing config	`false`
`-y, --yes`	boolean	Non-interactive mode with repo/language auto-detection	`false`
`--auto-index`	boolean	Run inline incremental index and doctor checks after init	`false` (enabled when `-y` is set)
`--dry-run`	boolean	Print generated config without writing files	`false`
`--enforce-agent-tools`	boolean	Generate SDL-first enforcement assets for the chosen client (hooks, instructions, plugin)	`false`

Supported language codests, tsx, js, jsx (TypeScript/JavaScript) · py (Python) · go (Go) · java (Java) · cs (C#) · c, cpp (C/C++) · php (PHP) · rs (Rust) · kt (Kotlin) · sh (Shell)Examples

# Interactive init with client config generation
sdl-mcp init --client codex --repo-path . --languages ts,py,go

# Fully automated: auto-detect, index, and run health checks
sdl-mcp init -y --auto-index

# Preview generated config without writing any files
sdl-mcp init -y --dry-run

# Generate enforcement hooks and agent instructions for Claude Code
sdl-mcp init --client claude-code --enforce-agent-tools

What gets createdA successful init writes:

config/sdlmcp.config.json — main SDL-MCP configuration
<client>-mcp-config.json — client-specific MCP server registration (when --client is set)
AGENTS.md / CLAUDE.md / CODEX.md etc. — agent instruction files (when --enforce-agent-tools)
.claude/hooks/, .claude/settings.json, .opencode/plugins/ — runtime enforcement assets (client-specific)

Next steps after init without --auto-index

Run doctor

Validate your environment: sdl-mcp doctor

Index your repo

Build the symbol graph: sdl-mcp index

Start the server

Connect your agent: sdl-mcp serve --stdio

sdl-mcp doctor — Validate runtime and environment

Runs a suite of checks across Node.js version, config readability, graph database, tree-sitter grammars, repo path accessibility, live index runtime, semantic models, and sandboxed runtime execution.Syntax

sdl-mcp doctor [options]

Check suite

Check	What it validates
Node.js version	Node.js >= required minimum version
Config file exists	Config file is present at resolved path
Config file readable	Config file can be read by the current user
Tree-sitter grammars	All grammar binaries load without error
Repo paths accessible	Every configured `rootPath` exists on disk
Stale index detection	All repos indexed within the last 24 hours
Watcher health telemetry	Active file watchers are not stale or errored
Live index runtime	Live indexing coordinator is healthy
Call resolution capabilities	Pass-2 resolvers and call-edge metadata
Graph database (Ladybug)	DB opens, symbols and edges are queryable
DB extension capabilities	`fts` and `vector` extensions loaded
Semantic embedding models	`onnxruntime-node`, `tokenizers`, and model files
Runtime execution	Allowed runtimes are detectable on the system

Each check reports ✓ pass, ⚠ warn, or ✗ fail. The command exits non-zero if any check fails.Examples

# Run all checks
sdl-mcp doctor

# Run with explicit config path
sdl-mcp doctor --config ./config/sdlmcp.config.json

# Increase log verbosity
sdl-mcp doctor --log-level debug

Sample output

Running SDL-MCP environment checks...

✓ Node.js version: Node.js v24.0.0 (>= 20.0.0)
✓ Config file exists: /home/user/.sdl-mcp/config/sdlmcp.config.json
✓ Config file readable: /home/user/.sdl-mcp/config/sdlmcp.config.json
✓ Tree-sitter grammars available: All 7 grammars loaded (TypeScript, C, C++, PHP, Rust, Kotlin, Bash)
✓ Repo paths accessible: All 1 repo(s) accessible
⚠ Stale index detection: Stale indexes: my-repo (26h ago). Run: sdl-mcp index --mode full
✓ Graph database (Ladybug): Ladybug OK (symbols: 1847, edges: 3214, schema: v5/5)

⚠ 1 warning(s). SDL-MCP may work but with limitations.

sdl-mcp index — Index repositories into the symbol graph

Index one or all configured repositories into the LadybugDB symbol graph. Supports incremental and full modes. If an HTTP server is already running on the same database, indexing is automatically delegated to the live server via SSE.Syntax

sdl-mcp index [options]

Options

Flag	Type	Description	Default
`--repo-id <ID>`	string	Index only this repository	All configured repos
`-w, --watch`	boolean	Stay running and watch for file changes	`false`
`-f, --force`	boolean	Force full re-index (instead of incremental)	`false`

Examples

# Index all configured repositories (incremental)
sdl-mcp index

# Index a specific repo
sdl-mcp index --repo-id my-repo

# Full re-index
sdl-mcp index --repo-id my-repo --force

# Index and watch for changes
sdl-mcp index --watch

Sample output

Indexing 1 repo(s)...

Indexing my-repo (/path/to/my-repo) [mode=incremental]...
  pass1: 142/142 src/server.ts
  pass2: 142/142 src/server.ts
  Files: 142
  Symbols: 312 new (1847 total)
  Edges: 89 new (3214 total)
  Duration: 4821ms

✓ Indexing complete

When an HTTP server (sdl-mcp serve --http) is already running on the same database, sdl-mcp index automatically delegates to it. The --watch flag is ignored in delegation mode — the server manages its own file watchers.

sdl-mcp serve — Start the MCP server

Start the SDL-MCP server using either stdio transport (for MCP clients) or HTTP transport (for development, network access, and the Graph UI).Syntax

sdl-mcp serve [options]

Options

Flag	Type	Description	Default
`--stdio`	boolean	Use stdio transport	—
`--http`	boolean	Use HTTP transport	—
`--host <HOST>`	string	HTTP bind address	`localhost`
`--port <NUMBER>`	number	HTTP port	`3000`
`--no-watch`	boolean	Disable file watchers even when enabled in config	`false`

Examples

# Start for an MCP client (stdio)
sdl-mcp serve --stdio

# Start HTTP server for development
sdl-mcp serve --http --host localhost --port 3000

# HTTP server on a custom port, no file watchers
sdl-mcp serve --http --port 8080 --no-watch

HTTP transport surfacesWhen running with --http, additional REST endpoints and a Graph UI are available:

Surface	Path
Graph UI	`http://<host>:<port>/ui/graph`
Symbol neighborhood	`/api/graph/:repoId/symbol/:symbolId/neighborhood`
Blast radius	`/api/graph/:repoId/blast-radius/:fromVersion/:toVersion`
Graph slice	`/api/graph/:repoId/slice/:handle`
Symbol search	`/api/symbol/:repoId/search`
Symbol card	`/api/symbol/:repoId/card/:symbolId`
Repo status	`/api/repo/:repoId/status`
Trigger re-index	`/api/repo/:repoId/reindex`

For MCP client integration, always use --stdio. Use --http during development to access the Graph UI and REST API.

sdl-mcp tool — Access all MCP tool actions directly

Invoke any of the 31 gateway-routable SDL-MCP tool actions directly from the CLI — no MCP server, transport, or SDK required. Dispatches through the same gateway router and Zod schemas as the MCP server.Syntax

sdl-mcp tool <action> [flags]
sdl-mcp tool --list
sdl-mcp tool <action> --help

Examples

# Get repo status
sdl-mcp tool repo.status --repo-id my-repo

# Search for symbols
sdl-mcp tool symbol.search --repo-id my-repo --query "handleRequest"

# Build a task-scoped graph slice
sdl-mcp tool slice.build --repo-id my-repo --entry-symbols sym123

# List all available actions
sdl-mcp tool --list

See the CLI Tool Access reference for full documentation of all 31 actions, output formats, argument types, stdin piping, and scripting patterns.

sdl-mcp info — Runtime diagnostics

Show a unified diagnostic report covering the SDL-MCP version, Node.js runtime, config resolution, log file, Ladybug graph database, and native addon status.Syntax

sdl-mcp info [options]

Options

Flag	Type	Description
`--json`	boolean	Output report as JSON

Report sections

Version — SDL-MCP package version
Runtime — Node.js version, platform, architecture
Config — Resolved config path, whether it exists and loaded successfully
Logging — Active log file path, whether console mirroring is enabled, whether temp-file fallback is in use
Ladybug — Graph database availability and active DB path
Native addon — Rust indexer availability, source path, and fallback reason
Warnings / Misconfigurations — Any detected issues

Examples

# Human-readable diagnostics
sdl-mcp info

# Machine-readable JSON output
sdl-mcp info --json

# Use a specific config
sdl-mcp info --config ./config/sdlmcp.config.json

Sample output

SDL-MCP version: 1.4.2

Runtime:
  Node.js: v24.0.0
  Platform: linux
  Arch: x64

Config:
  Path: /home/user/.sdl-mcp/config/sdlmcp.config.json
  Exists: yes
  Loaded: yes

Logging:
  File: /home/user/.sdl-mcp/logs/sdlmcp.log
  Console mirroring: disabled
  Fallback path: no

Ladybug:
  Available: yes
  Active path: /home/user/.sdl-mcp/db/sdlmcp.ladybug

Native addon:
  Available: yes
  Source path: /usr/local/lib/node_modules/sdl-mcp/native/index.node
  Reason: loaded

sdl-mcp summary — Generate context summaries

Generate copy-paste context summaries from indexed repository data. Useful for producing portable briefings to share with agents or teammates outside the MCP environment.Syntax

sdl-mcp summary <query> [options]

Options

Flag	Type	Description	Default
`--budget <NUMBER>`	number	Token budget for the summary	`2000`
`--short`	boolean	Shorthand for a small token budget	—
`--medium`	boolean	Shorthand for a medium token budget	—
`--long`	boolean	Shorthand for a large token budget	—
`--format <format>`	string	`markdown`, `json`, or `clipboard`	`markdown`
`--scope <scope>`	string	`symbol`, `file`, or `task` (auto-detected from query if omitted)	Auto
`--repo <ID>`	string	Repository ID	Auto-resolved from cwd
`-o, --output <PATH>`	string	Write output to file instead of stdout	—

Examples

# Short summary of the auth flow
sdl-mcp summary "auth flow" --short

# Detailed JSON summary with a custom token budget
sdl-mcp summary "database layer" --budget 4000 --format json

# Write a markdown summary to a file
sdl-mcp summary "error handling" --format markdown --output context.md

# Summary scoped to a specific repo
sdl-mcp summary "API routes" --repo my-repo --format clipboard

sdl-mcp health — Composite repository health score

Compute and display a composite health score for a repository. Outputs human-readable text by default, or machine-readable JSON or Shields.io badge JSON.Syntax

sdl-mcp health [options]

Options

Flag	Type	Description
`--repo-id <ID>`	string	Repository to evaluate (defaults to first configured repo)
`--json`	boolean	Output full health snapshot as JSON
`--badge`	boolean	Output Shields.io-compatible badge JSON

Health components

Component	Description
Freshness	How recently the repo was indexed
Coverage	Ratio of indexed symbols to total detected symbols
Error Rate	Proportion of files that failed during indexing
Edge Quality	Quality of dependency edges in the graph

Examples

# Human-readable health report
sdl-mcp health

# Machine-readable JSON snapshot
sdl-mcp health --json

# Shields.io badge JSON (for CI status badges)
sdl-mcp health --badge

Sample output

Health Score: 92 (my-repo)
  Freshness: 98.2%
  Coverage: 94.1%
  Error Rate: 0.7%
  Edge Quality: 91.4%

Badge JSON output (--badge)

{
  "schemaVersion": 5,
  "label": "sdl-mcp health",
  "message": "92",
  "color": "brightgreen"
}

sdl-mcp benchmark:ci — CI regression benchmarks

Run benchmark guardrails in CI. Measures indexing performance, graph quality, token efficiency, and edge accuracy, then compares against a stored baseline to detect regressions.Syntax

sdl-mcp benchmark:ci [options]

Options

Flag	Type	Description	Default
`--repo-id <ID>`	string	Repository to benchmark	First configured repo
`--baseline-path <PATH>`	string	Path to baseline JSON file	`.benchmark/baseline.json`
`--threshold-path <PATH>`	string	Path to threshold config	`config/benchmark.config.json`
`--out <PATH>`	string	Output path for results JSON	`.benchmark/latest.json`
`--json`	boolean	Also print full results JSON to stdout	`false`
`--update-baseline`	boolean	Update the baseline file with current results	`false`
`--skip-indexing`	boolean	Skip the indexing step (use existing indexed data)	`false`

Metrics collected

Category	Metrics
Indexing	Time per file, time per symbol
Quality	Symbols per file, edges per symbol, graph connectivity, exported symbol ratio
Performance	Slice build time, skeleton generation time
Token efficiency	Average card tokens, average skeleton tokens
Coverage	Call edge count, import edge count
Phase A	Summary generation time, summary tokens, health score, watcher events
Phase B (Edge Accuracy)	Per-language precision, recall, F1 score, strategy accuracy

Examples

# Run benchmarks and compare against existing baseline
sdl-mcp benchmark:ci --repo-id my-repo

# Update the baseline after a deliberate performance change
sdl-mcp benchmark:ci --repo-id my-repo --update-baseline

# Skip indexing when CI already indexed
sdl-mcp benchmark:ci --skip-indexing --json

Notes

Edge-accuracy regression checks compare against scripts/benchmark/edge-accuracy-baseline.json
Benchmark repo scope can be pinned via scripts/benchmark/phase-a-benchmark-lock.json
Exits with code 1 if any threshold or edge-accuracy gate fails

sdl-mcp export — Export a sync artifact

Export a repository snapshot as a sync artifact (.sdl-artifact.json). Artifacts contain full repository state and can be imported into another environment.Syntax

sdl-mcp export [options]

Options

Flag	Type	Description	Default
`--repo-id <ID>`	string	Repository to export	First configured repo
`--version-id <ID>`	string	Specific version to export	Latest
`--commit-sha <SHA>`	string	Export the version matching this commit SHA	—
`--branch <NAME>`	string	Export the version for this branch	—
`-o, --output <PATH>`	string	Output directory	`.sdl-sync/`
`--list`	boolean	List existing artifacts instead of exporting	`false`

Examples

# Export latest version of a repo
sdl-mcp export --repo-id my-repo --output .sdl-sync

# Export a specific commit
sdl-mcp export --repo-id my-repo --commit-sha a1b2c3d

# List existing artifacts
sdl-mcp export --list

Sample output

Exporting sync artifact for repository: my-repo

✓ Export successful
  Artifact ID: artifact-my-repo-v23-a1b2c3d
  Artifact path: .sdl-sync/my-repo.sdl-artifact.json
  Version ID: v23
  Commit SHA: a1b2c3d
  Files: 142
  Symbols: 1847
  Edges: 3214
  Size: 824.50 KB
  Duration: 1203ms

sdl-mcp import — Import a sync artifact

Restore repository state from a previously exported sync artifact. Optionally verifies artifact integrity before importing.Syntax

sdl-mcp import [options]

Options

Flag	Type	Description	Default
`--artifact-path <PATH>`	string	Path to the `.sdl-artifact.json` file (required)	—
`--repo-id <ID>`	string	Target repository ID	First configured repo
`-f, --force`	boolean	Overwrite existing data	`false`
`--verify`	boolean	Verify artifact integrity before import	`true`

Examples

# Import an artifact
sdl-mcp import --artifact-path .sdl-sync/my-repo.sdl-artifact.json --repo-id my-repo

# Force-overwrite and skip verification
sdl-mcp import --artifact-path .sdl-sync/my-repo.sdl-artifact.json --force --no-verify

Sample output

Importing sync artifact from: .sdl-sync/my-repo.sdl-artifact.json

✓ Import successful
  Repository ID: my-repo
  Version ID: v23
  Files restored: 142
  Symbols restored: 1847
  Edges restored: 3214
  Verified: Yes
  Duration: 987ms

sdl-mcp pull — Pull by version or commit with fallback

Pull the best available artifact for a repository, selecting by version ID or commit SHA. Falls back to a full re-index if no matching artifact is found.Syntax

sdl-mcp pull [options]

Options

Flag	Type	Description	Default
`--repo-id <ID>`	string	Repository to pull	First configured repo
`--version-id <ID>`	string	Target version ID	Latest
`--commit-sha <SHA>`	string	Pull the version matching this commit SHA	—
`--fallback`	boolean	Fall back to full re-index if no artifact found	`true`
`--retries <NUMBER>`	number	Number of retry attempts	`3`

Examples

# Pull latest with automatic fallback
sdl-mcp pull --repo-id my-repo

# Pull by commit SHA (typical CI usage)
sdl-mcp pull --repo-id my-repo --commit-sha a1b2c3d --fallback --retries 3

# Pull without fallback (fail if no exact match)
sdl-mcp pull --repo-id my-repo --commit-sha a1b2c3d --no-fallback

Sample output

Pulling latest state for repository: my-repo

✓ Pull successful
  Version ID: v23
  Artifact ID: artifact-my-repo-v23-a1b2c3d
  Method: artifact-import
  Retries: 0
  Duration: 1105ms

sdl-mcp version — Show version and environment

Print the SDL-MCP package version and basic environment information.Syntax

sdl-mcp version

Sample output

SDL-MCP version: 1.4.2

Environment:
  Node.js: v24.0.0
  Platform: linux
  Arch: x64

For more detailed diagnostics including config paths, database status, and native addon info, use sdl-mcp info instead.

Typical Workflows

Local Setup
CI Data Sync
One-liner (npx)

# 1. Initialize config (auto-detect repo and languages)
sdl-mcp init --client codex

# 2. Check your environment
sdl-mcp info
sdl-mcp doctor

# 3. Index your repository
sdl-mcp index

# 4. Start the MCP server
sdl-mcp serve --stdio

# Export a versioned snapshot from CI
sdl-mcp export --repo-id my-repo --commit-sha $GIT_SHA

# Pull it in another environment
sdl-mcp pull --repo-id my-repo --commit-sha $GIT_SHA --fallback

# Run regression benchmarks
sdl-mcp benchmark:ci --repo-id my-repo

# Full setup without a global install
npx --yes sdl-mcp@latest init -y --auto-index
npx --yes sdl-mcp@latest serve --stdio

CLI

MCP Tools

Configuration

Architecture

Run Without Installing

Global Options

Commands

Typical Workflows

Build docs developers (and LLMs) love

CLI

MCP Tools

Configuration

​Architecture

​Run Without Installing

​Global Options

​Commands

​Typical Workflows

Build docs developers (and LLMs) love

Architecture

Run Without Installing

Global Options

Commands

Typical Workflows