Instructional GIFs

Three short screencasts of Rivet’s core workflows, rendered from VHS tape scripts against the repository’s local Docker Compose stack.

Overview screencasts:

Short, single-command spots (embedded next to each step of Getting Started):

Mode / planner spots (embedded in docs/modes/, docs/reference/, docs/planning/):

Destination-specific:

Operational warnings:

Change data capture:

They are linked from the user-facing guides (see “Where they appear” below) and are intentionally terminal-only: no narration, no cursor movement, no UI chrome. They show exactly what rivet prints.

Regenerating

Prereqs (one-off):

brew install vhs          # pulls ttyd + ffmpeg as dependencies

docker compose up -d postgres mysql
cargo build --release --bin rivet --bin seed
cargo run --release --bin seed -- --target postgres      # ~500 rows in public.orders

Render all three:

python3 -m dev.pytools.render_gifs

Or just one:

python3 -m dev.pytools.render_gifs basic
python3 -m dev.pytools.render_gifs plan-apply
python3 -m dev.pytools.render_gifs reconcile-repair
python3 -m dev.pytools.render_gifs init-scaffold
python3 -m dev.pytools.render_gifs check-verdict
python3 -m dev.pytools.render_gifs inspect
python3 -m dev.pytools.render_gifs chunked-progress
python3 -m dev.pytools.render_gifs incremental-cursor
python3 -m dev.pytools.render_gifs discover-artifact
python3 -m dev.pytools.render_gifs plan-campaign     # creates ~35 M rows in rivet_gif.*
python3 -m dev.pytools.render_gifs parallel-cards    # 4 chunked exports, parent-side cards UI
python3 -m dev.pytools.render_gifs pool-detect       # connect-time pooler/proxy warnings; see below
python3 -m dev.pytools.render_gifs doctor-gcs        # real GCS via ADC; see below

The default invocation (no args) renders the eleven “always reproducible” scenarios against Docker Compose (setup per scenario is ephemeral — tables live under a dedicated rivet_gif schema that is dropped on teardown). Two scenarios are opt-in:

• pool-detect needs the pool docker-compose profile up so pgBouncer (6432) and ProxySQL (6033) are reachable: docker compose --profile pool up -d pgbouncer proxysql.
• doctor-gcs needs gcloud auth application-default login and a writable bucket.

plan-campaign takes ~60 s because it seeds 35 M narrow rows so the cost-class classifier triggers shared_source_heavy_conflict.

The renderer creates an ephemeral /tmp/rivet-gif-<name> workdir, seeds any fixture the scenario needs (the reconcile-repair tape uses a dedicated 10,000-row rivet_gif.events schema that is dropped on exit), invokes vhs, and moves the rendered .gif next to the tape.

Environment the tapes assume

Each tape inherits DATABASE_URL, RIVET_BIN_DIR, and PSQL_BIN from the renderer. The first Hide block prepends them to PATH and sets a clean PS1='rivet-demo $ ' prompt, so the rendered terminal is deterministic regardless of the user’s shell rc.

Conventions

• Relative Output paths only. VHS rejects absolute paths.
• No multi-line Type heredocs. VHS parses every newline as a tape command. Fixture YAMLs are written to the workdir by the renderer before vhs runs (see fixture_chunked_setup).
• Theme: Dracula, 14 pt; 1200 x 720 for basic / plan-apply and 1280 x 780 for reconcile-repair (wider table output).
• Typing speed: 30–35 ms/char. Fast enough to keep GIFs short; slow enough to read command lines.

Where they appear

• README.md — top-level table of contents.
• docs/README.md — “Start here” section.
• docs/getting-started.md (current 4-step layout):
  • basic.gif in §3 “Preflight & run”.
  • check-verdict.gif in §3 (right after the rivet check block).
  • inspect.gif in §4 “Inspect & iterate”.
• docs/reference/cli.md — plan-apply.gif next to rivet plan, reconcile-repair.gif next to rivet reconcile, parallel-cards.gif next to rivet run --parallel-export-processes.
• docs/destinations/gcs.md — doctor-gcs.gif in the “Verify” section.
• docs/modes/chunked.md — chunked-progress.gif in “Progress bar (chunked exports)”.
• docs/modes/incremental.md — incremental-cursor.gif in “What happens”.
• docs/reference/init.md — init-scaffold.gif in “Single table”; discover-artifact.gif in “Discovery artifact”.
• docs/reference/prioritization.md — plan-campaign.gif in “Viewing the output”.
• docs/pilot/pilot-walkthrough.md — init-scaffold.gif (Step 1), plan-apply.gif (Step 3), inspect.gif (Step 5), reconcile-repair.gif (Steps 6–8).
• docs/pilot/demo-quickstart.md — plan-apply.gif (Step 3), reconcile-repair.gif (Step 4).
• docs/pilot/production-checklist.md — pool-detect.gif in “Connection poolers and proxies”.

If you update a tape, re-render, and commit both the .tape and the .gif together. The tape is the source; the GIF is the build artifact.