Debug from the CLI or AI

Use the CLI or an AI tool to debug a run. The CLI, web UI and MCP share one debugger, so you can follow an AI’s work in the Activity panel.

Debug a script you run locally

Start the script with the debugger attached:

reflex run flows/checkout.lua --debug

--debug means --debug=on-error: the script pauses at a failure and keeps the browser open. Use --debug=always to attach from the first instruction. --debug-ttl 10m sets how long a pause waits after the last debugger disconnects.

In another terminal:

reflex debug wait          # report the current pause, or wait for the next one
reflex debug status        # read the state; does not attach
reflex browser summary -i -c --session run:<runId>   # inspect the paused browser
reflex debug retry --selector "role=button[name='Place order']" --everywhere --wait
reflex debug patches --apply --dry-run
reflex debug patches --apply

• --wait on retry keeps control attached until the next pause or the end of the run, so no failure runs unattended.
• --apply checks the old text before writing. On a mismatch nothing is written. Review the diff and commit it yourself.
• Commands default to your latest reflex run --debug. Pass a run id to pick another.

More: debug inspect, eval, step, continue --wait, breakpoint add flows/checkout.lua:42 and abort.

Debug a job or suite run

Attach to any queued or running run:

reflex debug attach <runId> --break 'Rest.*'
reflex debug attach <runId> --watch

--watch only observes. For a run on a project agent, patches prints the diff; apply it from a matching checkout.

Investigate a failed run

reflex runs view <runId>        # error, source, page evidence and near misses
reflex runs reproduce <runId>   # rerun locally with the browser kept open on failure
reflex runs try <runId> "role=button[name='Place order']"   # test a selector on the recorded page

For scripts and tools

Use --json for one JSON object (streams are NDJSON). debug wait exits 0 at a pause or successful end, 1 on a failed or cancelled end and 5 on timeout.

MCP tools

An AI client can use these tools with the same permissions as the CLI:

Tool	Purpose
debug_attach	Attach as watch or control. Keep the returned attachment id.
debug_state	Read the position, pause and clients.
debug_command	Send a command. Control commands need the attachment id.
debug_patches	Read the recorded fixes.
get_run_digest, get_run_logs	Start with the failure and its evidence.
replay_actions, replay_frame, replay_dom	Inspect calls and the page at a chosen point.
try_selector_on_run	Test a selector against the recorded DOM.

Read fresh state first, and send the current pauseId when you change execution, so a stale request cannot hit a later pause. Several controllers can be attached at once.

A selector fix can also become a heal suggestion. Accepting stays a human decision in the web UI.