Delve — API Surface#

API types#

Delve exposes four distinct API surfaces: a CLI (Cobra), an interactive REPL with Starlark scripting, a JSON-RPC 2.0 server, and a Debug Adapter Protocol (DAP) server. There is no REST/HTTP API, no gRPC, and no plugin system. The RPC2 and DAP surfaces expose the same underlying debugger; the REPL is just an RPC2 client built into the same binary.

CLI (dlv binary)#

Framework: github.com/spf13/cobra
Entry point: cmd/dlv/cmds/commands.go — New(docCall bool) *cobra.Command

Top-level commands#

Command	Description
`dlv debug [package]`	Compile and launch a debug session for a Go package
`dlv exec <binary>`	Launch a pre-built binary under debugger control
`dlv test [package]`	Compile and debug a test binary
`dlv attach <pid>`	Attach to an already-running process
`dlv core <binary> <dump>`	Post-mortem analysis of a core dump
`dlv trace [package] <fn-regex>`	Trace function calls (prints args; non-interactive)
`dlv connect <addr>`	Connect a terminal client to an existing headless server
`dlv dap`	Start a DAP server for IDE integration
`dlv replay <rr-trace>`	Replay an rr (record-and-replay) recording
`dlv version`	Print version information

Global (persistent) flags#

Flag	Default	Description
`--listen` / `-l`	`127.0.0.1:0`	Debugger server listen address; prefix with `unix:` for a domain socket
`--headless`	`false`	Run in headless server mode only (no terminal)
`--accept-multiclient`	`false`	Allow multiple simultaneous client connections
`--api-version`	`2`	JSON-RPC API version selection (only 2 is valid)
`--backend`	`default`	Backend: `default`, `native`, `lldb`, `rr`
`--build-flags`	`""`	Extra flags passed to `go build`
`--only-same-user`	`true`	Restrict connections to same OS user
`--log`	`false`	Enable debug server logging
`--log-output`	`""`	Comma-separated list of subsystems to log
`--init`	`""`	Init file executed by the terminal client on start
`--wd`	`""`	Working directory for the target process
`--redirect` / `-r`	`[]`	I/O redirect rules for the target process
`--disable-aslr`	`false`	Disable address space randomization

Command-specific flags (notable)#

attach --waitfor <prefix>: Wait for a process whose name starts with the given prefix before attaching.
trace --ebpf: Use eBPF uprobes instead of software breakpoints (Linux only, non-stop).
trace --follow-calls <depth>: Recursively trace callees to the given depth.
dap --client-addr <addr>: Dial into a waiting DAP client (reverse connection mode).
debug --tty <tty>: Assign a TTY to the target process.

JSON-RPC 2.0 API#

Package: service/rpc2
Transport: TCP (or in-process net.Conn pipe for interactive mode)
Codec: Custom JSON codec over Go’s net/rpc
Contract: service.Client interface (service/client.go) — ~50 methods; RPCServer and RPCClient both implement it

Method groups#

Session lifecycle

GetVersion() *api.GetVersionOut
ProcessPid() int
BuildID() string
LastModified() time.Time
Detach(kill bool) error
Restart(rebuild bool) ([]DiscardedBreakpoint, error)
RestartFrom(rerecord bool, pos string, resetArgs bool, ...) error
Disconnect(cont bool) error
IsMulticlient() bool

Execution control

Continue() <-chan *DebuggerState
Rewind() <-chan *DebuggerState (rr only)
DirectionCongruentContinue() <-chan *DebuggerState
Next() (*DebuggerState, error)
ReverseNext() (*DebuggerState, error) (rr only)
Step() (*DebuggerState, error)
ReverseStep() (*DebuggerState, error) (rr only)
StepOut() (*DebuggerState, error)
ReverseStepOut() (*DebuggerState, error) (rr only)
StepInstruction(skipCalls bool) (*DebuggerState, error)
ReverseStepInstruction(skipCalls bool) (*DebuggerState, error) (rr only)
Call(goroutineID int64, expr string, unsafe bool) (*DebuggerState, error) (function call injection)
Halt() (*DebuggerState, error)
CancelNext() error

Breakpoints & watchpoints

CreateBreakpoint(*Breakpoint) (*Breakpoint, error)
CreateBreakpointWithExpr(*Breakpoint, locExpr string, [][2]string, suspended bool) (*Breakpoint, error)
CreateWatchpoint(EvalScope, expr string, WatchType) (*Breakpoint, error)
CreateEBPFTracepoint(fnName string) error
GetBreakpoint(id int) (*Breakpoint, error)
GetBreakpointByName(name string) (*Breakpoint, error)
ListBreakpoints(all bool) ([]*Breakpoint, error)
ClearBreakpoint(id int) (*Breakpoint, error)
ClearBreakpointByName(name string) (*Breakpoint, error)
ToggleBreakpoint(id int) (*Breakpoint, error)
ToggleBreakpointByName(name string) (*Breakpoint, error)
AmendBreakpoint(*Breakpoint) error
GetBufferedTracepoints() ([]TracepointResult, error) (eBPF results)

