cxdbg 2.10.1
See the version list below for details.
dotnet tool install --global cxdbg --version 2.10.1
dotnet new tool-manifest
dotnet tool install --local cxdbg --version 2.10.1
#tool dotnet:?package=cxdbg&version=2.10.1
nuke :add-package cxdbg --version 2.10.1
cxdbg
A debugger for SharpConsoleUI applications. It attaches to a running app over its diagnostics socket and asks it questions, or acts on it.
A terminal application is the one program you cannot printf-debug: the screen
is the output, and a Console.WriteLine corrupts the thing you are trying to
read. cxdbg is the way in - it asks over a socket and prints the answers
somewhere else.
A protocol verb answers in JSON, so anything here pipes into jq and a script
can do by itself what this README does by hand. The readable layer - show,
why - formats instead, and takes --json when you want the reply raw.
dotnet tool install -g cxdbg

Three questions about a live app: what the layout tree holds, which container decided a control's size, and what Tab can reach.
Starting an app under it
cxdbg run ./MyApp
Everything after -- belongs to the application, passed through unchanged, and
cxdbg reads none of it. cxdbg names the socket before the app exists, so there
is nothing to hunt for afterwards.
Where it runs
An app wants a terminal of its own: it asks for socket consent on the plain console before it paints, and someone has to read and answer that. Two programs drawing on one screen produce neither. So cxdbg prints the socket and asks:
socket /run/user/1000/cxdbg-990879.sock
start it in a new terminal (kitty), or here? (T/h)
Answer h and it runs as a child of cxdbg, which then exits — the app keeps
this terminal and paints over it.
Three things take the question away:
--no-terminal |
run it here, do not ask |
--attach |
a terminal of its own, necessarily: the prompt takes over this one |
| piped or redirected stdin | nobody to ask, so nothing is started — see below |
With no emulator on the machine, cxdbg says so and asks whether to run it here
anyway. CXDBG_TERMINAL picks one; CXDBG_TERMINAL=none says there is none.
When cxdbg starts nothing — declined, or a scripted run with no terminal — it prints the two lines to run the app yourself, with the socket it already named, so the path still works afterwards:
export SHARPCONSOLEUI_DIAGNOSTICS_SOCKET=/run/user/1000/cxdbg-e0afbe.sock
./MyApp
Add --attach to start the app and open a prompt on it in one go.
cxdbg does not supervise what it starts: the app is still running when cxdbg exits. Leaving the prompt offers to stop it, since the prompt knows exactly which process it has been talking to - but declining is the default, and a redirected input is not asked at all.
The prompt
One question per command is right for a script and tiring for a person working
through a problem. shell keeps the socket open:
cxdbg shell -s /run/user/1000/app.sock # `attach` is the same command
connected to pid 48213 (app.sock). exit to leave.
cxdbg> focus
window Settings
focused DropdownControl
cxdbg> key --spec Tab
sent 1 key
cxdbg> focus
window Settings
focused ButtonControl
cxdbg> exit
stop pid 48213 as well? (y/N)
Up and down walk the history, Tab completes a verb, then that verb's fields,
then a path after >. Ctrl+A, Ctrl+E, Ctrl+U and Ctrl+K edit the line.
A leading dot marks cxdbg's own layer, so no verb the protocol ever gains can collide with one:
.help .help tree |
what can be typed, or one verb in detail |
.show <verb> .why size <control> |
the readable layer, in place |
.last [show] .last > <file> |
the reply that was too big to print |
.socket |
which application this is |
connect <path> |
move to another application, keeping your place |
Replies too big to print
A screenshot is 75KB of base64 and a cells snapshot 51KB. Printed at a prompt either one takes your scrollback with it, so above 8KB the prompt says what it is and keeps it:
cxdbg> image
75610 bytes of png (704x448), not printed.
Give --path to write it, or redirect it at the prompt.
cxdbg> .last > /tmp/shot.png
wrote 75610 bytes to /tmp/shot.png
That file is a real PNG, not base64: a reply carrying data and an encoding
is written as the decoded bytes, and the reply's own format decides which
- not the filename. Everything else is written as the protocol sent it, so
jqcan read it.
> works on any verb, not only the big ones, and >> appends.
Asking
Three verbs answer the same question three ways, and the disagreement between them is usually the bug:
cxdbg show tree |
what layout BELIEVES, desired against arranged |
cxdbg snapshot |
what the screen SHOWS, as text |
cxdbg snapshot --format cells |
what is in each COLUMN, one entry per cell |
cxdbg image |
what it LOOKS LIKE, with real glyphs |
cxdbg desktop |
the SCREEN: size, origin, modals, portals |
cxdbg control --control X |
what ONE control is, and what contains it |
cxdbg inspect --x 20 --y 10 |
what is under a POINT |
A control with a zero-width arranged rect is in tree, reachable by focus, and
invisible in snapshot. That pattern is obvious here and invisible to tmux.
When the columns do not add up, ask for cells:
cxdbg snapshot --format cells --y 7 --h 1
row 7
2 日 width 2
3 <- the column before this one is two wide
4 A width 1
Text cannot answer this. It folds a wide glyph into one character and drops the second column it occupies, which is exactly what you are looking for.
--format markup gives the same frame as text that parses back into cells, for
keeping or replaying:
cxdbg snapshot --format markup > frame.txt
When the question is about one control rather than the whole tree:
cxdbg control --control okButton
control ScrollablePanelControl
layout ScrollLayout
visible true
desired w 30 h 10
bounds 30x25 at 0,3
absolute 30x25 at 0,3
id ScrollablePanelControl#165f26b
props width height horizontal Left vertical Fill sticky None
state enabled true focusable true scrollOffset 0 viewportExtent 25 contentExtent 65
window SharpConsoleUI Demo
control id layout bounds
1 (root) - DockRootLayout 88x28 at 0,0
Its size, its state, and the containers above it - outermost first. Name it by
its Name, by the id tree reports, or by its bare type.
When you have a point, not a name
cxdbg inspect --x 20 --y 10
at 20,10
cell 'a' fg #eeeeee bg #2d2d2d
window SharpConsoleUI Demo [active]
region client
control MarkupControl
28x1 at 0,5
inside (root) > BodyMarker > NavigationView > HorizontalGridControl > ColumnContainer > ScrollablePanelControl
The answer to "my click does nothing here" is usually the region line:
at 0,1
cell '╔' fg #00ffff bg #262626
window SharpConsoleUI Demo [active]
region resize (TopLeft)
control none - this is window chrome
A click on chrome and a click on a control that ignored it look identical on screen. The window and the region come from the same code a real press runs, so this is what the click actually finds - not what should be there.
Explaining
cxdbg why size ChartControl#b679e5 # which container narrowed it, and where
cxdbg why color Danger --state Disabled
why answers the questions whose answer is a cascade: why is this forty wide,
why is this green. The answer is usually a container several levels up, or a
contrast adjustment.
Acting
cxdbg send key Tab
cxdbg send click 20 10
cxdbg send resize 80 24 # headless apps only; a terminal owns its own size
cxdbg set --logLevel Trace # bare `cxdbg set` reads them all
Input is asynchronous: the app has the keystroke when the command returns, not
necessarily the result. Poll cxdbg frame until the counter moves.
One syntax
cxdbg <verb> [--field value ...] [-s <socket>]
The field names are the protocol's own, so there is nothing to learn twice. A
bare --field is true; values are read as numbers, booleans or text; and
--field=value carries one that starts with a dash.
cxdbg tree --depth 2
cxdbg snapshot --format cells --y 7 --h 1
cxdbg set --logLevel Trace
cxdbg measure --control ChartControl#b679e5
The prompt takes the same line, minus the socket it already holds. Anything
you type at cxdbg> works on the command line and the other way round.
Nothing is declared in advance, which is the point: a verb that gains a field gains an option, and a verb cxdbg has never heard of is passed through, because the app can be newer than the debugger attached to it.
cxdbg commands # what this app answers, from the app
cxdbg metrics --json # the reply as the protocol sent it
--help works at every level: cxdbg help, cxdbg help tree, cxdbg tree --help, cxdbg run --help.
Exit codes
| 0 | answered |
| 1 | the application refused, and said why |
| 2 | nothing was listening |
| 3 | cxdbg rejected the command line; nothing was sent |
Only 1 says anything about the application.
Consent
An app opens a socket when SHARPCONSOLEUI_DIAGNOSTICS_SOCKET is set, after
asking on the console - the variable alone is not consent, since it can be
inherited from a shell profile or left over in a terminal. A headless app has
nobody to ask and opens it without prompting.
There is no verb that stops an application: the protocol is a way to observe one, and a probe that could kill what it is watching would be a worse thing than a leaked process. The prompt's offer on the way out is not a verb - it is cxdbg stopping a process by pid, after the person at the keyboard said so.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
| Version | Downloads | Last Updated |
|---|---|---|
| 2.11.0 | 86 | 11/17/2026 |
| 2.10.14 | 95 | 11/14/2026 |
| 2.10.13 | 94 | 11/12/2026 |
| 2.10.12 | 83 | 11/12/2026 |
| 2.10.11 | 98 | 11/11/2026 |
| 2.10.10 | 95 | 11/10/2026 |
| 2.10.9 | 100 | 11/6/2026 |
| 2.10.8 | 100 | 11/4/2026 |
| 2.10.7 | 98 | 11/4/2026 |
| 2.10.6 | 97 | 11/3/2026 |
| 2.10.5 | 120 | 10/30/2026 |
| 2.10.4 | 114 | 10/30/2026 |
| 2.10.3 | 105 | 10/29/2026 |
| 2.10.2 | 136 | 10/29/2026 |
| 2.10.1 | 134 | 10/28/2026 |