name: rvst-cli description: Reference for every RVST CLI mode and test-harness command. Use whenever you need to validate layout, drive a user interaction, or investigate a render bug without a visible window. type: reference

RVST CLI — every tool the agent has

RVST hosts (typeaway, rvst-app, any downstream app) ship four headless modes. Every one is a way to see what the user sees without opening a window. Prefer them over manual launches.

The four modes

--dump · DOM + layout tree

target/blitz/release/<bin> --dump path/to/app.js path/to/app.css

Prints every Blitz DOM node: id, tag, class/id attributes, computed width/height/position, display mode, bg/fg colors, padding. Text nodes show their content preview.

Use when:

• A component is the wrong size (grep for the id or class, check WxH @ (x,y))
• Computed styles look wrong (colors, padding are printed per-node)
• You need to confirm a DOM mutation landed (before/after)

Viewport is fixed at 640×400 in dump mode. That's fine for layout sanity; use --ascii for realistic viewports.

--snapshot · structured JSON

target/blitz/release/<bin> --snapshot app.js app.css

Prints a SceneSnapshot as JSON. Same info as --dump but machine-readable — the shape is rvst_snapshot::SceneSnapshot. Pipe through jq to extract:

... --snapshot | jq '.nodes[] | select(.attrs.id=="typeaway-editor")'

Use for automated tests and diffing.

--ascii · rendered layout visualization

target/blitz/release/<bin> --ascii app.js app.css
target/blitz/release/<bin> --ascii --view=a11y app.js app.css

Runs the resolver at 1280×800 and prints a 120×40 ASCII art rendering of the node boxes, plus a compact tree. --view= options include semantic (default), a11y, tag, text.

Use when:

• You want a quick "does this look roughly right"
• Checking for obvious layout overflow / missing elements
• Capturing in a bug report

--test · interactive JSON protocol

echo '{"cmd":"snapshot"}' | target/blitz/release/<bin> --test app.js app.css

This is the workhorse. Reads one JSON command per line from stdin, prints one JSON result per line on stdout. Starts with {"ready":true,"node_count":N}. Handles everything interactive.

Test-harness command reference

All commands take cmd (name) + params (object). Listed by category.

State inspection

Interaction

Runtime event injection (HMR / doc events)

Visualization

Analysis

Assertions (exit non-zero on failure if you care)

Diff workflow

Session

Dev-harness only (internal use)

Canonical workflows

"Does my CSS change produce the right layout?"

# Snapshot the baseline
target/blitz/release/<bin> --snapshot app.js app.css > /tmp/before.json
# Change the CSS, rebuild
npm run build
target/blitz/release/<bin> --snapshot app.js app.css > /tmp/after.json
# Diff (jq is the easy approach)
diff <(jq -S '.nodes[] | {id,tag,layout}' /tmp/before.json) \
     <(jq -S '.nodes[] | {id,tag,layout}' /tmp/after.json)

"Does my click handler fire?"

(
  cat <<'CMD'
{"cmd":"eval","params":{"script":"globalThis.__clicked=0;document.addEventListener('click',()=>{globalThis.__clicked++})"}}
CMD
  cat <<'CMD'
{"cmd":"click","params":{"id":<rvst-id>}}
CMD
  cat <<'CMD'
{"cmd":"eval","params":{"script":"globalThis.__rvst_test_result=String(globalThis.__clicked)"}}
CMD
  echo '{"cmd":"close"}'
) | target/blitz/release/<bin> --test app.js app.css

Expect "result":"1" — otherwise the handler is not wired.

"What's preventing this button from being clickable?"

echo '{"cmd":"why_not_visible","params":{"id":<rvst-id>}}' \
  | target/blitz/release/<bin> --test app.js app.css

"Did the HMR event reach the DOM?"

(
  echo '{"cmd":"snapshot_mark","params":{"name":"pre"}}'
  echo '{"cmd":"dispatch_event","params":{"type":"rvst:hmr-message","extra":{"data":"{\"type\":\"update\",\"updates\":[]}"}}}'
  echo '{"cmd":"diff","params":{"mark":"pre"}}'
  echo '{"cmd":"close"}'
) | target/blitz/release/<bin> --test app.js app.css

Anti-patterns

• Launching the windowed app to "see if it worked" when --ascii or --test would answer the same question in 200ms. You can't see the window. The validation tools are how you see it.
• Ignoring a crash because it "still looks ok" — check ~/Library/Caches/typeaway/last-panic.log. A silent abort is not a passing test.
• Testing with a single viewport for a layout change — run --dump (640×400) and --ascii (1280×800) both. Responsive bugs hide in the gap.