Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bananasjim--rdc-cli/badge.svg)](/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

i

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.

  1. ```
  2. _____ _____ _____
  3. | __ \| __ \ / ____|
  4. | |__) | | | | |
  5. | _ /| | | | |
  6. | | \ \| |__| | |____
  7. |_| \_\_____/ \_____| cli
  8. ```
  9. [![PyPI](https://img.shields.io/pypi/v/rdc-cli)](https://pypi.org/project/rdc-cli/)
  10. [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/rdc-cli/)
  11. [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  12. [![Commands](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/commands.json)](https://bananasjim.github.io/rdc-cli/)
  13. [![Tests](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/tests.json)](https://bananasjim.github.io/rdc-cli/)
  14. [![Coverage](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/coverage.json)](https://bananasjim.github.io/rdc-cli/)
  15. [![Discord](https://img.shields.io/discord/1485003415687008296?logo=discord&label=Discord)](https://discord.gg/h3zwUadp4k)
  16. **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.
  17. **[Full documentation →](https://bananasjim.github.io/rdc-cli/)**
  18. ```bash
  19. rdc open scene.rdc
  20. rdc draws | grep Shadow | sort -t$'\t' -k3 -rn | head -5 # top 5 shadow draws by tri count
  21. rdc shader 142 ps | grep shadowMap # find shadow sampling in PS
  22. rdc cat /draws/142/shader/ps/constants # inspect bound constants
  23. rdc diff before.rdc after.rdc --draws | grep '~' # what changed between two frames?
  24. rdc close
  25. ```
  26. ## Install
  27. Requires Python 3.11 or newer. Starting with 0.7.0, rdc-cli requires Pillow 13
  28. for its security fixes. Python 3.10 users must upgrade Python; rebuild the
  29. RenderDoc Python module when changing Python minor versions.
  30. **PyPI — Linux** (recommended)
  31. ```bash
  32. uv tool install rdc-cli # or: pipx install rdc-cli
  33. rdc setup-renderdoc # build renderdoc Python module from source
  34. rdc doctor # verify everything works
  35. ```
  36. **PyPI — Windows** (requires git, uv, Visual Studio Build Tools)
  37. ```bash
  38. uv tool install rdc-cli # or: pipx install rdc-cli
  39. rdc setup-renderdoc # build renderdoc Python module from source
  40. rdc doctor # verify everything works
  41. ```
  42. **PyPI — macOS** (Split client only)
  43. ```bash
  44. uv tool install rdc-cli # or: pipx install rdc-cli
  45. rdc doctor
  46. ```
  47. **AUR** (Arch Linux — builds renderdoc automatically, no extra setup)
  48. ```bash
  49. yay -S rdc-cli-git # recommended: tracks latest master
  50. # or
  51. yay -S rdc-cli # stable: tracks tagged releases
  52. ```
  53. **From source**
  54. ```bash
  55. git clone https://github.com/BANANASJIM/rdc-cli.git
  56. cd rdc-cli
  57. pixi install && pixi run sync
  58. pixi run install # editable install + shell completions
  59. pixi run setup-renderdoc # build renderdoc (pixi installs toolchain on macOS)
  60. ```
  61. ### Platform Support Matrix
  62. | Platform | Local capture/replay | Split client | Remote capture |
  63. |----------|----------------------|--------------|----------------|
  64. | Linux | ✅ | ✅ | ✅ |
  65. | macOS | ❌ (not supported yet) | ✅ (recommended) | — |
  66. | Windows | ✅ | ✅ | ✅ |
  67. | Android | — | — | ✅ capture + remote replay |
  68. ### RenderDoc bootstrap
  69. After installing rdc-cli, build the renderdoc Python module:
  70. ```bash
  71. rdc setup-renderdoc
  72. ```
  73. If building from source, use the pixi wrapper instead: `pixi run setup-renderdoc`
  74. ## Quickstart
  75. **Explore a capture like a filesystem:**
  76. ```bash
  77. rdc ls / # top-level: draws, passes, resources, shaders, ...
  78. rdc ls /draws/142 # what's inside this draw call?
  79. rdc cat /draws/142/pipeline/blend # color blend state
  80. rdc tree /passes --depth 2 # pass structure at a glance
  81. ```
  82. **Shader debugging — no GUI needed:**
  83. ```bash
  84. rdc shader 142 ps # pixel shader disassembly
  85. rdc shader 142 ps --constants # current constant buffer values
  86. rdc debug pixel 142 400 300 --trace # step-by-step PS execution trace
  87. rdc search "shadowMap" # grep across all shaders in the frame
  88. ```
  89. **Export and scripting:**
  90. ```bash
  91. rdc texture 5 -o albedo.png # export a texture
  92. rdc rt 142 -o render.png # export render target
  93. rdc rt 142 --depth -o depth.png # export raw depth attachment
  94. rdc buffer 88 -o verts.bin # export raw buffer
  95. rdc cbuffer 142 --stage ps --binding 0 # decode a constant buffer to JSON
  96. rdc snapshot 142 -o ./snap/ # pipeline + shaders + render targets
  97. rdc draws --json | jq '.[] | select(.triangles > 10000)' # filter with jq
  98. ```
  99. **CI assertions:**
  100. ```bash
  101. rdc open frame.rdc
  102. rdc assert-pixel 142 400 300 --expect "0.5 0.0 0.0 1.0" --tolerance 0.01
  103. rdc assert-state 142 topology --expect TriangleList
  104. rdc assert-image golden.png actual.png --threshold 0.001
  105. rdc assert-clean --min-severity HIGH
  106. rdc close
  107. ```
  108. **Two-frame diff:**
  109. ```bash
  110. rdc diff before.rdc after.rdc --shortstat # summary: draws ±N, resources ±N
  111. rdc diff before.rdc after.rdc --draws # per-draw changes
  112. rdc diff before.rdc after.rdc --framebuffer # pixel-level image diff
  113. ```
  114. **Remote replay and Split mode**
  115. rdc-cli supports three deployment modes:
  116. | Mode | Daemon runs on | GPU access | Client needs renderdoc? |
  117. |------|---------------|------------|------------------------|
  118. | **Local** | client | local GPU | yes |
  119. | **Proxy** (`--proxy`) | client | remote `renderdoccmd` server | yes |
  120. | **Split** (`--listen`/`--connect`) | server | server-local GPU | **no** |
  121. ```bash
  122. # Multi-GPU host: force the replay GPU (0-based index, name, or device ID)
  123. rdc open frame.rdc --gpu 1
  124. # Proxy: local daemon, remote GPU (needs renderdoccmd on remote)
  125. rdc open frame.rdc --proxy gpu-server:39920
  126. # Split server: bind to a specific LAN interface
  127. rdc open frame.rdc --listen 192.168.1.10:54321
  128. # Split client: connect from any machine (no renderdoc needed)
  129. rdc open --connect replay-host:54321 --token TOKEN
  130. rdc draws # all commands work transparently
  131. rdc close
  132. ```
  133. Split mode is recommended for cross-platform use. All commands work transparently regardless of mode.
  134. **Android capture and remote replay**
  135. ```bash
  136. rdc setup-renderdoc --android # download RenderDoc APKs for Android
  137. rdc android setup # start remote server on connected device
  138. rdc android capture com.app/.MainActivity -o frame.rdc # capture via GPU debug layers
  139. # Remote replay on the device GPU
  140. rdc open frame.rdc --android # auto-resolves device from saved state
  141. rdc draws # all commands work transparently
  142. rdc pick-pixel 540 1170 --json # pixel queries work in remote mode
  143. rdc close
  144. rdc android stop # stop remote server
  145. ```
  146. 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:
  147. ```bash
  148. rdc setup-renderdoc --android --arm-studio /path/to/arm-performance-studio
  149. ```
  150. ## Why rdc-cli?
  151. 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.
  152. rdc-cli bridges that gap:
  153. - **TSV by default** — every command outputs tab-separated text that pipes directly into Unix tools. Raw numbers, not human-friendly formatting.
  154. - **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`.
  155. - **Daemon architecture** — load the capture once, then query as many times as you want. No per-command startup cost.
  156. - **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).
  157. - **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.
  158. - **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.
  159. ## Commands
  160. 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.
  161. | Category | Commands |
  162. |----------|----------|
  163. | Session | `open`, `close`, `status`, `goto` |
  164. | Inspection | `info`, `stats`, `events`, `draws`, `event`, `draw`, `log` |
  165. | GPU state | `pipeline`, `bindings`, `shader`, `shaders`, `shader-map` |
  166. | Debug | `debug pixel`, `debug vertex`, `debug thread`, `pixel`, `pick-pixel`, `tex-stats` |
  167. | Shader edit | `shader-build`, `shader-replace`, `shader-restore`, `shader-restore-all`, `shader-encodings` |
  168. | Resources | `resources`, `resource`, `passes`, `pass`, `usage`, `unused-targets` |
  169. | Export | `texture`, `rt`, `buffer`, `cbuffer`, `mesh`, `snapshot` |
  170. | Search | `search`, `counters` |
  171. | Assertions | `assert-pixel`, `assert-state`, `assert-image`, `assert-count`, `assert-clean` |
  172. | Diff | `diff` (with `--draws`, `--stats`, `--framebuffer`, `--pipeline`, etc.) |
  173. | VFS | `ls`, `cat`, `tree` |
  174. | Remote | `remote connect`, `remote list`, `remote capture`, `remote setup`, `remote status`, `remote disconnect` |
  175. | Android | `android setup`, `android stop`, `android capture` |
  176. | Target control | `attach`, `capture-trigger`, `capture-list`, `capture-copy` |
  177. | Capture file | `sections`, `section`, `callstacks`, `gpus`, `thumbnail` |
  178. | Utility | `doctor`, `completion`, `capture`, `count`, `script`, `serve`, `setup-renderdoc`, `install-skill` |
  179. All list commands output TSV. All commands support `--json`. Footer/summary goes to stderr — stdout is always clean data.
  180. ### Common options
  181. Options available on most list/query commands (not every command supports all):
  182. ```
  183. --json JSON output (all commands)
  184. --jsonl streaming JSON, one object per line (list commands)
  185. --no-header drop TSV header for awk/cut (list commands)
  186. -q / --quiet IDs only for xargs (list commands)
  187. --sort <field> sort by field (draws, resources, shaders)
  188. --limit <N> truncate rows (events, search)
  189. --filter <pat> name glob filter (events)
  190. -o <path> output to file (export commands)
  191. ```
  192. ### Shell completions
  193. Completions are installed automatically by `pixi run install`. To install manually:
  194. ```bash
  195. rdc completion bash > ~/.local/share/bash-completion/completions/rdc
  196. rdc completion zsh > ~/.zfunc/_rdc
  197. rdc completion fish > ~/.config/fish/completions/rdc.fish
  198. ```
  199. ## Development
  200. ```bash
  201. pixi run sync # install deps + git hooks + renderdoc symlink
  202. pixi run install # editable install + shell completions
  203. pixi run check # lint + typecheck + test
  204. pixi run verify # full packaging verification
  205. ```
  206. GPU integration tests require a real renderdoc module:
  207. ```bash
  208. export RENDERDOC_PYTHON_PATH=/path/to/renderdoc/build/lib
  209. pixi run test-gpu # unit tests marked @gpu
  210. pixi run e2e # cross-platform smoke test (26 checks)
  211. pixi run test-e2e # full e2e suite (self-capture + dynamic discovery)
  212. ```
  213. ## Contributing
  214. Bug reports, feature requests, and pull requests are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  215. ## License
  216. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.