fx debug cli supports both POSIX subcommands and raw --json request strings. Pass either a subcommand or --json '<payload>', never both:
# Subcommand mode and --json mode validate the same protocol models fx debug cli stack-trace -t 1 fx debug cli --json '{"command": "stack-trace", "thread_id": 1}' # Print the full JSON schema for all request and response models locally fx debug cli schema
Account for these output and path differences across commands:
success, message, body, events) on stdout.start and stop: Run locally, print {"success": <bool>, "message": "<str>"} (to stderr when success is false), and ignore --ack-seq.schema: Runs locally in CLI mode only and prints multi-line indented JSON Schema on stdout.stderr and exit with a non-zero code (1 or 2).break and tracepoint): CLI mode resolves workspace-relative, CWD-relative, and absolute paths to absolute host paths. --json mode passes "file" verbatim and requires an absolute host path.Include --ack-seq <seq> (before the subcommand) or "ack_seq": <seq> (in any daemon --json request) to prune buffered event history up to that sequence number:
fx debug cli --ack-seq 5 get-state fx debug cli --json '{"command": "get-state", "ack_seq": 5}'
Any daemon --json request can also include "last_seen_seq": <seq> to return buffered events in events. The daemon keeps up to 100 buffered events and evicts older entries automatically. If wait-for-event passes a last_seen_seq older than pruned or evicted events, message reports "Warning: Some events were pruned from history".
When you construct requests, apply these protocol rules:
"thread_id" (from wait-for-event, get-state, or threads) as -t <tid> or "thread_id": <tid>. Pass Zircon process KOIDs (from get-state "processes" or driver-list "driver_hosts"[*]."host_koid") as -p <pid> or "pid": <pid>."stopped" event. For the list of thread-pausing, auto-resuming, and non-pausing commands, see Transport and watchdog hazards.Note: Ignore --start and --count on evaluate --help. In schema output, ignore the internal hello handshake request and the unimplemented single_thread, granularity, and target_id fields on step-in, next, and finish (--single-thread applies only to continue).
The following tables list all 27 subcommands by category. In CLI syntax, -t, -p, -c, -a, -s, -k, and -w also accept --thread-id, --pid, --condition, --access-type, --size, --koid, and --watch. On tracepoint, -e also accepts --expr or --expression and --max-frames also accepts --max-matching-frames. In --json requests, you can omit <opt_*> fields to use their default or null values.
| Subcommand (aliases) | CLI syntax | --json payload |
|---|---|---|
start | start [--port <port>] [--connect] | {"command": "start", "port": <opt_int>, "connect": <opt_bool>} |
stop | stop | {"command": "stop"} |
schema | schema [--indent <n>] | (Local CLI subcommand only) |
get-state (get_state, getState) | get-state | {"command": "get-state"} (Returns threads, processes, breakpoints, watchpoints, function_breakpoints, tracepoints) |
threads | threads | {"command": "threads"} |
driver-list (driver-hosts, driver_list, driverList) | driver-list [<filter> | -f/--filter <filter>] | {"command": "driver-list", "filter": "<opt_substr>"} |
attach | attach <filter> [--exact] [--weak] [-r/--recursive] [--job-only] or attach (-d/--driver <drv> | -n/--node <moniker>) [--weak] [--wait] [-r/--recursive] [--job-only] | {"command": "attach", "filter": "<name>" | <koid>, "exact": <opt_bool>, "weak": <opt_bool>, "recursive": <opt_bool>, "job_only": <opt_bool>} or with "driver": "<drv>" or "node": "<moniker>" plus optional "weak", "wait", "recursive", "job_only" |
detach | detach (<pid> | --all) | {"command": "detach", "pid": <pid>} or {"command": "detach", "all": true} |
| Subcommand (aliases) | CLI syntax | --json payload |
|---|---|---|
wait-for-event (wait_for_event, waitForEvent) | wait-for-event [--last-seen-seq <seq>] [--timeout <secs>] | {"command": "wait-for-event", "last_seen_seq": <seq>, "timeout": <opt_secs>} |
pause | pause (-t <tid> | -p <pid>) | {"command": "pause", "thread_id": <tid>} or {"command": "pause", "pid": <pid>} |
continue | continue <tid> [--single-thread] | {"command": "continue", "thread_id": <tid>, "single_thread": <opt_bool>} |
step-in (step, s, step-into, step_in, stepIn, stepin, step_into, stepinto) | step-in <tid> | {"command": "step-in", "thread_id": <tid>} |
next (n, step-over, step_over, stepOver, stepover) | next <tid> | {"command": "next", "thread_id": <tid>} |
finish (step-out, step_out, stepOut, stepout) | finish <tid> | {"command": "finish", "thread_id": <tid>} |
| Subcommand (aliases) | CLI syntax | --json payload |
|---|---|---|
stack-trace (bt, backtrace, stack_trace, stackTrace) | stack-trace (-t <tid> | -p <pid>) [-r/--raw] [--force-remote-unwind] [--unwinder <name>] | {"command": "stack-trace", "thread_id": <tid>} or {"command": "stack-trace", "pid": <pid>} with optional "raw": <bool>, "force_remote_unwind": <bool>, "unwinder": "cfi" | "fp" | "scs" | "plt" | "armehabi" | "sigreturn" |
variables (locals) | variables -t <tid> [--frame-index <idx>] | {"command": "variables", "thread_id": <tid>, "frame_index": <opt_idx>} |
evaluate (print) | evaluate -t <tid> [--frame-index <idx>] <expr> | {"command": "evaluate", "thread_id": <tid>, "frame_index": <opt_idx>, "expression": "<expr>"} |
console (cmd, console-command, console_command) | console [-t <tid>] [--frame-index <idx>] [--] <cmd> | {"command": "console", "input": "<cmd>", "thread_id": <opt_tid>, "frame_index": <opt_idx>} |
async-backtrace (abt, tasks, async-tasks, async_tasks, asyncTasks, async_backtrace, asyncBacktrace) | async-backtrace [-p <pid>] | {"command": "async-backtrace", "pid": <opt_pid>} |
diagnose-hang (hang, hang-analyze, diagnose_hang, diagnoseHang) | diagnose-hang [-p <pid>] [--auto-resume | --no-auto-resume] | {"command": "diagnose-hang", "pid": <opt_pid>, "auto_resume": <opt_bool>} |
| Subcommand (aliases) | CLI syntax | --json payload |
|---|---|---|
modules (libs, sym-stat, sym_stat) | modules [-p <pid>] [-f/--filter <filter>] [-r/--reload] | {"command": "modules", "pid": <opt_pid>, "filter": "<opt_substr>", "force_reload": <opt_bool>} |
aspace (as) | aspace [<addr>] [-p <pid>] [-f/--filter <filter>] | {"command": "aspace", "pid": <opt_pid>, "address": "<opt_addr>", "filter": "<opt_substr>"} |
handles (handle) | handles [-p <pid>] [--type <type>] [-k <koid>] [--detail] | {"command": "handles", "pid": <opt_pid>, "type": "<opt_type>", "koid": <opt_koid>, "detail": <opt_bool>, "hex": <opt_bool>} |
mem-read (x, mem_read, memRead) | mem-read <addr_or_expr> [-s <bytes>] [-p <pid>] [-t <tid> [--frame-index <idx>]] | {"command": "mem-read", "address": "<addr_or_expr>", "size": <opt_bytes>, "pid": <opt_pid>, "thread_id": <opt_tid>, "frame_index": <opt_idx>} |
| Subcommand (aliases) | CLI syntax | --json payload |
|---|---|---|
break (b, breakpoint, set-breakpoints, set_breakpoints, setBreakpoints) | break (<file>:<line> | --file <f> --line <n> | -f/--function <sym>) [-c <expr>] [-d/--delete] | {"command": "break", "file": "<abs_host_path>", "line": <n>, "condition": "<opt_expr>", "delete": <opt_bool>} or {"command": "break", "function": "<sym>", "condition": "<opt_expr>", "delete": <opt_bool>} |
watch (watchpoint, data-breakpoint, set-data-breakpoints, set_data_breakpoints, setDataBreakpoints) | watch -t <tid> -a <write|readWrite> [--frame-index <idx>] [-c <expr>] [--hit-condition <expr>] <expr> or watch (-d/--delete <data_id> | --clear) | {"command": "watch", "name": "<expr>", "thread_id": <tid>, "frame_index": <opt_idx>, "access_type": "write" | "readWrite", "condition": "<opt_expr>", "hit_condition": "<opt_expr>"} or {"command": "watch", "name": "<data_id>", "delete": true} or {"command": "watch", "clear": true} |
tracepoint (tp, trace) | tracepoint (<file>:<line> | --file <f> --line <n> | <sym> | -f/--function <sym> | -w <expr> [-t <tid> [--frame-index <idx>]] [-a <write|readWrite>] [--size <bytes>]) [--id <id>] [-c <expr>] [-e <expr>] [--locals] [--registers] [--backtrace] [-r/--raw-backtrace] [--max-frames <n>] [--max-hits <n>] or tracepoint (--list | --clear | (<id> | --id <id>) (--enable | --disable | -d/--delete) | <target> -d/--delete) | Target: {"command": "tracepoint", "file": "<abs_host_path>", "line": <n>} or {"command": "tracepoint", "function": "<sym>"} or {"command": "tracepoint", "watch": "<expr>", "thread_id": <opt_tid>, "frame_index": <opt_idx>, "size": <opt_bytes>, "access_type": "write" | "readWrite"}, plus optional "id": <int>, "condition": "<expr>", "expressions": ["<expr>"], "capture": ["frame", "backtrace", "locals", "registers"], "raw_backtrace": <bool>, "max_matching_frames": <int>, "max_hits": <int>. Manage: {"command": "tracepoint", "list_all": true}, {"command": "tracepoint", "clear": true}, or {"command": "tracepoint", "tracepoint_id": <id>, "enabled": <bool> | "delete": true} |