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: 14 days 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 (28 days ago)
- Default Branch: master
- Last Pushed: 2026-02-24T06:05:06.000Z (23 days ago)
- Last Synced: 2026-02-24T06:19:22.023Z (23 days 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/)
**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** (recommended — any Linux distro)
```bash
pipx install rdc-cli # install the CLI
# Build the renderdoc Python module (one-time, ~3 min, needs cmake + ninja)
curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/build-renderdoc.sh | bash
rdc doctor # verify everything works
```
**AUR** (Arch Linux — builds renderdoc automatically, no extra setup)
```bash
yay -S rdc-cli # stable: tracks tagged releases
yay -S rdc-cli-git # git: tracks latest master
```
**From source**
```bash
git clone https://github.com/BANANASJIM/rdc-cli.git
cd rdc-cli
pixi install && pixi run sync
```
## 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/om # output merger 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(.tri_count > 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
```
## 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 (use `--table` for that).
- **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/cli-reference/rdc/) 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` |
| 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` |
| Utility | `doctor`, `completion`, `capture`, `count`, `script`, `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 (events, resources, shaders)
--limit truncate rows (events, search)
--filter name glob filter (events)
-o output to file (export commands)
```
### Shell completions
```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 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
```
## License
[MIT](LICENSE)