dbg Debugger

dbg is a CLI debugger that supports Node.js (V8/CDP), Bun (WebKit/JSC), Python (via debugpy/DAP), Java (via JDWP/DAP) and native code (C/C++/Rust/Swift via LLDB/DAP). It uses short @refs for all entities -- use them instead of long IDs.

Supported Runtimes

The runtime is auto-detected from the launch command for JS and Python runtimes, including executables compiled by Bun (else pass --runtime bun). Everything after the program's name goes to it unchanged. For native code, use --runtime lldb. Python can also attach to a running debugpy listener over TCP (--runtime python).

Core Debug Loop

# 1. Launch with breakpoint at first line
dbg launch --brk node app.js
# Or: dbg launch --brk bun app.ts
# Or: dbg launch --brk python3 app.py
# Or: dbg launch --brk --runtime lldb ./my_program
# Or attach to a running process with the --inspect flag
dbg attach 9229

# 2. Set breakpoints at suspicious locations
dbg break src/handler.ts:42
dbg break src/utils.ts:15 --condition "count > 10"

# 3. Run to breakpoint (--wait blocks until it pauses or the program ends;
#    "Running (no pause within 30s)" means it ran out: dbg continue --wait 60 keeps waiting)
dbg continue --wait 30

# 4. Inspect state (shows location, source, locals, stack)
dbg state

# 5. Drill into values
dbg props @v1              # expand object
dbg props @v1 --depth 3   # expand nested 3 levels
dbg eval "x + 1"

# 6. Fix and verify (JS/TS only)
dbg set count 0            # change variable
dbg hotpatch src/utils.js  # live-edit (reads file from disk)
dbg continue               # verify fix

Debugging Strategies

Bug investigation -- narrow down with breakpoints

dbg launch --brk node app.js
dbg break src/api.ts:50                    # suspect line
dbg break src/api.ts:60 --condition "!user" # conditional
dbg continue
dbg vars                                    # check locals
dbg eval "JSON.stringify(req.body)"         # inspect deeply
dbg step over                               # advance one line
dbg state                                   # see new state

Native code debugging (C/C++/Rust)

dbg launch --brk --runtime lldb ./my_program
dbg break main.c:42
dbg break-fn main                          # function breakpoint
dbg continue
dbg vars                                    # inspect locals
dbg eval "array[i]"                         # evaluate expression
dbg step into                               # step into function

Python debugging (debugpy)

Python uses the debugpy DAP adapter. Two ways in:

Launch (auto-detected from a python/python3 command):

dbg launch --brk python3 app.py        # pauses at first line
dbg break app.py:42
dbg continue
dbg state                              # location + locals + stack
dbg eval "some_expr"                   # evaluate in the paused frame
dbg step over

Attach -- the debuggee runs its own debugpy listener and dbg connects over TCP (no adapter spawned in between). Useful when the process must be launched a specific way (a test runner, a virtualenv, a secrets wrapper):

# 1. Start the program listening on a port. --wait-for-client blocks before
#    the first line runs, so you have time to attach and set breakpoints.
python3 -m debugpy --listen 5679 --wait-for-client app.py &

# 2. Attach. --runtime python (alias: debugpy) is REQUIRED for a bare port.
dbg attach 5679 --runtime python

# 3. Set breakpoints (use absolute paths), then drive execution.
dbg break /abs/path/app.py:42
dbg continue
dbg state

Notes:

• --wait-for-client treats the FIRST TCP connection as the client -- don't probe the port to check readiness; just attach once debugpy prints its startup banner to stderr.
• A short script can run to completion before you set a breakpoint. Set it immediately after attaching, or attach to a long-running entry point.
• dbg set / dbg hotpatch are JS/TS only; inspection (break, continue, state, vars, eval, step, break-fn) all work for Python.

Attach to running/test process (Node/Bun)

# Start with inspector enabled
node --inspect app.js
# Or: bun --inspect app.ts
# Then attach
dbg attach 9229
dbg state

