rdc-cli 0.5.5

CLI for RenderDoc .rdc captures

 _____  _____   _____
|  __ \|  __ \ / ____|
| |__) | |  | | |
|  _  /| |  | | |
| | \ \| |__| | |____
|_|  \_\_____/ \_____|  cli

Turn RenderDoc captures into Unix text streams. rdc-cli does not replace RenderDoc — it makes .rdc file contents accessible to grep, awk, sort, diff, jq, and AI agents.

Full documentation →

rdc open scene.rdc
rdc draws | grep Shadow | sort -t$'\t' -k3 -rn | head -5   # top 5 shadow draws by tri count
rdc shader 142 ps | grep shadowMap                           # find shadow sampling in PS
rdc cat /draws/142/shader/ps/constants                       # inspect bound constants
rdc diff before.rdc after.rdc --draws | grep '~'             # what changed between two frames?
rdc close

Install

PyPI — Linux (recommended)

uv tool install rdc-cli               # or: pipx install rdc-cli
rdc setup-renderdoc                   # build renderdoc Python module from source
rdc doctor                            # verify everything works

PyPI — Windows (requires git, uv, Visual Studio Build Tools)

uv tool install rdc-cli               # or: pipx install rdc-cli
rdc setup-renderdoc                   # build renderdoc Python module from source
rdc doctor                            # verify everything works

PyPI — macOS (Split client only)

uv tool install rdc-cli               # or: pipx install rdc-cli
rdc doctor

AUR (Arch Linux — builds renderdoc automatically, no extra setup)

yay -S rdc-cli-git    # recommended: tracks latest master
# or
yay -S rdc-cli        # stable: tracks tagged releases

From source

git clone https://github.com/BANANASJIM/rdc-cli.git
cd rdc-cli
pixi install && pixi run sync
pixi run install                      # editable install + shell completions
pixi run setup-renderdoc              # build renderdoc (pixi installs toolchain on macOS)

Platform Support Matrix

Platform	Local capture/replay	Split client	Remote capture
Linux	✅	✅	✅
macOS	❌ (not supported yet)	✅ (recommended)	—
Windows	✅	✅	✅
Android	—	—	✅ capture + remote replay

RenderDoc bootstrap

After installing rdc-cli, build the renderdoc Python module:

rdc setup-renderdoc

If building from source, use the pixi wrapper instead: pixi run setup-renderdoc

Quickstart

Explore a capture like a filesystem:

rdc ls /                              # top-level: draws, passes, resources, shaders, ...
rdc ls /draws/142                     # what's inside this draw call?
rdc cat /draws/142/pipeline/blend      # color blend state
rdc tree /passes --depth 2            # pass structure at a glance

Shader debugging — no GUI needed:

rdc shader 142 ps                     # pixel shader disassembly
rdc shader 142 ps --constants         # current constant buffer values
rdc debug pixel 142 400 300 --trace   # step-by-step PS execution trace
rdc search "shadowMap"                # grep across all shaders in the frame

Export and scripting:

rdc texture 5 -o albedo.png           # export a texture
rdc rt 142 -o render.png              # export render target
rdc buffer 88 -o verts.bin            # export raw buffer
rdc snapshot 142 -o ./snap/           # pipeline + shaders + render targets
rdc draws --json | jq '.[] | select(.triangles > 10000)'  # filter with jq

CI assertions:

rdc open frame.rdc
rdc assert-pixel 142 400 300 --expect "0.5 0.0 0.0 1.0" --tolerance 0.01
rdc assert-state 142 topology --expect TriangleList
rdc assert-image golden.png actual.png --threshold 0.001
rdc assert-clean --min-severity HIGH
rdc close

Two-frame diff:

rdc diff before.rdc after.rdc --shortstat        # summary: draws ±N, resources ±N
rdc diff before.rdc after.rdc --draws             # per-draw changes
rdc diff before.rdc after.rdc --framebuffer       # pixel-level image diff

Remote replay and Split mode

rdc-cli supports three deployment modes:

Mode	Daemon runs on	GPU access	Client needs renderdoc?
Local	client	local GPU	yes
Proxy (--proxy)	client	remote renderdoccmd server	yes
Split (--listen/--connect)	server	server-local GPU	no

# Proxy: local daemon, remote GPU (needs renderdoccmd on remote)
rdc open frame.rdc --proxy gpu-server:39920

# Split server: bind to a specific LAN interface
rdc open frame.rdc --listen 192.168.1.10:54321

# Split client: connect from any machine (no renderdoc needed)
rdc open --connect replay-host:54321 --token TOKEN
rdc draws                          # all commands work transparently
rdc close

