cpp-debugger-cli

cpp-debugger-cli is an agent-friendly JSON client for Debug Adapter Protocol (DAP) sessions. Each CLI invocation handles one JSON request while a detached per-session daemon keeps the debug adapter and target state alive.

Version 0.1 officially targets lldb-dap. The transport and public operations are adapter-neutral, with adapterConfig and rawRequest available for adapter-specific capabilities.

Requirements

• Node.js 22 or newer
• lldb-dap on PATH, or params.adapterPath
• A C/C++ executable built with debug information

Some Windows LLVM distributions require python311.dll at runtime. Install Python 3.11 and include its directory in PATH if lldb-dap --version fails with 0xC0000135.

Install

Install the prebuilt package from the GitHub Release asset:

npm install -g https://github.com/Lin-WeiChen-Taiwan/cpp-debugger-cli/releases/download/v0.2.0/cpp-debugger-cli-0.2.0.tgz

Confirm the installation with cpp-debugger-cli --version. The package is not published to the npm registry.

Development

npm install
npm run build
npm install -g .

Requests are passed as one JSON object on stdin. stdout contains exactly one JSON response; logs are stored in the user runtime directory.

Launch

Positions use 1-based lines and columns.

{
  "version": 1,
  "operation": "launch",
  "timeoutMs": 20000,
  "params": {
    "program": "C:/project/build/app.exe",
    "args": [],
    "cwd": "C:/project",
    "stopOnEntry": false,
    "waitForStop": true,
    "breakpoints": [
      {
        "file": "C:/project/src/main.cpp",
        "breakpoints": [{ "line": 12 }]
      }
    ]
  }
}

launch and attach generate a session ID. Every later session operation must send that ID.

Operations

• Session: launch, attach, sessions, status, disconnect, terminate
• Execution: continue, pause, next, stepIn, stepOut, waitForEvent
• Inspection: threads, stackTrace, scopes, variables, evaluate
• Breakpoints: setBreakpoints
• I/O and extension: events, sendStdin, rawRequest

Execution operations wait for stopped or terminated by default. Set params.waitForStop to false for immediate acknowledgement. A wait timeout leaves the target running and returns waitTimedOut: true.

setBreakpoints replaces all source breakpoints for one file. variables, threads, stackTrace, and events default to 200 results and accept a maximum limit of 2000.

Events are kept in a bounded ring buffer and have monotonically increasing sequence numbers:

{
  "version": 1,
  "operation": "events",
  "sessionId": "SESSION_ID",
  "params": { "afterSequence": 20, "limit": 100 }
}

sendStdin is available when the adapter uses the DAP runInTerminal reverse request and the session was launched with runInTerminal: true. Adapters that do not support this mode return STDIN_UNAVAILABLE; their output can still arrive through DAP output events.

Adapter Configuration

adapterPath defaults to lldb-dap. Use adapterArgs for process arguments and adapterConfig for launch or attach fields not covered by the stable API. Stable fields override conflicting adapterConfig fields.

rawRequest can call non-lifecycle DAP requests:

{
  "version": 1,
  "operation": "rawRequest",
  "sessionId": "SESSION_ID",
  "params": { "command": "modules", "arguments": {} }
}

Lifecycle requests cannot be sent through rawRequest.

Lifecycle

Active sessions do not expire while running or stopped. Terminated and failed sessions retain final events for five minutes. disconnect does not request target termination; use terminate when the target must be stopped. Adapter crashes return ADAPTER_EXITED and are never automatically restarted because debugger state cannot be reconstructed safely.

Verification

npm run verify

The integration suite includes a fake DAP adapter and a real CMake/Ninja C++ fixture. The real test is skipped only when the required local tools are unavailable.

Current Limits

Version 0.1 does not officially support GDB, Visual Studio Debugger, remote debugging, core dumps, reverse debugging, data breakpoints, multi-process debugging, or external terminals.