/cli-anything-unrealinsights

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.wai