xenia-rs/migration/claude-memory/project_xenia_rs_cli.md

name, description, type, originSessionId

name	description	type	originSessionId
xenia-rs CLI Reference	Complete CLI commands, arguments, and environment variables for the xenia-rs tool — update this when CLI changes	project	08576735-74b4-4180-994a-2eb93dc60997

Update trigger: Whenever the xenia-rs CLI changes (new commands, flags, env vars), update this file and the MEMORY.md index entry. Last documented: 2026-04-22 (added exec --halt-on-deadlock + XENIA_HALT_ON_DEADLOCK env var for deadlock investigation — bypasses the force-wake recovery path so the ctx snapshot survives).

Binary

xenia-rs — Xbox 360 XEX/XISO reverse-engineering toolchain

CLI framework: Clap 4.x with derive macros
Entry point: xenia-rs/crates/xenia-app/src/main.rs
Observability module: xenia-rs/crates/xenia-app/src/observability.rs

---

Global flags (apply to every subcommand)

Flag	Type	Effect
--log-json	bool	Force JSON on the console fmt layer (default is compact text, stderr)
--log-file <PATH>	path	Additionally write logs to file via non-blocking appender. .json extension → JSON formatter; else text
--log-filter <DIRECTIVES>	env-filter	Overrides RUST_LOG. Precedence: --log-filter > RUST_LOG > default (warn for exec --quiet, else info)
--trace-chrome <PATH>	path	Emit Chrome about:tracing JSON of all spans (uses tracing-chrome). Loadable in chrome://tracing / Perfetto
--profile <PATH>	path	Start pprof sampling profiler at 100 Hz. .svg → flamegraph; .pb → pprof protobuf. Requires profiling Cargo feature (on by default)

Cargo features on xenia-app:

• profiling (default): pulls pprof = { features = ["flamegraph", "protobuf-codec"] }. Disable with --no-default-features for minimal release builds; --profile then fails at startup with a clear error.

---

Commands

disasm — Disassemble XEX from entry point

xenia-rs disasm <PATH> [-n <COUNT>]

Arg	Type	Default	Description
path	String (positional)	—	Path to XEX file
-n, --count	usize	64	Number of instructions to disassemble

---

exec — Load and execute XEX with tracing

xenia-rs exec <PATH> [-n <MAX>] [--ips-limit <N>] [--db <DB>] [--trace-instructions] [--trace-imports] [--trace-branches] [--quiet] [--ui] [--halt-on-deadlock]

Arg	Type	Default	Description
path	String (positional)	—	Path to XEX file
-n, --max-instructions	Option<u64>	none	Max instructions before stop (unlimited if omitted)
--ips-limit	Option<u64>	none	Throttle to N instructions per second (unlimited if omitted). Check runs once per scheduler round at run_execution's outer loop — anchor is Instant::now() at function entry
--db	Option<String>	none	SQLite DB path; includes full static analysis + opt-in trace tables
--trace-instructions	bool flag	false	Log each instruction to exec_trace table
--trace-imports	bool flag	false	Log kernel/import calls to import_calls table
--trace-branches	bool flag	false	Log taken branches to branch_trace table
--quiet	bool flag	false	Suppress banners, kernel logs, register dump
--ui	bool flag	false	Open winit+wgpu window for dynamic analysis; backs XamInputGetState with gilrs; presents guest frontbuffer on VdSwap; CPU runs on worker thread. HUD shows swap count + last frontbuffer addr + pad state. Phase 1: no PM4/shader execution, so the frontbuffer is typically black for real games — HUD remains live.
--halt-on-deadlock	bool flag	false	At the hard-deadlock branch in run_execution (all live HW threads Blocked on handle waits, no pending timer), emit a per-HW-slot warn! with tid/state/pc/lr/sp and break instead of force-waking waiters with STATUS_TIMEOUT. Increments scheduler.deadlock_halts metric; sets the UI shutdown flag so the window closes alongside the worker. Default is force-wake (preserved probe-run behaviour — counts as scheduler.deadlock_recoveries). Also settable via XENIA_HALT_ON_DEADLOCK=1.

---

browse — Browse XISO disc image contents

xenia-rs browse <PATH>

Arg	Type	Default	Description
path	String (positional)	—	Path to XISO file

---

info — Display XEX header information

xenia-rs info <PATH>

Arg	Type	Default	Description
path	String (positional)	—	Path to XEX file

---

extract — Extract PE image and metadata from XEX

xenia-rs extract <PATH> [-o <OUTPUT>] [--db <DB>]

