name: "cli-anything-nsight-graphics"
description: Windows-first CLI harness for Nsight Graphics capture, GPU Trace summary, and ngfx-replay analysis
version: 0.2.0
command: cli-anything-nsight-graphics
install: pip install cli-anything-nsight-graphics
requires:

• NVIDIA Nsight Graphics installation
• Windows host recommended

categories:

• graphics
• debugging
• gpu
• profiling

Nsight Graphics CLI Skill#

Command-line orchestration of official NVIDIA Nsight Graphics activities.

Capabilities#

• Probe installed Nsight binaries and compatibility mode
• Launch an application detached under Nsight
• Attach Nsight to a running PID
• Trigger Graphics Capture or OpenGL Frame Debugger capture
• Trigger GPU Trace capture, auto-export, and summarize
• Analyze existing .ngfx-capture files through ngfx-replay
• Report clear compatibility diagnostics for .ngfx-gputrace inputs
• Trigger Generate C++ Capture

Commands#

doctor#

cli-anything-nsight-graphics --json doctor info
cli-anything-nsight-graphics --json doctor versions
cli-anything-nsight-graphics --nsight-path "C:\Path\To\Nsight Graphics 2024.2\host\windows-desktop-nomad-x64" --json doctor info

launch#

cli-anything-nsight-graphics launch detached --activity "Graphics Capture" --exe "C:\Path\To\App.exe"
cli-anything-nsight-graphics launch attach --activity "Graphics Capture" --pid 12345

frame capture#

cli-anything-nsight-graphics --output-dir D:\captures frame capture ^
  --exe "C:\Path\To\App.exe" ^
  --wait-frames 10

GPU Trace#

cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture ^
  --exe "C:\Path\To\App.exe" ^
  --start-after-ms 1000 ^
  --limit-to-frames 1 ^
  --auto-export ^
  --summarize

cli-anything-nsight-graphics gpu-trace summarize ^
  --input-dir D:\traces

Replay analysis#

cli-anything-nsight-graphics --json replay analyze ^
  --capture-file D:\captures\frame.ngfx-capture ^
  --output-dir D:\analysis

Generate C++ Capture#

cli-anything-nsight-graphics --output-dir D:\cpp cpp capture ^
  --exe "C:\Path\To\App.exe" ^
  --wait-seconds 5

Agent Notes#

• Prefer doctor info first to discover the available compatibility mode.
• Use doctor versions to list detected installs when multiple Nsight Graphics versions exist.
• Use --nsight-path to force a specific install directory or ngfx.exe.
• Use --json for programmatic workflows.
• Prefer gpu-trace capture --auto-export --summarize for one-step performance

triage. The summary includes exported table inventory, metric inventory,
frame-budget classification, workload classification, throughput ranking,
bottleneck hints, and warnings for empty event/regime tables.

• Use replay analyze when the input is an existing .ngfx-capture file. With

no analysis switches it exports metadata, logs, captured log errors, and a
replay performance report, then adds structured analysis.highlights /
analysis.warnings.

• ngfx-replay documents its input as a Graphics Capture file. .ngfx-gputrace

inputs are accepted for clear diagnostics, but on Nsight Graphics 2026.1.0
they may report Invalid file header; use gpu-trace summarize for exported
GPU Trace table analysis.

• replay analyze uses official ngfx-replay metadata/log/screenshot/perf-report

outputs; it is not a RenderDoc-style shader, pipeline, texture, or resource inspector.

• Frame/GPU/C++ capture commands require a launch target through --exe or a

preconfigured root-level --project.

• If a global cli-anything-nsight-graphics command points at an old worktree,

reinstall from nsight-graphics/agent-harness with python -m pip install -e ..