Thread & goroutine management

ListThreads() ([]*Thread, error)
GetThread(id int) (*Thread, error)
SwitchThread(threadID int) (*DebuggerState, error)
ListGoroutines(start, count int) ([]*Goroutine, int, error)
ListGoroutinesWithFilter(start, count int, filters []ListGoroutinesFilter, group *GoroutineGroupingOptions, scope *EvalScope) ([]*Goroutine, []GoroutineGroup, int, bool, error)
SwitchGoroutine(goroutineID int64) (*DebuggerState, error)

Variable inspection

EvalVariable(EvalScope, symbol string, LoadConfig) (*Variable, error)
SetVariable(EvalScope, symbol, value string) error
TypeInfo(name string) (*TypeInfo, error)
ListLocalVariables(EvalScope, LoadConfig) ([]Variable, error)
ListFunctionArgs(EvalScope, LoadConfig) ([]Variable, error)
ListPackageVariables(filter string, LoadConfig) ([]Variable, error)

Register & memory access

ListThreadRegisters(threadID int, includeFp bool) (Registers, error)
ListScopeRegisters(EvalScope, includeFp bool) (Registers, error)
ExamineMemory(address uint64, length int) ([]byte, bool, error)

Debug symbol queries

ListSources(filter string) ([]string, error)
ListFunctions(filter string, tracefollow int) ([]string, error)
ListTypes(filter string) ([]string, error)
ListPackagesBuildInfo(filter string, includeFiles bool) ([]PackageBuildInfo, error)
FindLocation(EvalScope, loc string, findInstruction bool, [][2]string) ([]Location, string, error)

Stack inspection

Stacktrace(goroutineID int64, depth, skip int, StacktraceOptions, *LoadConfig) ([]Stackframe, error)
Ancestors(goroutineID int64, numAncestors int, depth int) ([]Ancestor, error)
DisassembleRange(EvalScope, startPC, endPC uint64, AssemblyFlavour) (AsmInstructions, error)
DisassemblePC(EvalScope, pc uint64, AssemblyFlavour) (AsmInstructions, error)

Recording & checkpoints (rr only)

Recorded() bool
TraceDirectory() (string, error)
Checkpoint(where string) (checkpointID int, err error)
ListCheckpoints() ([]Checkpoint, error)
ClearCheckpoint(id int) error
StopRecording() error

Core dump export

CoreDumpStart(dest string) (DumpState, error)
CoreDumpWait(msec int) DumpState
CoreDumpCancel() error

Multi-target & dynamic libs

ListTargets() ([]Target, error)
FollowExec(bool, regex string) error
FollowExecEnabled() bool
ListDynamicLibraries() ([]Image, bool, error)

Debug symbol resolution

SetDebugInfoDirectories([]string) error
GetDebugInfoDirectories() ([]string, error)
GuessSubstitutePath() ([][2]string, error)
CancelDownloads() error
DownloadLibraryDebugInfo(n int) error

Escape hatch

CallAPI(method string, args, reply any) error — calls any RPC method by name (used by Starlark bindings)

DAP (Debug Adapter Protocol) API#

Package: service/dap
Transport: TCP; also supports reverse-connect (dial to client)
Library: github.com/google/go-dap
Protocol: Microsoft Debug Adapter Protocol (VS Code, GoLand, Neovim, etc.)
Dispatch: single handleRequest(dap.Message) switch in server.go:665

Implemented requests (by required/optional)#

Required (baseline DAP compliance)

Request	Description
`Initialize`	Negotiate capabilities
`Launch`	Start process with compile or exec modes
`Attach`	Attach to existing process
`Disconnect`	End session, optionally kill target
`Threads`	List OS threads
`SetBreakpoints`	Set/replace source breakpoints
`SetFunctionBreakpoints`	Set breakpoints by function name
`ConfigurationDone`	Signal that client-side setup is complete
`Continue`	Resume execution
`Next`	Step over
`StepIn`	Step into
`StepOut`	Step out
`StackTrace`	Get call stack for a thread
`Scopes`	Get variable scopes for a frame
`Variables`	Get variables for a scope
`Evaluate`	Evaluate expression or command
`Source`	Retrieve source text for a file
`Pause`	Halt running target
`Terminate`	Kill target process

Optional (advertised capabilities)