Split mode is recommended for cross-platform use. All commands work transparently regardless of mode.

Android capture and remote replay

rdc setup-renderdoc --android            # download RenderDoc APKs for Android
rdc android setup                        # start remote server on connected device
rdc android capture com.app/.MainActivity -o frame.rdc   # capture via GPU debug layers

# Remote replay on the device GPU
rdc open frame.rdc --android             # auto-resolves device from saved state
rdc draws                                # all commands work transparently
rdc pick-pixel 540 1170 --json           # pixel queries work in remote mode
rdc close

rdc android stop                         # stop remote server

Android capture uses GPU debug layers (Android 10+). Remote replay uploads the capture back to the device for replay on the original GPU. Tested on Adreno and Mali (EMUI) devices. For Mali GPUs, ARM Performance Studio is recommended:

rdc setup-renderdoc --android --arm-studio /path/to/arm-performance-studio

Why rdc-cli?

RenderDoc is excellent at capturing GPU frames and replaying them interactively. But its GUI doesn't compose — you can't pipe a draw call list into sort, diff two captures in CI, or let an AI agent inspect shader state.

rdc-cli bridges that gap:

• TSV by default — every command outputs tab-separated text that pipes directly into Unix tools. Raw numbers, not human-friendly formatting.
• VFS path namespace — GPU state is navigable like a filesystem: /draws/142/shader/ps, /passes/GBuffer/draws, /resources/88. Explore with ls, read with cat.
• Daemon architecture — load the capture once, then query as many times as you want. No per-command startup cost.
• Built for CI — assert-pixel, assert-state, assert-image, assert-count, assert-clean with diff(1)-compatible exit codes (0=pass, 1=fail, 2=error).
• AI-agent friendly — structured output (--json, --jsonl), deterministic VFS paths, and a Claude Code skill for automated GPU frame analysis.
• Escape hatch — rdc script runs arbitrary Python inside the daemon with full access to the renderdoc module, for anything the CLI doesn't cover yet.

Commands

Run rdc --help for the full list, or rdc <command> --help for details. See the full command reference for every option.

Category	Commands
Session	open, close, status, goto
Inspection	info, stats, events, draws, event, draw, log
GPU state	pipeline, bindings, shader, shaders, shader-map
Debug	debug pixel, debug vertex, debug thread, pixel, pick-pixel, tex-stats
Shader edit	shader-build, shader-replace, shader-restore, shader-restore-all, shader-encodings
Resources	resources, resource, passes, pass, usage, unused-targets
Export	texture, rt, buffer, mesh, snapshot
Search	search, counters
Assertions	assert-pixel, assert-state, assert-image, assert-count, assert-clean
Diff	diff (with --draws, --stats, --framebuffer, --pipeline, etc.)
VFS	ls, cat, tree
Remote	remote connect, remote list, remote capture
Android	android setup, android stop, android capture
Target control	attach, capture-trigger, capture-list, capture-copy
Capture file	sections, section, callstacks, gpus, thumbnail
Utility	doctor, completion, capture, count, script, serve, setup-renderdoc, install-skill

All list commands output TSV. All commands support --json. Footer/summary goes to stderr — stdout is always clean data.

Common options

Options available on most list/query commands (not every command supports all):

--json           JSON output (all commands)
--jsonl          streaming JSON, one object per line (list commands)
--no-header      drop TSV header for awk/cut (list commands)
-q / --quiet     IDs only for xargs (list commands)
--sort <field>   sort by field (draws, resources, shaders)
--limit <N>      truncate rows (events, search)
--filter <pat>   name glob filter (events)
-o <path>        output to file (export commands)

Shell completions

Completions are installed automatically by pixi run install. To install manually:

rdc completion bash > ~/.local/share/bash-completion/completions/rdc
rdc completion zsh  > ~/.zfunc/_rdc
rdc completion fish > ~/.config/fish/completions/rdc.fish

Development

pixi run sync                 # install deps + git hooks + renderdoc symlink
pixi run install              # editable install + shell completions
pixi run check                # lint + typecheck + test
pixi run verify               # full packaging verification

GPU integration tests require a real renderdoc module:

export RENDERDOC_PYTHON_PATH=/path/to/renderdoc/build/lib
pixi run test-gpu             # unit tests marked @gpu
pixi run e2e                  # cross-platform smoke test (26 checks)
pixi run test-e2e             # full e2e suite (self-capture + dynamic discovery)

Contributing

Bug reports, feature requests, and pull requests are welcome! See CONTRIBUTING.md for guidelines.

License

MIT