CLI reference¶

bugsaur init [<path>]
bugsaur run --project <path> [--profile <name>] [--break <file:line>] [--test-at <file:line>]
bugsaur serve --socket <path> [--project <path> [--profile <name>] [--break <file:line>]]
bugsaur gui [--socket <path>] [--control-socket <path>] [--gui-keymaps <json>] [--focus-on-stop]
            [--theme dark|light|system] [--layout <json>]
            --project <path> [--profile <name>] [--break <file:line> ...] [--test-at <file:line>]

Run bugsaur with no arguments to print this usage; it exits with status 2.

`bugsaur init`¶

Create .bugsaur/config.toml for a project without launching anything.

bugsaur init [<path>]

Argument	Description
`<path>`	project directory; the current directory when omitted

The language is detected by a marker file — Cargo.toml, go.mod, composer.json, pyproject.toml / setup.py / requirements.txt — and one profile is written per debuggable entry point. If the language is not recognised, the command fails and names the directory.

bugsaur init
bugsaur init /path/to/project

`bugsaur run`¶

Start a debug session without opening the window.

bugsaur run --project <path> [--profile <name>] [--break <file:line>] [--test-at <file:line>]

Option	Description
`--project <path>`	any directory inside the project
`--profile <name>`	which profile to use; `default` when omitted
`--break <file:line>`	a breakpoint; replaces the saved set entirely
`--test-at <file:line>`	debug the test at that location instead of the profile's program

`bugsaur serve`¶

Run the backend and accept a source frontend on a socket, without a window.

bugsaur serve --socket <path> [--project <path> [--profile <name>] [--break <file:line>]]

Option	Description
`--socket <path>`	Unix socket for the source frontend. Required
`--project <path>`	project directory
`--profile <name>`	which profile to use
`--break <file:line>`	a breakpoint

--test-at is not supported here

Test-under-cursor debugging works with run and gui, not with serve.

`bugsaur gui`¶

Open the debugger window. The mode the Neovim plugin starts for you when gui = true.

bugsaur gui [--socket <path>] [--control-socket <path>] [--gui-keymaps <json>] [--focus-on-stop]
            [--theme dark|light|system] [--layout <json>]
            --project <path> [--profile <name>] [--break <file:line> ...] [--test-at <file:line>]

Project options¶

Option	Description
`--project <path>`	any directory inside the project
`--profile <name>`	which profile to use; `default` when omitted
`--break <file:line>`	a breakpoint; may be repeated. Replaces the saved set entirely
`--test-at <file:line>`	debug the test at that location instead of the profile's program

Window options¶

Option	Description
`--theme dark\\|light\\|system`	window theme
`--layout <json>`	panel layout; the same keys as `[ui.layout]`
`--width <px>`	initial window width in logical pixels
`--height <px>`	initial window height in logical pixels
`--gui-keymaps <json>`	window hotkeys, action → chord
`--focus-on-stop`	raise the window on every stop

The project wins over these flags

--theme, --layout, --width and --height are the editor's suggestion. They apply only when the project's [ui] section says nothing on the subject. See Configuration → UI.

Socket options¶

Option	Description
`--socket <path>`	socket for the source frontend
`--control-socket <path>`	control socket

Options common to `run`, `serve` and `gui`¶

Launching without a project config¶

Instead of --project, name everything explicitly:

Option	Description
`--adapter <id>`	adapter id from the catalog
`--program <path>`	what to debug
`--cwd <path>`	working directory
`--launch-arguments <json>`	the DAP request body, as JSON

bugsaur gui --adapter codelldb --program ./build/app --break ./src/main.c:20

The adapter catalog¶

Option	Description
`--adapters <path>`	catalog file to use instead of the default locations

Rules worth knowing¶

Configuration comes from <root>/.bugsaur/config.toml and is created automatically if absent when the project's language is recognised.

Without --break, the set from <root>/.bugsaur/breakpoints.json — saved by the editor — is used. An explicit --break replaces it entirely.

--test-at is mutually exclusive with --program. It works in run and gui, not in serve. Breakpoints behave the same way with it.

Without --cwd, the working directory is the project root — or, for a manual launch with no project, the current directory.