cli-anything-unrealinsights

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cli-anything-unrealinsights

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

当你需要在Windows系统上通过Agent友好的方式访问Unreal Insights追踪捕获与导出工作流时，可以使用此CLI工具。

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
```

Windows系统
已安装包含
```
UnrealInsights.exe
```
的Unreal Engine工具
已在UE 5.5版本下验证；无头时序导出器尽可能兼容UE 5.3风格的命令解析

可选的显式环境变量：

```
UNREALINSIGHTS_EXE
```
```
UNREAL_TRACE_SERVER_EXE
```
```
UNREALINSIGHTS_TRACE
```

Core Commands

核心命令

Backend discovery

后端发现

powershell

cli-anything-unrealinsights --json backend info

To use a source-built engine's matching

UnrealInsights.exe

powershell

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.

powershell

cli-anything-unrealinsights --json backend info

要使用源码构建引擎对应的

UnrealInsights.exe

：

powershell

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

该命令会先在指定引擎根目录下查找

Engine\Binaries\Win64\UnrealInsights.exe

，如果不存在，则使用该引擎的

Build.bat

进行构建。

Trace session state

追踪会话状态

powershell

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

powershell

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

Trace Store discovery

Trace Store发现

powershell

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

powershell

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

Capture orchestration

捕获编排

powershell

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:

powershell

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'

powershell

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

你也可以使用显式形式：

powershell

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

持续捕获会话控制

powershell

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.

powershell

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

当Agent需要立即开始性能分析，并在后续步骤中停止或生成快照时，此流程为首选方案。

如果已追踪的捕获会话仍在运行，

capture start

命令现在需要添加

--replace

参数，以便在启动新进程前终止之前的进程。

Live trace control backend

实时追踪控制后端

powershell

$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

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

powershell

$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

实时命令交付需要配置

UNREALINSIGHTS_LIVE_EXEC

或

--backend-command

。如果未配置后端，实时命令会返回JSON格式的错误，不会返回成功状态。

live stop-trace

会停止追踪数据收集但不会终止UE进程；

capture stop

仍会终止由启动器启动的进程树。

GUI co-pilot

GUI辅助工具

powershell

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.

powershell

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命令会省略

-NoUI

和

-AutoQuit

参数，以保持Unreal Insights处于打开状态。

Offline exporters

离线导出器

powershell

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

powershell

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=*

建议使用等号形式的通配符过滤器，例如

--timers=*

和

--counter=*

。启动器会将简单值传递给UnrealInsights，不会添加内部引号，因此通配符在

-ExecOnAnalysisCompleteCmd

中仍可正常使用。

Batch response files

批量响应文件

powershell

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

powershell

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

Analyze summaries

分析汇总

powershell

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.

powershell

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

汇总报告包含顶级计时器、重点GameThread/RenderThread/RHIThread热点、等待/任务相关计时器、计数器峰值，以及未来可进行Memory/Network/Slate/Asset/Cooking分析的未覆盖领域。

analyze summary

还会返回

export_status

和

summary.diagnostics.export_status_counts

，以便Agent区分成功导出与完成但未生成任何行的追踪/过滤组合。

JSON Output Guidance

JSON输出指南

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.

Agent工作流建议使用
```
--json
```
参数。

导出命令返回以下内容：

```
trace_path
```
```
exec_command
```
```
output_files
```
```
output_status
```
```
status_message
```
```
log_path
```
```
exit_code
```
```
warnings
```
```
errors
```
```
succeeded
```

捕获命令返回以下内容：

```
command
```
```
trace_path
```
```
trace_exists
```
```
trace_size
```
```
pid
```
或
```
exit_code
```

持续捕获状态返回以下内容：

```
pid
```
```
running
```
```
target_exe
```
```
project_path
```
```
trace_path
```
```
trace_size
```
```
started_at
```

Trace Store命令返回以下内容：
- ```
store_dir
```
- ```
trace_count
```
- ```
traces
```
- ```
latest
```

实时命令返回以下内容：

```
pid
```
```
live_command
```
```
backend
```
```
exit_code
```
```
succeeded
```

分析汇总返回以下内容：

```
exports
```
```
export_status
```
```
summary.top_timers
```
```
summary.focus_threads
```
```
summary.wait_timers
```
```
summary.counter_peaks
```
```
summary.diagnostics
```
```
summary.uncovered_domains
```

将

output_status == "ok"

视为已完成的导出。将

output_status == "no_output"

视为空追踪/过滤结果，而非后端崩溃。使用

exporter_error

、

process_failed

和

timed_out

来决定是否重试或进行调试。

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.

v1版本优先支持Windows系统。
v1版本包含Trace Store浏览、GUI打开/状态查询、可插拔实时命令交付，以及时序/计数器汇总功能。
```
capture stop
```
会尽力终止由启动器启动的进程树。
```
capture snapshot
```
会尽力对活跃追踪数据进行文件系统快照。
当存在UE示例追踪文件
```
example_trace.decomp.utrace
```
时，回归测试会自动发现该文件；二进制追踪文件未被包含在内。