rdc-cli
Scriptable CLI for RenderDoc captures — built for terminal workflows, CI pipelines, and AI agents
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/bananasjim--rdc-cli)HTML
<a href="/listings/bananasjim--rdc-cli"><img src="/api/listings/bananasjim--rdc-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**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`
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 285 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ```
- _____ _____ _____
- | __ \| __ \ / ____|
- | |__) | | | | |
- | _ /| | | | |
- | | \ \| |__| | |____
- |_| \_\_____/ \_____| cli
- ```
- [](https://pypi.org/project/rdc-cli/)
- [](https://pypi.org/project/rdc-cli/)
- [](LICENSE)
- [](https://bananasjim.github.io/rdc-cli/)
- [](https://bananasjim.github.io/rdc-cli/)
- [](https://bananasjim.github.io/rdc-cli/)
- [](https://discord.gg/h3zwUadp4k)
- **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 →](https://bananasjim.github.io/rdc-cli/)**
- ```bash
- 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
- Requires Python 3.11 or newer. Starting with 0.7.0, rdc-cli requires Pillow 13
- for its security fixes. Python 3.10 users must upgrade Python; rebuild the
- RenderDoc Python module when changing Python minor versions.
- **PyPI — Linux** (recommended)
- ```bash
- 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)
- ```bash
- 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)
- ```bash
- uv tool install rdc-cli # or: pipx install rdc-cli
- rdc doctor
- ```
- **AUR** (Arch Linux — builds renderdoc automatically, no extra setup)
- ```bash
- yay -S rdc-cli-git # recommended: tracks latest master
- # or
- yay -S rdc-cli # stable: tracks tagged releases
- ```
- **From source**
- ```bash
- 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:
- ```bash
- rdc setup-renderdoc
- ```
- If building from source, use the pixi wrapper instead: `pixi run setup-renderdoc`
- ## Quickstart
- **Explore a capture like a filesystem:**
- ```bash
- 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:**
- ```bash
- 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:**
- ```bash
- rdc texture 5 -o albedo.png # export a texture
- rdc rt 142 -o render.png # export render target
- rdc rt 142 --depth -o depth.png # export raw depth attachment
- rdc buffer 88 -o verts.bin # export raw buffer
- rdc cbuffer 142 --stage ps --binding 0 # decode a constant buffer to JSON
- rdc snapshot 142 -o ./snap/ # pipeline + shaders + render targets
- rdc draws --json | jq '.[] | select(.triangles > 10000)' # filter with jq
- ```
- **CI assertions:**
- ```bash
- 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:**
- ```bash
- 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** |
- ```bash
- # Multi-GPU host: force the replay GPU (0-based index, name, or device ID)
- rdc open frame.rdc --gpu 1
- # 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**
- ```bash
- 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:
- ```bash
- 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](https://bananasjim.github.io/rdc-cli/) 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](https://bananasjim.github.io/rdc-cli/docs/commands/) 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`, `cbuffer`, `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`, `remote setup`, `remote status`, `remote disconnect` |
- | 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:
- ```bash
- rdc completion bash > ~/.local/share/bash-completion/completions/rdc
- rdc completion zsh > ~/.zfunc/_rdc
- rdc completion fish > ~/.config/fish/completions/rdc.fish
- ```
- ## Development
- ```bash
- 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:
- ```bash
- 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](CONTRIBUTING.md) for guidelines.
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.