CLI Tool Access

sdl-mcp tool gives you full access to SDL-MCP’s tool capabilities from your terminal, shell scripts, and CI pipelines — without running a server or installing an MCP SDK.

The CLI tool dispatcher routes through the same gateway router and Zod validation schemas as the MCP server. CLI and MCP always execute identical code paths.

Quick Start

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

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

# Get a symbol card
sdl-mcp tool symbol.getCard --repo-id my-repo --symbol-id "file:src/server.ts::MCPServer"

# Build a task-scoped graph slice
sdl-mcp tool slice.build --repo-id my-repo --task-text "debug auth flow" --max-cards 50

# Get per-action help
sdl-mcp tool symbol.search --help

How It Works

The CLI tool dispatcher bypasses the MCP server and transport layer entirely:

  sdl-mcp tool symbol.search --query "auth"
       │
       ▼
  ┌─────────────────────┐
  │ CLI Arg Parser       │  --query → { query: "auth" }
  │ (type coercion)      │  --limit → number, --tags → string[]
  └──────────┬──────────┘
             │
             ▼
  ┌─────────────────────┐
  │ Config + DB Init     │  Same config loading as MCP server
  │ + repoId resolution  │  Auto-resolves repoId from cwd
  └──────────┬──────────┘
             │
             ▼
  ┌─────────────────────┐
  │ Gateway Router       │  Same handler functions
  │ + Zod Validation     │  Same schemas
  └──────────┬──────────┘
             │
             ▼
  ┌─────────────────────┐
  │ Output Formatter     │  json | json-compact | pretty | table
  └─────────────────────┘

Parses CLI flags into typed arguments using action definitions
Loads config and initializes the graph DB (same as the MCP server)
Routes directly to the same handler functions the MCP server uses
Normalizes and validates with the same alias-mapping and Zod schemas
Formats output in your choice of format

Basic Syntax

sdl-mcp tool <action> [flags]

The <action> follows a namespace.operation pattern, for example symbol.search or slice.build. Run sdl-mcp tool --list to see all 31 available actions.

All 31 Actions

Query — Read-only intelligence queries (9 actions)

Action	Description
`symbol.search`	Search for symbols by name or summary
`symbol.getCard`	Get a single symbol card by ID
`symbol.getCards`	Batch fetch symbol cards for multiple IDs
`slice.build`	Build a graph slice for a task context
`slice.refresh`	Refresh an existing slice handle (delta only)
`slice.spillover.get`	Fetch overflow symbols with pagination
`delta.get`	Get semantic delta pack between two versions
`context.summary`	Generate token-bounded context summary
`pr.risk.analyze`	Analyze PR risk with blast radius

Code — Gated raw code access (3 actions)

Action	Description
`code.needWindow`	Request policy-gated raw code window
`code.getSkeleton`	Get skeleton view (signatures + control flow, bodies elided)
`code.getHotPath`	Get lines matching specific identifiers with surrounding context

Repo — Repository lifecycle (7 actions)

Action	Description
`repo.register`	Register a repository for indexing
`repo.status`	Get repository status information
`repo.overview`	Get codebase overview with directory summaries
`index.refresh`	Trigger full or incremental re-indexing
`policy.get`	Read current gating policy
`policy.set`	Update policy configuration
`usage.stats`	Get token usage statistics for session or history

Agent — Agentic and live-edit operations (12 actions)

Action	Description
`agent.orchestrate`	Autonomous task execution with budget control
`agent.feedback`	Record which symbols were useful or missing
`agent.feedback.query`	Query aggregated feedback statistics
`buffer.push`	Push editor buffer updates (requires running server)
`buffer.checkpoint`	Force checkpoint (requires running server)
`buffer.status`	Get buffer status (requires running server)
`memory.store`	Store a development memory
`memory.query`	Query development memories
`memory.remove`	Remove a development memory
`memory.surface`	Auto-surface relevant memories
`runtime.execute`	Execute command in sandboxed subprocess
`runtime.queryOutput`	Search stored runtime output artifacts by keyword

buffer.push, buffer.checkpoint, and buffer.status require an active MCP server with live indexing enabled. In CLI mode they will return errors or empty results.

Output Formats

Control output with --output-format:

