name: "cli-anything-unrealinsights"
description: "Capture Unreal Engine traces, inspect Trace Store files, keep Unreal Insights GUI open, and export/summarize timing/counter data."

cli-anything-unrealinsights#

Use this CLI when you need agent-friendly access to Unreal Insights trace capture
and exporter workflows on Windows.

Prerequisites#

Windows
Unreal Engine tools installed with UnrealInsights.exe
Verified with UE 5.5; headless timing exporters include compatibility handling

for UE 5.3-style command parsing where possible

Optional explicit env vars:
- UNREALINSIGHTS_EXE
- UNREAL_TRACE_SERVER_EXE
- UNREALINSIGHTS_TRACE

Core Commands#

Backend discovery#

cli-anything-unrealinsights --json backend info

To use a source-built engine's matching UnrealInsights.exe:

cli-anything-unrealinsights --json backend ensure-insights `
  --engine-root 'D:\code\D5\d5render-ue5_3'

This first looks for Engine\Binaries\Win64\UnrealInsights.exe under the
specified engine root, then builds it with that engine's Build.bat if needed.

Trace session state#

cli-anything-unrealinsights trace set D:\captures\session.utrace
cli-anything-unrealinsights --json trace info

Trace Store discovery#

cli-anything-unrealinsights --json store info
cli-anything-unrealinsights --json store list --live-only
cli-anything-unrealinsights --json store latest --set-current

Capture orchestration#

cli-anything-unrealinsights --json capture run `
  --project 'D:\Projects\MyGame\MyGame.uproject' `
  --engine-root 'D:\Program Files\Epic Games\UE_5.5' `
  --output-trace D:\captures\boot.utrace `
  --channels "default,bookmark" `
  --exec-cmd "Trace.Bookmark BootStart" `
  --wait --timeout 300

You can also keep using the explicit form:

cli-anything-unrealinsights --json capture run `
  'D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor.exe' `
  --target-arg 'D:\Projects\MyGame\MyGame.uproject'

Continuous capture session control#

cli-anything-unrealinsights --json capture start `
  --project 'D:\Projects\MyGame\MyGame.uproject' `
  --engine-root 'D:\Program Files\Epic Games\UE_5.5' `
  --output-trace D:\captures\live_session.utrace

cli-anything-unrealinsights --json capture status
cli-anything-unrealinsights --json capture snapshot D:\captures\live_snapshot.utrace
cli-anything-unrealinsights --json capture stop

This is the preferred flow when an agent needs to start profiling now and stop
or snapshot later in a follow-up turn.

If a tracked capture session is still running, capture start now requires
--replace so the previous process is stopped before a new one is launched.

Live trace control backend#

$env:UNREALINSIGHTS_LIVE_EXEC='ushell-wrapper --pid {pid} --cmd "{cmd}"'
cli-anything-unrealinsights --json live processes
cli-anything-unrealinsights --json live trace-status --pid 1234
cli-anything-unrealinsights --json live bookmark --pid 1234 "BeforeExport"
cli-anything-unrealinsights --json live stop-trace --pid 1234

Live command delivery requires UNREALINSIGHTS_LIVE_EXEC or --backend-command.
If no backend is configured, live commands return a JSON error and do not claim
success. live stop-trace stops trace collection without killing the UE process;
capture stop still terminates the harness-launched process tree.

GUI co-pilot#

cli-anything-unrealinsights --json gui status
cli-anything-unrealinsights --json gui open --trace D:\captures\session.utrace
cli-anything-unrealinsights --json gui open-latest

GUI commands omit -NoUI and -AutoQuit so Unreal Insights remains open.

Offline exporters#

cli-anything-unrealinsights --json -t D:\captures\session.utrace export threads D:\out\threads.csv
cli-anything-unrealinsights --json -t D:\captures\session.utrace export timer-stats D:\out\stats.csv --region=EXPORT_CAPTURE
cli-anything-unrealinsights --json -t D:\captures\session.utrace export counter-values D:\out\counter_values.csv --counter=*

Prefer equals-form wildcard filters such as --timers=* and --counter=*.
The harness passes simple values to UnrealInsights without inner quotes so
wildcards remain usable inside -ExecOnAnalysisCompleteCmd.

Batch response files#

cli-anything-unrealinsights --json -t D:\captures\session.utrace batch run-rsp D:\out\exports.rsp

Analyze summaries#

cli-anything-unrealinsights --json -t D:\captures\session.utrace analyze summary --out D:\out\summary
cli-anything-unrealinsights --json analyze summary --skip-export --out D:\out\summary

The summary reports top timers, focused GameThread/RenderThread/RHIThread
hotspots, wait/task-related timers, counter peaks, and uncovered domains for
future Memory/Network/Slate/Asset/Cooking analysis.

analyze summary also returns export_status and
summary.diagnostics.export_status_counts so agents can distinguish successful
exports from trace/filter combinations that completed but produced no rows.

JSON Output Guidance#

Prefer --json for agent workflows.
Export commands return:
- trace_path
- exec_command
- output_files
- output_status
- status_message
- log_path
- exit_code
- warnings
- errors
- succeeded
Capture returns:
- command
- trace_path
- trace_exists
- trace_size
- pid or exit_code
Continuous capture status returns:
- pid
- running
- target_exe
- project_path
- trace_path
- trace_size
- started_at
Trace Store commands return:
- store_dir
- trace_count
- traces
- latest
Live commands return:
- pid
- live_command
- backend
- exit_code
- succeeded
Analyze summary returns:
- exports
- export_status
- summary.top_timers
- summary.focus_threads
- summary.wait_timers
- summary.counter_peaks
- summary.diagnostics
- summary.uncovered_domains

Treat output_status == "ok" as a materialized export. Treat
output_status == "no_output" as an empty trace/filter result, not a backend
crash. Use exporter_error, process_failed, and timed_out for retry or
debugging decisions.

Notes#

v1 is Windows-first.
v1 includes Trace Store browsing, GUI open/status, pluggable live command delivery,

and timing/counter summaries.

capture stop is a best-effort stop of the harness-launched process tree.
capture snapshot is a best-effort filesystem snapshot of the active trace.
Regression tests auto-discover the UE example_trace.decomp.utrace sample

when present; the binary trace is not vendored.