# Bun process or Bun-compiled binary: BUN_INSPECT opens the inspector, `?break=1`
# holds the process until dbg attaches, then pauses on its first statement.
BUN_INSPECT='ws://localhost:6499/app?break=1' ./my-bun-binary
dbg attach ws://localhost:6499/app        # runtime auto-detected
# Function breakpoint (JS/TS): a path from the global scope, an @ref, or --name <regex> (Bun)
dbg break-fn fetch --condition 'String(args[0]).includes("/v1/messages")'
dbg break-fn @v12                          # a function object you found in vars/props
dbg logpoint fn:service.ping '"ping", label'   # trace calls without pausing; dbg console
dbg continue                              # pauses on the call; `dbg stack` @f1 is the caller

Trace execution flow with logpoints (no pause)

dbg logpoint src/auth.ts:20 '"login attempt:", username'   # console.log's arguments
dbg logpoint src/auth.ts:45 '`auth result: ${result}`'
dbg continue
dbg console    # see logged output; logpoints never print into the program's own output

Inspect state as the program exits (JS)

dbg catch exit              # pause in the program's exit, state still alive
dbg continue --wait 60      # runs until it exits
dbg eval "code"             # the exit code; eval anything else that is still there
dbg continue                # let it exit

Exception debugging

dbg catch uncaught          # pause on uncaught exceptions
dbg continue                # runs until exception
dbg state                   # see where it threw
dbg eval "err.message"      # inspect the error
dbg stack                   # full call stack

TypeScript source map support

dbg automatically resolves .ts paths via source maps. Set breakpoints using .ts paths, see .ts source in output. Use --generated to see compiled .js if needed.

Ref System

Every output assigns short refs. Use them everywhere:

• @v1..@vN -- variables: dbg props @v1, dbg set @v2 true
• @f0..@fN -- stack frames: dbg eval --frame @f1 "this"
• BP#1..N -- breakpoints: dbg break-rm BP#1, dbg break-toggle BP#1
• LP#1..N -- logpoints: dbg break-rm LP#1

Refs @v/@f reset on each pause. BP#/LP# persist until removed.

Key Flags

• --json -- machine-readable JSON output on any command
• --session NAME -- target a specific session (default: "default")
• --runtime NAME -- select debug adapter (e.g. lldb for native code)
• --generated -- bypass source maps, show compiled JS (on state/source/stack)

Command Reference

See references/commands.md for full command details and options.

Tips

• dbg state after stepping always shows location + source + locals -- usually enough context
• dbg state -c for source only, -v for vars only, -s for stack only -- save tokens
• Minified/bundled code: dbg sourcemap <script> --pretty shows the script formatted from then on (positions and breakpoints translate); dbg source --width 600 shows 600 chars around the paused column; dbg search "text" --width 200 windows each match
• dbg eval supports await and --await (JS/TS). Promises settle only while the program runs: paused, you get an already-settled value, else an explanation
• dbg eval <expr> --out file.txt writes the whole value (output is otherwise cut at 80 chars)
• In ES modules require is undefined: use process.getBuiltinModule("node:fs")
• dbg blackbox "node_modules/**" -- skip stepping into dependencies
• dbg hotpatch file reads the file from disk -- edit the file first, then hotpatch (JS/TS only)
• dbg break-fn funcName -- function breakpoints: by symbol on DAP runtimes; on JS by path (obj.method), @ref, or --name <regex> (Bun). --condition/--log run where the pause lands: the function's own parameters, arguments and this; for native functions (e.g. fetch on Bun), which dbg wraps in the process, args and this. The path must exist when set; dbg stop removes wrappers
• dbg eval works on a running target too (global scope); only --frame needs a pause
• Python: dbg launch --brk python3 app.py, or attach to a debugpy --listen <port> server with dbg attach <port> --runtime python
• Execution commands (continue, step, pause, run-to) auto-return status
• dbg stop kills the debugged process and daemon