Format	Flag value	Best for
Indented JSON	`json` (default)	Human-readable, machine-parseable
Compact JSON	`json-compact`	Piping to `jq` or other tools
Pretty	`pretty`	Interactive terminal sessions
Table	`table`	List-like results

# Indented JSON — human-readable and machine-parseable
sdl-mcp tool repo.status --repo-id my-repo

Pretty Format Examples

Symbol search (--output-format pretty)

Found 3 symbol(s):

  NAME              KIND       FILE
  ─────────────────  ─────────  ──────────────
  handleAuth        function   src/auth.ts
  AuthService       class      src/auth.ts
  AuthMiddleware    class      src/middleware.ts

Repo status (--output-format pretty)

Repository: my-repo
  Root Path:       /path/to/repo
  Files Indexed:   142
  Symbols Indexed: 1,847
  Latest Version:  v23
  Last Indexed:    2026-03-14T19:00:00Z
  Health Score:    92

Slice build (--output-format pretty)

Slice built:
  Cards: 12
  Edges: 18
  Handle: slice-abc123

Argument Types

The CLI automatically coerces flag values to the expected types:

Type	CLI Syntax	Example
`string`	`--flag value`	`--repo-id my-repo`
`number`	`--flag 42`	`--limit 20`
`boolean`	`--flag`	`--semantic`
`string[]`	`--flag a,b,c`	`--entry-symbols "sym1,sym2"`
`json`	`--flag '{"key":"val"}'`	`--policy-patch '{"maxWindowLines":200}'`

The parser also accepts the same common aliases that MCP requests use, so CLI flags such as --repo-id, --root-path, --symbol-id, --symbol-ids, --from-version, --to-version, and --slice-handle all normalize to the canonical action fields before validation.

Budget Flags

Actions that accept a budget object use flat flags for convenience. SDL-MCP merges them automatically:

# These flat flags:
sdl-mcp tool slice.build --repo-id my-repo --task-text "debug" \
  --max-cards 50 --max-tokens 10000

# Are merged into:
# { budget: { maxCards: 50, maxEstimatedTokens: 10000 } }

Stdin JSON Piping

Pipe JSON arguments via stdin. CLI flags always override piped values when both are present.

# Pipe full args from stdin
echo '{"repoId":"my-repo","query":"auth","limit":5}' | sdl-mcp tool symbol.search

# Mix stdin + CLI flags — CLI wins on overlap
# Result: query="auth", limit=5 (CLI), repoId="my-repo" (stdin)
echo '{"repoId":"my-repo","limit":100}' | sdl-mcp tool symbol.search --query "auth" --limit 5

# Chain commands using json-compact output
sdl-mcp tool symbol.search --repo-id my-repo --query "auth" --output-format json-compact \
  | jq '.results[0].symbolId' \
  | xargs -I{} sdl-mcp tool symbol.getCard --repo-id my-repo --symbol-id {}

Auto-Resolution

Automatic repoId

You don’t always need to specify --repo-id. The CLI resolves it automatically:

CLI flags or stdin — explicit --repo-id always wins
Current directory match — if your cwd is inside a configured repo’s root path
Single-repo fallback — if only one repo is configured, it’s used automatically

# Inside /path/to/my-repo (which is configured as "my-repo"):
sdl-mcp tool symbol.search --query "auth"
# repoId auto-resolved to "my-repo"

Typo Suggestions

Mistyped action names produce actionable error messages:

$ sdl-mcp tool symbol.sear
Error: unknown action "symbol.sear". Did you mean: symbol.search?. Run: sdl-mcp tool --list

Examples by Workflow

Debugging
PR Review
CI/CD Integration
Scripting

# 1. Find the relevant symbol
sdl-mcp tool symbol.search --query "validateToken" --output-format pretty

# 2. Get its card (signature, dependencies, summary)
sdl-mcp tool symbol.getCard --symbol-id "file:src/auth/jwt.ts::validateToken"

# 3. Build a task-scoped slice
sdl-mcp tool slice.build --task-text "debug token validation failure" --max-cards 20

# 4. Get the skeleton of the file
sdl-mcp tool code.getSkeleton --file src/auth/jwt.ts --output-format pretty