Request	Capability
`StepBack` / `ReverseContinue`	`supportsStepBack` (rr backend only)
`SetVariable`	`supportsSetVariable`
`SetExpression`	`supportsSetExpression`
`ExceptionInfo`	`supportsExceptionInfoRequest`
`Disassemble`	`supportsDisassembleRequest`
`ReadMemory`	`supportsReadMemoryRequest`
`DataBreakpointInfo` / `SetDataBreakpoints`	`supportsDataBreakpoints` (watchpoints)
`SetExceptionBreakpoints`	`exceptionBreakpointFilters` (goroutine panic, runtime error)
`SetInstructionBreakpoints`	`supportsInstructionBreakpoints`
`LoadedSources`	`supportsLoadedSourcesRequest`
`Cancel`	`supportsCancelRequest`
`Modules`	`supportsModulesRequest`
`Restart`	`supportsRestartRequest`
`RestartFrame`	`supportsRestartFrame`
`Goto` / `GotoTargets`	`supportsGotoTargetsRequest`
`TerminateThreads`	`supportsTerminateThreadsRequest`
`StepInTargets`	`supportsStepInTargetsRequest`
`Completions`	`supportsCompletionsRequest`
`BreakpointLocations`	`supportsBreakpointLocationsRequest`

DAP Launch modes#

The launch request supports three modes via the mode field:

"debug" — compile and launch (equivalent to dlv debug)
"test" — compile test binary and launch
"exec" — launch a pre-built binary
"remote" — attach to an already-running dlv --headless server

REPL / Terminal API#

Package: pkg/terminal
Scripting: Starlark scripting via pkg/terminal/starbind
Line editing: github.com/go-delve/readline
Role: The REPL is an RPC2 client; every command translates to a service.Client method call. There is no separate code path.

Command groups#

Breakpoints

Command (aliases)	Description
`break` / `b`	Set a breakpoint by location expression
`trace` / `t`	Set a tracepoint (prints args, no stop)
`watch`	Set a watchpoint
`clear`	Delete a breakpoint by ID
`clearall`	Delete multiple breakpoints
`toggle`	Toggle a breakpoint on/off
`breakpoints` / `bp`	List active breakpoints
`on`	Execute commands when a breakpoint is hit
`condition` / `cond`	Set a conditional expression on a breakpoint

Execution control

Command (aliases)	Description
`continue` / `c`	Run until breakpoint or exit
`next` / `n`	Step over to next source line
`step` / `s`	Step into function call
`stepout` / `so`	Step out of current function
`step-instruction` / `si`	Single CPU instruction step
`next-instruction` / `ni`	Single CPU instruction step, skipping calls
`call`	Inject and execute a function call
`restart` / `r`	Restart the process
`rebuild`	Recompile and restart

Data inspection

Command (aliases)	Description
`print` / `p`	Evaluate and print an expression
`whatis`	Print type of an expression
`locals`	Print all local variables
`args`	Print function arguments
`vars`	Print package-level variables
`regs`	Print CPU registers
`set`	Assign a new value to a variable
`examinemem` / `x`	Examine raw bytes at a memory address
`display`	Print expression at every stop

Goroutine & thread management

Command (aliases)	Description
`goroutine` / `gr`	Show or switch current goroutine
`goroutines` / `grs`	List all goroutines
`thread` / `tr`	Switch to a thread
`threads`	List all threads

Stack navigation

Command (aliases)	Description
`stack` / `bt`	Print stack trace
`frame`	Switch to a specific frame
`up`	Move up one frame
`down`	Move down one frame
`deferred`	Execute command in context of a deferred call

Source & symbols

Command	Description
`list` / `ls`	Show source code at current position
`disassemble` / `disass`	Disassemble current function or range
`sources`	List source files
`funcs`	List functions (with regex filter)
`types`	List types
`packages`	List packages
`libraries`	List loaded dynamic libraries

Meta

Command	Description
`source`	Execute a file of Delve commands
`config`	Change runtime configuration
`edit` / `ed`	Open current source in `$EDITOR`
`dump`	Create a core dump of the current process
`transcript`	Append session output to a file
`exit` / `quit` / `q`	Quit the debugger
`help` / `h`	Print help

Starlark scripting#

source can load .star files. A Context interface exposes every service.Client method to Starlark. Scripts can define command_* functions which become new REPL commands. The CallAPI escape hatch allows calling arbitrary RPC methods from scripts.

Library API (if applicable)#

Delve does not publish a stable library API. The service/api package (wire types: Breakpoint, Variable, Goroutine, DebuggerState, LoadConfig, EvalScope, etc.) and service/rpc2.RPCClient are used directly by IDE extensions and tooling, but are not versioned independently. The canonical “how to write a client” document is Documentation/api/ClientHowto.md, which treats the RPC2 client as the integration point.

Backward compatibility: Semantic versioning is not enforced; clients are expected to negotiate the API version via GetVersion() and adapt to api-version: 2.
Key public packages for client authors: service/api (types), service/rpc2 (client constructor + method set), service (Client interface + Server interface).