Debug Microflows — mxcli debug

mxcli debug drives the Mendix runtime’s microflow debugger from the command line: set breakpoints by name, inspect a paused microflow’s variables, and step/continue — against an app started by mxcli run --local. It is the headless counterpart to Studio Pro’s debugger.

Because mxcli owns both halves — the admin password + app URL (from run --local) and the activity model GUIDs (from the .mpr) — it can offer breakpoints by name, so you never handle raw GUIDs.

Quick start

# terminal 1 — app with the debugger enabled and a session ready
mxcli run --local -p app.mpr --debug

# terminal 2 — break by name, then inspect/step/continue (same -p)
mxcli debug activities Sudoku.ACT_Hint -p app.mpr
mxcli debug break Sudoku.ACT_Hint --activity 'Retrieve' -p app.mpr
#   ...trigger the microflow in the browser (the request pauses)...
mxcli debug paused   -p app.mpr
mxcli debug inspect Game -p app.mpr
mxcli debug step over    -p app.mpr
mxcli debug continue     -p app.mpr
mxcli debug disable      -p app.mpr        # always finish here

--debug on run --local enables the debugger and starts a session (cached under <projectDir>/.mxcli/), so you skip a separate mxcli debug enable. With no breakpoints set, nothing pauses — --debug alone is behaviour-neutral.

Two APIs, one command

Under the hood the debugger spans two runtime APIs, which mxcli debug hides:

• the M2EE admin API toggles the debugger (enable/disable/status);
• the app’s /debugger/ endpoint runs the session (breakpoints, paused state, stepping).

Commands

Selecting an activity: --activity '#2' (the index from activities) or a caption substring like --activity 'Retrieve' (case-insensitive; must match one).

Selecting a paused flow: --flow <debug_id> (from paused); a single paused flow is auto-selected.

Connection flags

Defaults target a run --local runtime; override to debug a differently-configured or remote runtime.

Nanoflows (client-side)

mxcli debug works for nanoflows as well as microflows. break / activities / unbreak auto-detect the document type and set the breakpoint correctly — a nanoflow uses the runtime’s nanoflow_name parameter (the wrong key NPEs the runtime; mxcli handles it). Break by name the same way:

mxcli debug break Sudoku.NF_ToggleNotes --activity 'Change' -p app.mpr

A paused nanoflow does not appear in get_paused_microflows; it surfaces only in the runtime’s poll_events. mxcli debug paused (and step/inspect/continue) merge both sources, so a paused nanoflow appears with its debug_id; its variables are shown under the Client events (poll_events) section of paused.

A nanoflow’s debug_id is single-use — it changes after every step (a microflow’s is stable). Let step/inspect/continue auto-resolve the flow (omit --flow); each command re-reads the current state and picks up the fresh id. A --flow value copied from an earlier paused goes stale after the first nanoflow step.

Nanoflow logging: a nanoflow logs to the browser console and to the server runtime log, but the runtime rewrites the log node to Client_Nanoflow — so in .mxcli/runtime.log a nanoflow’s LOG NODE 'Sudoku' … appears as Client_Nanoflow:, not Sudoku:. Grep for Client_Nanoflow (or the message text); a node-name filter built for microflows drops nanoflow lines. Note LOG DEBUG from a nanoflow is dropped server-side (browser console only) — only INFO/WARNING/ERROR reach runtime.log.

Important behaviour

• A breakpoint pauses whoever hits it — the browser included. The triggering request hangs until continue or disable. Don’t leave a paused session idle.
• Always mxcli debug disable when done. run --local --debug does this on shutdown; a manual enable is your responsibility.
• Use the same -p for every command. The session token and breakpoint record live under <projectDir>/.mxcli/.