https://github.com/bananasjim/rdc-cli
Scriptable CLI for RenderDoc captures — built for terminal workflows, CI pipelines, and AI agents
https://github.com/bananasjim/rdc-cli
cli frame-analysis gpu gpu-capture graphics-debugging linux opengl python renderdoc renderdoc-api shader-debugging vulkan
Last synced: about 2 months ago
JSON representation
Scriptable CLI for RenderDoc captures — built for terminal workflows, CI pipelines, and AI agents
- Host: GitHub
- URL: https://github.com/bananasjim/rdc-cli
- Owner: BANANASJIM
- License: mit
- Created: 2026-02-18T21:29:05.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-02-24T06:05:06.000Z (3 months ago)
- Last Synced: 2026-02-24T06:19:22.023Z (3 months ago)
- Topics: cli, frame-analysis, gpu, gpu-capture, graphics-debugging, linux, opengl, python, renderdoc, renderdoc-api, shader-debugging, vulkan
- Language: Python
- Homepage: https://bananasjim.github.io/rdc-cli/
- Size: 1.45 MB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
```
_____ _____ _____
| __ \| __ \ / ____|
| |__) | | | | |
| _ /| | | | |
| | \ \| |__| | |____
|_| \_\_____/ \_____| 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
**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 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:**
```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
# 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 --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`, `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 sort by field (draws, resources, shaders)
--limit truncate rows (events, search)
--filter name glob filter (events)
-o 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)