# 5. Narrow to the hot path with specific identifiers
sdl-mcp tool code.getHotPath --symbol-id "file:src/auth/jwt.ts::validateToken" \
  --identifiers "verifySignature,checkExpiry"

# Analyze PR risk between versions
sdl-mcp tool pr.risk.analyze --from-version v22 --to-version v23

# Get the semantic delta
sdl-mcp tool delta.get --from-version v22 --to-version v23

# Generate a context summary for the reviewer
sdl-mcp tool context.summary --query "changes in v23" --format markdown

# Register and index in CI
sdl-mcp tool repo.register --repo-id ci-build --root-path .
sdl-mcp tool index.refresh --repo-id ci-build --mode full

# Run PR risk analysis — fail pipeline on high risk
RISK=$(sdl-mcp tool pr.risk.analyze \
  --from-version $BASE_SHA --to-version $HEAD_SHA \
  --output-format json-compact | jq '.overallRisk')
if [ "$RISK" -gt 75 ]; then
  echo "High risk PR detected: $RISK"
  exit 1
fi

# Export all symbols to a file
sdl-mcp tool symbol.search --query "" --limit 1000 \
  --output-format json-compact > symbols.json

# Batch fetch cards for specific symbols
sdl-mcp tool symbol.getCards \
  --symbol-ids "sym1,sym2,sym3" \
  --output-format json > cards.json

# Run a sandboxed command (minimal output mode)
sdl-mcp tool runtime.execute \
  --runtime shell --code "npm test" \
  --timeout-ms 30000 --output-mode minimal

# Search stored output from a previous execution
sdl-mcp tool runtime.queryOutput \
  --artifact-handle "runtime-my-repo-1234567890-abc123" \
  --query-terms "FAIL,Error" \
  --max-excerpts 5

Configuration

No additional configuration is needed beyond the standard SDL-MCP config file. The tool command uses the same config resolution as all other commands:

# Default config resolution
sdl-mcp tool symbol.search --query "auth"

# Override config path
sdl-mcp tool --config /path/to/sdl-mcp.json symbol.search --query "auth"

Config lookup order: --config flag → SDL_CONFIG env → cwd local config → user-global config → package fallback.

Architecture

The CLI tool access feature is composed of four modules:

Module	File	Responsibility
Action Definitions	`src/cli/commands/tool-actions.ts`	31 action definitions with arg specs, types, and examples
Arg Parser	`src/cli/commands/tool-arg-parser.ts`	Flag→field mapping, type coercion, budget merging, required validation
Dispatcher	`src/cli/commands/tool-dispatch.ts`	Config/DB init, repoId resolution, handler routing, error handling
Output Formatter	`src/cli/commands/tool-output.ts`	JSON, compact JSON, pretty, and table output with action-specific formatting

The dispatcher reuses the gateway router (src/gateway/router.ts), which maps action names to the same { schema, handler } pairs used by the MCP server. This ensures CLI and MCP always execute identical code paths.

Limitations

buffer.* actions require an active MCP server with live indexing. In CLI mode they will return errors or empty results.
No streaming — results are returned after full execution (no partial updates).
Single invocation overhead — each sdl-mcp tool call initializes config and the graph database. For high-frequency scripting, use the MCP server via HTTP transport instead.

CLI

MCP Tools

Configuration

CLI Tool Access

Quick Start

How It Works

Basic Syntax

All 31 Actions

Output Formats

Pretty Format Examples

Argument Types

Budget Flags

Stdin JSON Piping

Auto-Resolution

Automatic repoId

Typo Suggestions

Examples by Workflow

Configuration

Architecture

Limitations

Build docs developers (and LLMs) love

CLI

MCP Tools

Configuration

​Quick Start

​How It Works

​Basic Syntax

​All 31 Actions

​Output Formats

​Pretty Format Examples

​Argument Types

​Budget Flags

​Stdin JSON Piping

​Auto-Resolution

​Automatic repoId

​Typo Suggestions

​Examples by Workflow

​Configuration

​Architecture

​Limitations

Build docs developers (and LLMs) love

Quick Start

How It Works

Basic Syntax

All 31 Actions

Output Formats

Pretty Format Examples

Argument Types

Budget Flags

Stdin JSON Piping

Auto-Resolution

Automatic repoId

Typo Suggestions

Examples by Workflow

Configuration

Architecture

Limitations