rdc-cli 0.3.0__tar.gz → 0.3.2__tar.gz

rdc_cli-0.3.2/.commitlintrc.yml

@@ -0,0 +1,2 @@
+extends:
+  - '@commitlint/config-conventional'

rdc_cli-0.3.2/.githooks/pre-commit

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Pre-commit hook: run lint + typecheck + test before every commit.
+# Install: git config core.hooksPath .githooks
+set -euo pipefail
+
+echo "pre-commit: running pixi run check..."
+pixi run check

rdc_cli-0.3.2/.githooks/pre-push

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Pre-push hook: run e2e test before pushing.
+# Requires active renderdoc module — skip with: git push --no-verify
+set -euo pipefail
+
+echo "pre-push: running pixi run e2e..."
+pixi run e2e

rdc_cli-0.3.2/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @BANANASJIM

rdc_cli-0.3.2/.github/workflows/aur.yml

@@ -0,0 +1,63 @@
+name: AUR Publish
+
+on:
+  push:
+    branches: [master]
+    paths: ["aur/PKGBUILD"]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  aur-git:
+    name: Publish rdc-cli-git
+    runs-on: ubuntu-latest
+    if: github.ref_type == 'branch'
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - uses: KSXGitHub/github-actions-deploy-aur@9dfe151cf48f26a957bbd0379c120e79cb990e13 # v2.7.2
+        with:
+          pkgname: rdc-cli-git
+          pkgbuild: aur/PKGBUILD
+          commit_username: ${{ secrets.AUR_USERNAME }}
+          commit_email: ${{ secrets.AUR_EMAIL }}
+          ssh_private_key: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+          commit_message: "Update PKGBUILD"
+
+  aur-stable:
+    name: Publish rdc-cli (stable)
+    runs-on: ubuntu-latest
+    if: github.ref_type == 'tag'
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Extract version
+        id: ver
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Compute tarball sha256
+        id: sha
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          SHA=$(curl -fsSL "https://github.com/BANANASJIM/rdc-cli/archive/refs/tags/v${VERSION}.tar.gz" | sha256sum | awk '{print $1}')
+          echo "sha256=${SHA}" >> "$GITHUB_OUTPUT"
+
+      - name: Patch PKGBUILD
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+          SHA256: ${{ steps.sha.outputs.sha256 }}
+        run: |
+          sed -i "s/^pkgver=.*/pkgver=${VERSION}/" aur/stable/PKGBUILD
+          sed -i "s/'PLACEHOLDER'/'${SHA256}'/" aur/stable/PKGBUILD
+
+      - uses: KSXGitHub/github-actions-deploy-aur@9dfe151cf48f26a957bbd0379c120e79cb990e13 # v2.7.2
+        with:
+          pkgname: rdc-cli
+          pkgbuild: aur/stable/PKGBUILD
+          commit_username: ${{ secrets.AUR_USERNAME }}
+          commit_email: ${{ secrets.AUR_EMAIL }}
+          ssh_private_key: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+          commit_message: "Update rdc-cli to v${{ steps.ver.outputs.version }}"