Arg	Type	Default	Description
path	String (positional)	—	Path to XEX or ISO file
-o, --output	Option<String>	input dir	Output directory
--db	Option<String>	none	SQLite DB; writes metadata, sections, imports tables

---

dis — Full disassembly with function detection and xrefs

xenia-rs dis <PATH> [-o <OUTPUT>] [--db <DB>] [--quiet]

Arg	Type	Default	Description
path	String (positional)	—	Path to XEX or ISO file
-o, --output	Option<String>	stdout	Output .asm file
--db	Option<String>	none	SQLite DB; includes extract tables + functions, labels, instructions, xrefs
--quiet	bool flag	false	Suppress assembly text output (DB-only mode)

---

check — Deterministic run digest + golden-diff regression detector (P8)

xenia-rs check <PATH> [-n <INSTRS>] [--out <PATH>] [--expect <PATH>]

Arg	Type	Default	Description
path	String (positional)	—	Path to XEX or ISO file
-n, --max-instructions	u64	2_000_000	Instructions to execute before computing the digest
--out	Option<String>	stdout	Write the 14-field JSON digest to this path
--expect	Option<String>	none	Golden digest JSON; byte-for-byte (trimmed) diff against the run's output. Exits non-zero on mismatch with expected vs actual on stderr

Digest fields (stable order, one u64 per line): path, instructions, imports, unimpl, packets, draws, swaps, resolves, unique_render_targets, shader_blobs_live, interrupts_delivered, interrupts_dropped, texture_cache_entries, texture_decodes.

Typical use: Run once on a known-good build → commit the output as run.digest.json. CI re-runs xenia-rs check … --expect run.digest.json; non-zero exit blocks the PR on drift.

---

Environment Variables

XENIA_DB_BATCH_SIZE

• Source: xenia-rs/crates/xenia-analysis/src/db.rs (lines 35-45)
• Type: u64
• Default: 100_000
• Validation: Must be > 0; invalid values fall back to default
• Effect: Rows per streaming commit / trace buffer flush. import_calls always flushes at 1,000 (not configurable).

RUST_LOG

• Source: standard tracing-subscriber env filter
• Default behavior: "warn" when exec --quiet, otherwise "info"
• Override: Set to any tracing filter string (e.g. debug, xenia_analysis=trace)
• Note: --log-filter takes precedence over RUST_LOG.

XENIA_FAKE_PAD

• Source: xenia-rs/crates/xenia-ui/src/input.rs (fake_pad_policy)
• Default: enabled (simulated pad when no physical controller)
• Disable with: XENIA_FAKE_PAD=0 (or false / off)
• Effect: when no gilrs pad is attached, XamInputGetState still returns STATUS_SUCCESS with an all-zero X_INPUT_STATE so games don't bail with ERROR_DEVICE_NOT_CONNECTED. Set to 0 to get truthful "no controller" reporting.

XENIA_SCHED_ORDER / XENIA_SCHED_SEED

• Source: xenia-rs/crates/xenia-cpu/src/scheduler.rs (OrderMode::from_env)
• Default: fixed 0..=5
• Effect: random (with optional u64 XENIA_SCHED_SEED) shuffles round order for fuzzing thread interleavings.

XENIA_HALT_ON_DEADLOCK

• Source: xenia-rs/crates/xenia-app/src/main.rs (resolved at the top of run_execution)
• Values: 1 or true (case-insensitive) to enable; anything else = disabled
• Default: disabled (force-wake waiters with STATUS_TIMEOUT, increment scheduler.deadlock_recoveries)
• Effect: equivalent to exec --halt-on-deadlock. OR'd with the flag — either source is sufficient to trip the halt path. Use from shells / recipes without rewiring CLI args.

RUST_LOG_SPAN_EVENTS

• Source: parsed by observability::parse_span_events
• Values: full | close | active | enter | exit | new (anything else = none)
• Effect: Controls the FmtSpan setting on fmt layers. close is the most useful — every span emits a line with time.busy/time.idle elapsed, giving per-phase timing in the console without reading a Chrome trace.

---

Database Table Layering

Command	Tables
extract --db	metadata, sections, imports
dis --db	above + functions, labels, instructions, xrefs
exec --db	above + exec_trace, import_calls, branch_trace*

*Only written when corresponding --trace-* flag is passed to exec.

Why: Cumulative schema lets analysis tools query across all levels without joining separate DBs.

How to apply: When suggesting DB workflows, recommend the appropriate command tier for the user's analysis goal.