cli-anything-unrealinsights

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

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

Trace Store discovery

Capture orchestration

You can also keep using the explicit form:

Continuous capture session control

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

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

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

Offline exporters

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

Analyze summaries

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.