node-devtools-cli

Node DevTools CLI

Command-line interface for non-blocking debugging of Node.js backend processes. Connects via the Inspector Protocol (Chrome DevTools Protocol) and provides tracepoints, logpoints, exceptionpoints, and watch expressions without pausing execution.

Installation

Same package as browser-devtools-mcp:

npm install -g browser-devtools-mcp

Quick Start

# 1. Start daemon (if not running)
node-devtools-cli daemon start

# 2. Connect to a Node.js process (by PID)
node-devtools-cli --session-id my-debug debug connect --pid 12345

# 3. Set a tracepoint on server.js line 42
node-devtools-cli --session-id my-debug debug put-tracepoint \
  --url-pattern "server.js" \
  --line-number 42

# 4. Trigger the code path (e.g., make API request to your app)
# 5. Get captured snapshots
node-devtools-cli --session-id my-debug --json debug get-probe-snapshots

Global Options

Option	Description	Default
--port <number>	Daemon server port	2020
--session-id <string>	Session for Node connection persistence	auto
--json	Output as JSON (recommended for AI)	false
--quiet	Suppress log messages	false
--verbose	Enable debug output	false
--timeout <ms>	Operation timeout	30000

AI Agent Recommended:

node-devtools-cli --json --quiet --session-id "debug-session" <command>

Tool Domains

Domain	Description	Reference
debug	Connection, tracepoints, logpoints, exceptionpoints, watch, snapshots

Connection Methods

Connect via debug connect with one of:

Method	Option	Example
PID	--pid <number>	--pid 12345
Process name	--process-name <pattern>	--process-name "server.js"
Docker container	--container-id or --container-name	--container-name my-api
Inspector port	--inspector-port <number>	--inspector-port 9229
WebSocket URL	--ws-url <url>	--ws-url "ws://127.0.0.1:9229/abc"

If the process doesn't have --inspect active, the CLI activates it via SIGUSR1 (no code changes). For Docker: expose port 9229 and use --inspect=0.0.0.0:9229.

CLI Management Commands

Daemon

node-devtools-cli daemon status
node-devtools-cli daemon start
node-devtools-cli daemon stop
node-devtools-cli daemon restart
node-devtools-cli daemon info

Session

node-devtools-cli session list
node-devtools-cli session info <session-id>
node-devtools-cli session delete <session-id>

Tools

node-devtools-cli tools list
node-devtools-cli tools search <query>
node-devtools-cli tools info <tool-name>

Config & Updates

node-devtools-cli config
node-devtools-cli update --check

Examples

Connect by PID

SESSION="--session-id api-debug"

# Connect
node-devtools-cli $SESSION debug connect --pid $(pgrep -f "node server.js")

# Set tracepoint on route handler
node-devtools-cli $SESSION debug put-tracepoint \
  --url-pattern "routes/api.ts" \
  --line-number 25

# Trigger: curl http://localhost:3000/api/users
# Get snapshots
node-devtools-cli $SESSION --json debug get-probe-snapshots

Connect by Process Name

node-devtools-cli debug connect --process-name "api"

Docker Container

# App runs in container with -p 9229:9229
node-devtools-cli debug connect \
  --container-name my-node-app \
  --host host.docker.internal \
  --inspector-port 9229

Exception Catching

SESSION="--session-id exc-debug"

node-devtools-cli $SESSION debug connect --pid 12345
node-devtools-cli $SESSION debug put-exceptionpoint --state uncaught

# Trigger error in app
# Check snapshots
node-devtools-cli $SESSION --json debug get-probe-snapshots --types exceptionpoint

Interactive Mode

node-devtools-cli interactive

Command	Description
help	Show commands
exit, quit	Exit
debug connect	Connect to process
debug status	Connection status
<domain> <tool>	Execute tool

Shell Completions

eval "$(node-devtools-cli completion bash)"
eval "$(node-devtools-cli completion zsh)"