{"id":45634497,"url":"https://github.com/bananasjim/rdc-cli","last_synced_at":"2026-04-01T22:44:55.859Z","repository":{"id":340096549,"uuid":"1161215057","full_name":"BANANASJIM/rdc-cli","owner":"BANANASJIM","description":"Scriptable CLI for RenderDoc captures — built for terminal workflows, CI pipelines, and AI agents","archived":false,"fork":false,"pushed_at":"2026-02-24T06:05:06.000Z","size":1524,"stargazers_count":7,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-24T06:19:22.023Z","etag":null,"topics":["cli","frame-analysis","gpu","gpu-capture","graphics-debugging","linux","opengl","python","renderdoc","renderdoc-api","shader-debugging","vulkan"],"latest_commit_sha":null,"homepage":"https://bananasjim.github.io/rdc-cli/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BANANASJIM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-18T21:29:05.000Z","updated_at":"2026-02-24T06:05:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"ee18014e-6d7d-40b6-b08d-772ce2b45cdc","html_url":"https://github.com/BANANASJIM/rdc-cli","commit_stats":null,"previous_names":["bananasjim/rdc-cli"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/BANANASJIM/rdc-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BANANASJIM%2Frdc-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BANANASJIM%2Frdc-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BANANASJIM%2Frdc-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BANANASJIM%2Frdc-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BANANASJIM","download_url":"https://codeload.github.com/BANANASJIM/rdc-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BANANASJIM%2Frdc-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29808860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T22:43:48.403Z","status":"online","status_checked_at":"2026-02-25T02:00:07.329Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","frame-analysis","gpu","gpu-capture","graphics-debugging","linux","opengl","python","renderdoc","renderdoc-api","shader-debugging","vulkan"],"created_at":"2026-02-24T01:35:37.815Z","updated_at":"2026-04-01T22:44:55.839Z","avatar_url":"https://github.com/BANANASJIM.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n _____  _____   _____\n|  __ \\|  __ \\ / ____|\n| |__) | |  | | |\n|  _  /| |  | | |\n| | \\ \\| |__| | |____\n|_|  \\_\\_____/ \\_____|  cli\n```\n\n[![PyPI](https://img.shields.io/pypi/v/rdc-cli)](https://pypi.org/project/rdc-cli/)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/rdc-cli/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Commands](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/commands.json)](https://bananasjim.github.io/rdc-cli/)\n[![Tests](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/tests.json)](https://bananasjim.github.io/rdc-cli/)\n[![Coverage](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/coverage.json)](https://bananasjim.github.io/rdc-cli/)\n[![Discord](https://img.shields.io/discord/1485003415687008296?logo=discord\u0026label=Discord)](https://discord.gg/h3zwUadp4k)\n\n**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.\n\n**[Full documentation →](https://bananasjim.github.io/rdc-cli/)**\n\n```bash\nrdc open scene.rdc\nrdc draws | grep Shadow | sort -t$'\\t' -k3 -rn | head -5   # top 5 shadow draws by tri count\nrdc shader 142 ps | grep shadowMap                           # find shadow sampling in PS\nrdc cat /draws/142/shader/ps/constants                       # inspect bound constants\nrdc diff before.rdc after.rdc --draws | grep '~'             # what changed between two frames?\nrdc close\n```\n\n## Install\n\n**PyPI — Linux** (recommended)\n\n```bash\nuv tool install rdc-cli               # or: pipx install rdc-cli\nrdc setup-renderdoc                   # build renderdoc Python module from source\nrdc doctor                            # verify everything works\n```\n\n**PyPI — Windows** (requires git, uv, Visual Studio Build Tools)\n\n```bash\nuv tool install rdc-cli               # or: pipx install rdc-cli\nrdc setup-renderdoc                   # build renderdoc Python module from source\nrdc doctor                            # verify everything works\n```\n\n**PyPI — macOS** (Split client only)\n\n```bash\nuv tool install rdc-cli               # or: pipx install rdc-cli\nrdc doctor\n```\n\n**AUR** (Arch Linux — builds renderdoc automatically, no extra setup)\n\n```bash\nyay -S rdc-cli-git    # recommended: tracks latest master\n# or\nyay -S rdc-cli        # stable: tracks tagged releases\n```\n\n**From source**\n\n```bash\ngit clone https://github.com/BANANASJIM/rdc-cli.git\ncd rdc-cli\npixi install \u0026\u0026 pixi run sync\npixi run install                      # editable install + shell completions\npixi run setup-renderdoc              # build renderdoc (pixi installs toolchain on macOS)\n```\n\n### Platform Support Matrix\n\n| Platform | Local capture/replay | Split client | Remote capture |\n|----------|----------------------|--------------|----------------|\n| Linux | ✅ | ✅ | ✅ |\n| macOS | ❌ (not supported yet) | ✅ (recommended) | — |\n| Windows | ✅ | ✅ | ✅ |\n| Android | — | — | ✅ capture + remote replay |\n\n### RenderDoc bootstrap\n\nAfter installing rdc-cli, build the renderdoc Python module:\n\n```bash\nrdc setup-renderdoc\n```\n\nIf building from source, use the pixi wrapper instead: `pixi run setup-renderdoc`\n\n## Quickstart\n\n**Explore a capture like a filesystem:**\n\n```bash\nrdc ls /                              # top-level: draws, passes, resources, shaders, ...\nrdc ls /draws/142                     # what's inside this draw call?\nrdc cat /draws/142/pipeline/blend      # color blend state\nrdc tree /passes --depth 2            # pass structure at a glance\n```\n\n**Shader debugging — no GUI needed:**\n\n```bash\nrdc shader 142 ps                     # pixel shader disassembly\nrdc shader 142 ps --constants         # current constant buffer values\nrdc debug pixel 142 400 300 --trace   # step-by-step PS execution trace\nrdc search \"shadowMap\"                # grep across all shaders in the frame\n```\n\n**Export and scripting:**\n\n```bash\nrdc texture 5 -o albedo.png           # export a texture\nrdc rt 142 -o render.png              # export render target\nrdc buffer 88 -o verts.bin            # export raw buffer\nrdc snapshot 142 -o ./snap/           # pipeline + shaders + render targets\nrdc draws --json | jq '.[] | select(.triangles \u003e 10000)'  # filter with jq\n```\n\n**CI assertions:**\n\n```bash\nrdc open frame.rdc\nrdc assert-pixel 142 400 300 --expect \"0.5 0.0 0.0 1.0\" --tolerance 0.01\nrdc assert-state 142 topology --expect TriangleList\nrdc assert-image golden.png actual.png --threshold 0.001\nrdc assert-clean --min-severity HIGH\nrdc close\n```\n\n**Two-frame diff:**\n\n```bash\nrdc diff before.rdc after.rdc --shortstat        # summary: draws ±N, resources ±N\nrdc diff before.rdc after.rdc --draws             # per-draw changes\nrdc diff before.rdc after.rdc --framebuffer       # pixel-level image diff\n```\n\n**Remote replay and Split mode**\n\nrdc-cli supports three deployment modes:\n\n| Mode | Daemon runs on | GPU access | Client needs renderdoc? |\n|------|---------------|------------|------------------------|\n| **Local** | client | local GPU | yes |\n| **Proxy** (`--proxy`) | client | remote `renderdoccmd` server | yes |\n| **Split** (`--listen`/`--connect`) | server | server-local GPU | **no** |\n\n```bash\n# Proxy: local daemon, remote GPU (needs renderdoccmd on remote)\nrdc open frame.rdc --proxy gpu-server:39920\n\n# Split server: bind to a specific LAN interface\nrdc open frame.rdc --listen 192.168.1.10:54321\n\n# Split client: connect from any machine (no renderdoc needed)\nrdc open --connect replay-host:54321 --token TOKEN\nrdc draws                          # all commands work transparently\nrdc close\n```\n\nSplit mode is recommended for cross-platform use. All commands work transparently regardless of mode.\n\n**Android capture and remote replay**\n\n```bash\nrdc setup-renderdoc --android            # download RenderDoc APKs for Android\nrdc android setup                        # start remote server on connected device\nrdc android capture com.app/.MainActivity -o frame.rdc   # capture via GPU debug layers\n\n# Remote replay on the device GPU\nrdc open frame.rdc --android             # auto-resolves device from saved state\nrdc draws                                # all commands work transparently\nrdc pick-pixel 540 1170 --json           # pixel queries work in remote mode\nrdc close\n\nrdc android stop                         # stop remote server\n```\n\nAndroid 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:\n\n```bash\nrdc setup-renderdoc --android --arm-studio /path/to/arm-performance-studio\n```\n\n## Why rdc-cli?\n\nRenderDoc 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.\n\nrdc-cli bridges that gap:\n\n- **TSV by default** — every command outputs tab-separated text that pipes directly into Unix tools. Raw numbers, not human-friendly formatting.\n- **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`.\n- **Daemon architecture** — load the capture once, then query as many times as you want. No per-command startup cost.\n- **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).\n- **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.\n- **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.\n\n## Commands\n\nRun `rdc --help` for the full list, or `rdc \u003ccommand\u003e --help` for details.  See the [full command reference](https://bananasjim.github.io/rdc-cli/docs/commands/) for every option.\n\n| Category | Commands |\n|----------|----------|\n| Session | `open`, `close`, `status`, `goto` |\n| Inspection | `info`, `stats`, `events`, `draws`, `event`, `draw`, `log` |\n| GPU state | `pipeline`, `bindings`, `shader`, `shaders`, `shader-map` |\n| Debug | `debug pixel`, `debug vertex`, `debug thread`, `pixel`, `pick-pixel`, `tex-stats` |\n| Shader edit | `shader-build`, `shader-replace`, `shader-restore`, `shader-restore-all`, `shader-encodings` |\n| Resources | `resources`, `resource`, `passes`, `pass`, `usage`, `unused-targets` |\n| Export | `texture`, `rt`, `buffer`, `mesh`, `snapshot` |\n| Search | `search`, `counters` |\n| Assertions | `assert-pixel`, `assert-state`, `assert-image`, `assert-count`, `assert-clean` |\n| Diff | `diff` (with `--draws`, `--stats`, `--framebuffer`, `--pipeline`, etc.) |\n| VFS | `ls`, `cat`, `tree` |\n| Remote | `remote connect`, `remote list`, `remote capture` |\n| Android | `android setup`, `android stop`, `android capture` |\n| Target control | `attach`, `capture-trigger`, `capture-list`, `capture-copy` |\n| Capture file | `sections`, `section`, `callstacks`, `gpus`, `thumbnail` |\n| Utility | `doctor`, `completion`, `capture`, `count`, `script`, `serve`, `setup-renderdoc`, `install-skill` |\n\nAll list commands output TSV. All commands support `--json`. Footer/summary goes to stderr — stdout is always clean data.\n\n### Common options\n\nOptions available on most list/query commands (not every command supports all):\n\n```\n--json           JSON output (all commands)\n--jsonl          streaming JSON, one object per line (list commands)\n--no-header      drop TSV header for awk/cut (list commands)\n-q / --quiet     IDs only for xargs (list commands)\n--sort \u003cfield\u003e   sort by field (draws, resources, shaders)\n--limit \u003cN\u003e      truncate rows (events, search)\n--filter \u003cpat\u003e   name glob filter (events)\n-o \u003cpath\u003e        output to file (export commands)\n```\n\n### Shell completions\n\nCompletions are installed automatically by `pixi run install`. To install manually:\n\n```bash\nrdc completion bash \u003e ~/.local/share/bash-completion/completions/rdc\nrdc completion zsh  \u003e ~/.zfunc/_rdc\nrdc completion fish \u003e ~/.config/fish/completions/rdc.fish\n```\n\n## Development\n\n```bash\npixi run sync                 # install deps + git hooks + renderdoc symlink\npixi run install              # editable install + shell completions\npixi run check                # lint + typecheck + test\npixi run verify               # full packaging verification\n```\n\nGPU integration tests require a real renderdoc module:\n\n```bash\nexport RENDERDOC_PYTHON_PATH=/path/to/renderdoc/build/lib\npixi run test-gpu             # unit tests marked @gpu\npixi run e2e                  # cross-platform smoke test (26 checks)\npixi run test-e2e             # full e2e suite (self-capture + dynamic discovery)\n```\n\n## Contributing\n\nBug reports, feature requests, and pull requests are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbananasjim%2Frdc-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbananasjim%2Frdc-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbananasjim%2Frdc-cli/lists"}