Configuration reference

Every key of .bugsaur/config.toml. The list is closed: an unknown key is a parse error that stops the launch.

Top level

Key	Type	Required	Default	Description
version	integer	yes	—	config format version. Currently 1
default	string	no	—	profile used when no name is given. Required once there is more than one profile
ui	table	no	—	window settings; see [ui]
profiles	table	no	{}	profiles by name; see [profiles.<name>]

version = 1
default = "app"

[profiles.<name>]

Key	Type	Required	Default	Description
adapter	string	yes	—	adapter id from the catalog: dlv, codelldb, debugpy, php
program	string	yes	—	what to debug. A relative path resolves from the project root
adapter_command	string	no	from the catalog	overrides the adapter's command when it lives in vendor/ or node_modules/ rather than on PATH
cwd	string	no	the project root	working directory of the debuggee
args	array of strings	no	[]	the debuggee's command-line arguments
env_file	string	no	—	file of environment variables. Named but missing is a launch error
env	table of strings	no	{}	environment variables; override env_file and the inherited environment
launch_timeout	integer	no	120	seconds for launch / attach and configurationDone responses
mode	string	no	launch	launch or attach
build	table	no	from the catalog	how to build before launching; see build
launch_arguments	table	no	{}	the DAP request body, passed to the adapter as-is

[profiles.api]
adapter = "dlv"
program = "cmd/api"
cwd = "."
args = ["--verbose"]
env_file = ".env"
env = { LOG_LEVEL = "debug" }
launch_timeout = 300
mode = "launch"

${root} expands to the absolute project root in env, args, adapter_command and launch_arguments.

[profiles.<name>.build]

Key	Type	Required	Default	Description
command	string	yes	—	the executable to run
args	array of strings	no	[]	its arguments

Substitutions in args: {out} — the binary being built; {program} — what program names.

[profiles.worker.build]
command = "go"
args = ["build", "-tags=dev", "-gcflags=all=-N -l", "-o", "{out}", "./cmd/worker"]

[profiles.<name>.launch_arguments]

A free-form table passed to the adapter as the DAP request body, on top of the catalog's defaults and on top of everything Bugsaur generated. A key is replaced whole, not merged. Bugsaur does not interpret its contents — the meaning belongs to the adapter.

Keys the PHP adapter reads: port, pathMappings, sessionMode — plus testCommand for the test-under-cursor flow.

[profiles.docker.launch_arguments]
sessionMode = "server"
port = 9003
pathMappings = { "/app" = "${root}" }

[ui]

Key	Type	Required	Default	Description
theme	string	no	dark	dark, light or system
width	integer	no	800	initial window width in logical pixels
height	integer	no	600	initial window height in logical pixels
layout	table	no	—	panel layout; see [ui.layout]
keymaps	table	no	—	window hotkeys; see [ui.keymaps]

An absent key is not the same as an explicitly set one: silence lets the editor decide, an explicit value wins over the editor. See UI.

[ui.layout]

Key	Type	Required	Default	Description
left	float 0–1	no	0.25	share of the window width for the left column
left_split	float 0–1	no	0.35	share of the column height for top_left
main_split	float 0–1	no	0.35	share of the right area's height for main
top_left	array of strings	no	["Threads"]	panels in the upper left zone
bottom_left	array of strings	no	[]	panels in the lower left zone
main	array of strings	no	everything else	panels in the main zone
bottom	array of strings	no	["Call Stack"]	panels below the main zone

Valid panel names: Threads, Call Stack, Variables, Watches, Evaluate, Logs, Inspector, Breakpoints.

Launch errors: an unknown panel name, a panel named in two zones, a share outside 0–1, a layout leaving no panels.

[ui.keymaps]

A table of action → chord. An empty string unbinds.

Group	Actions
Execution	continue, step_into, step_over, step_out, pause, terminate, restart
Panels	next_panel, previous_panel, focus_threads, focus_call_stack, focus_variables, focus_watches, focus_evaluate, focus_logs, focus_inspector, focus_breakpoints
Navigation	next_row, previous_row, top, bottom, collapse, expand, activate, delete_row, cancel
Variables search	search, search_next, search_previous, search_continue
Other	help

A chord is modifiers Cmd, Ctrl, Alt, Shift joined by +, plus a key name (F1…F20, a letter, Enter, Space, ArrowDown, …). Modifier order is irrelevant. An unknown action, key or modifier stops the launch.

Files next to the config

Path	What it is
.bugsaur/config.toml	this file — the project's, committed
.bugsaur/breakpoints.json	your breakpoints — personal, git-ignored
.bugsaur/build/	binaries Bugsaur builds; ignores itself
.bugsaur/logs/	logs saved from the Logs panel
.bugsaur-keys.json	personal per-project hotkeys, chord → action

A complete example

version = 1
default = "api"

[ui]
theme = "system"

[ui.layout]
left = 0.3
bottom_left = ["Call Stack"]
bottom = []

[ui.keymaps]
continue = "Alt+R"
pause = ""

[profiles.api]
adapter = "dlv"
program = "cmd/api"
args = ["--config", "${root}/configs/dev.yaml"]
env_file = ".env"
env = { LOG_LEVEL = "debug" }
launch_timeout = 300

[profiles.api.build]
command = "go"
args = ["build", "-gcflags=all=-N -l", "-o", "{out}", "./cmd/api"]

[profiles.worker]
adapter = "dlv"
program = "cmd/worker"