📘 Khy-OS 文档站 🧭 新手先读：核心概念

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