rdc_cli-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,183 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+    tags: ["v*"]
+  pull_request:
+    branches: [master, main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+
+      - name: Setup Python
+        run: uv python install 3.12
+
+      - name: Sync deps
+        run: uv sync --extra dev
+
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+      - name: Ruff format check
+        run: uv run ruff format --check src tests
+
+      - name: Verify skill reference is fresh
+        run: diff <(uv run python scripts/gen-skill-ref.py) src/rdc/_skills/references/commands-quick-ref.md
+        shell: bash
+
+  security:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --extra dev
+      - run: uv run --with pip-audit pip-audit
+
+  typecheck:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+
+      - name: Setup Python
+        run: uv python install 3.12
+
+      - name: Sync deps
+        run: uv sync --extra dev
+
+      - name: Mypy
+        run: uv run mypy src
+
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+
+      - name: Setup Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync deps
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Pytest + coverage
+        run: uv run --python ${{ matrix.python-version }} pytest tests/unit -v --cov=rdc --cov-report=term-missing --cov-fail-under=80
+
+  build-and-verify:
+    name: Build & verify (py${{ matrix.python-version }})
+    needs: [lint, typecheck, test]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+
+      - name: Setup Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Build
+        run: uv build --python ${{ matrix.python-version }}
+
+      - name: Twine check
+        run: uvx twine check dist/*
+
+      - name: Check wheel contents
+        run: uvx check-wheel-contents dist/*.whl
+
+      - name: Create clean test venv
+        run: uv venv /tmp/test-env --python ${{ matrix.python-version }}
+
+      - name: Install wheel in clean venv
+        run: uv pip install dist/*.whl --python /tmp/test-env/bin/python
+
+      - name: Smoke test version
+        run: /tmp/test-env/bin/rdc --version
+
+      - name: Smoke test help
+        run: /tmp/test-env/bin/rdc --help
+
+      - name: Smoke test import
+        run: /tmp/test-env/bin/python -c "from rdc.cli import main"
+
+      - name: Upload dist artifacts
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
+        with:
+          name: dist
+          path: dist/
+
+  release:
+    name: Publish to PyPI + GitHub Release
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [build-and-verify]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
+        with:
+          files: dist/*
+          generate_release_notes: true

rdc_cli-0.3.2/.github/workflows/commitlint.yml

@@ -0,0 +1,27 @@
+name: Commit Lint
+
+on:
+  pull_request:
+    branches: [master, main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Commitlint
+        uses: wagoid/commitlint-github-action@b948419dd99f3fd78a6548d48f94e3df7f6bf3ed # v6.2.1
+        with:
+          configFile: .commitlintrc.yml

rdc_cli-0.3.2/.github/workflows/docs.yml

@@ -0,0 +1,127 @@
+name: Docs
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: gh-pages
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          if [[ "$GITHUB_REF_NAME" == v* ]]; then
+            echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+          else
+            VER=$(grep -m1 '^version' pyproject.toml | sed 's/.*= *"\(.*\)"/\1/')
+            echo "version=${VER}-dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@eac588ad8def6316056a12d4907a9d4d84ff7a3b # v7.3.0
+        with:
+          enable-cache: true
+
+      - name: Install Python dependencies
+        run: uv sync --extra dev
+
+      - name: Compute test stats
+        id: test_stats
+        run: |
+          TEST_COUNT=$(uv run pytest tests/unit --co 2>/dev/null \
+            | grep -oP '^\d+(?= tests? collected)' || echo "0")
+          COV_PCT=$(uv run pytest tests/unit --cov=rdc --cov-report=term-missing \
+            --no-header -rN -q 2>/dev/null \
+            | grep 'TOTAL' | awk '{print $NF}' || echo "")
+          echo "test_count=${TEST_COUNT}" >> "$GITHUB_OUTPUT"
+          echo "coverage=${COV_PCT}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate stats.json
+        env:
+          DOC_VERSION: ${{ steps.version.outputs.version }}
+          TEST_COUNT: ${{ steps.test_stats.outputs.test_count }}
+          COVERAGE: ${{ steps.test_stats.outputs.coverage }}
+        run: |
+          mkdir -p docs-astro/src/data
+          uv run python scripts/gen-stats.py \
+            --version "$DOC_VERSION" \
+            --test-count "$TEST_COUNT" \
+            --coverage "$COVERAGE" \
+            > docs-astro/src/data/stats.json
+          cat docs-astro/src/data/stats.json
+
+      - name: Build mkdocs
+        run: uv run --with "mkdocs<2" --with mkdocs-material --with mkdocs-click mkdocs build -d _site
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs-astro/package-lock.json
+
+      - name: Build Astro
+        run: |
+          cd docs-astro
+          npm ci
+          npm run build
+
+      - name: Merge mkdocs CLI reference into Astro output
+        run: |
+          mkdir -p docs-astro/dist/docs/cli-reference
+          cp -r _site/cli-reference/* docs-astro/dist/docs/cli-reference/
+
+      - name: Generate badge endpoint JSONs
+        run: |
+          mkdir -p docs-astro/dist/badges
+          python3 -c "
+          import json, pathlib
+          s = json.loads(pathlib.Path('docs-astro/src/data/stats.json').read_text())
+          badges = [
+              ('commands', str(s.get('command_count', '?')), 'brightgreen'),
+              ('tests',    str(s.get('test_count', 0) or '?'), 'blue'),
+              ('coverage', s.get('coverage', '') or '?',       'green'),
+          ]
+          for name, message, color in badges:
+              pathlib.Path(f'docs-astro/dist/badges/{name}.json').write_text(
+                  json.dumps({'schemaVersion': 1, 'label': name, 'message': message, 'color': color})
+              )
+          print('Badges generated:', [b[0] for b in badges])
+          "
+
+      - name: Deploy to gh-pages branch
+        env:
+          DOC_VERSION: ${{ steps.version.outputs.version }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          cd docs-astro/dist
+          git init -b gh-pages
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "deploy: v${DOC_VERSION}"
+          git push --force \
+            "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \
+            HEAD:gh-pages
+
+      - name: Update repo metadata
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOC_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          gh repo edit \
+            --description "Scriptable CLI for RenderDoc captures — built for terminal workflows, CI pipelines, and AI agents (v${DOC_VERSION})" \
+            || true
+          gh repo edit --homepage "https://bananasjim.github.io/rdc-cli/" || true

rdc_cli-0.3.2/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+CLAUDE.md
+tests/fixtures/vulkan_samples
+.local/
+.claude/*
+!.claude/skills/
+_site/
+docs-astro/dist/

rdc_cli-0.3.2/.python-version

@@ -0,0 +1 @@
+3.14

rdc_cli-0.3.2/.release-please-manifest.json

@@ -0,0 +1 @@
+{".": "0.2.0"}

rdc_cli-0.3.2/Makefile

@@ -0,0 +1,20 @@
+.PHONY: sync check lint format typecheck test
+
+sync:
+	uv sync --extra dev
+
+check: lint typecheck test
+
+lint:
+	uv run ruff check src tests
+	uv run ruff format --check src tests
+
+format:
+	uv run ruff format src tests
+	uv run ruff check --fix src tests
+
+typecheck:
+	uv run mypy src
+
+test:
+	uv run pytest tests -v --cov=rdc --cov-report=term-missing --cov-fail-under=80

rdc_cli-0.3.2/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: rdc-cli
+Version: 0.3.2
+Summary: Unix-friendly CLI for RenderDoc .rdc captures
+Author: Jim
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Environment :: Console
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: Pillow>=10.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == "rich"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+```
+ _____  _____   _____
+|  __ \|  __ \ / ____|
+| |__) | |  | | |
+|  _  /| |  | | |
+| | \ \| |__| | |____
+|_|  \_\_____/ \_____|  cli
+```
+
+[![PyPI](https://img.shields.io/pypi/v/rdc-cli)](https://pypi.org/project/rdc-cli/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/rdc-cli/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Commands](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/commands.json)](https://bananasjim.github.io/rdc-cli/)
+[![Tests](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/tests.json)](https://bananasjim.github.io/rdc-cli/)
+[![Coverage](https://img.shields.io/endpoint?url=https://bananasjim.github.io/rdc-cli/badges/coverage.json)](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
+```
+
+## 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.
+
+## Quick examples
+
+**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
+```
+
+## Install
+
+**PyPI** (recommended)
+
+```bash
+pipx install rdc-cli
+# build renderdoc Python module (one-time, ~3 min, needs cmake/ninja/python3)
+curl -fsSL https://raw.githubusercontent.com/BANANASJIM/rdc-cli/master/scripts/build-renderdoc.sh | bash
+rdc doctor   # verify installation
+```
+
+**AUR** (Arch Linux — builds renderdoc Python module automatically)
+
+```bash
+yay -S rdc-cli-git
+```
+
+**From source**
+
+```bash
+git clone https://github.com/BANANASJIM/rdc-cli.git
+cd rdc-cli
+pixi install && pixi run sync
+```
+
+## 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/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 <field>   sort by field (events, resources, shaders)
+--limit <N>      truncate rows (events, search)
+--filter <pat>   name glob filter (events)
+-o <path>        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)