Tape File Syntax Reference

A tape file (.tape) is a plain-text script. Each command is on its own line, and commands run sequentially from top to bottom. This page catalogs every command and the lexical and parser rules that govern a tape.

For the full list of Set settings (names, defaults, ranges) see the configuration options reference. For the vcr.toml preset/macro layer used by Use and the Exec macro form, see the vcr.toml reference. For the CLI verbs that consume tapes, see the CLI commands reference.

Command catalog

The table below is the complete set of commands. Detailed entries follow.

Output

Declares a file the recording is written to. The format is chosen by the file extension. A path with no extension is treated as a directory of PNG frames.

Output "demo.svg"     # animated SVG (no FFmpeg required)
Output "demo.gif"     # animated GIF (requires FFmpeg)
Output "demo.mp4"     # H.264 MP4 (requires FFmpeg)
Output "demo.webm"    # VP9 WebM, supports transparency (requires FFmpeg)
Output "demo.png"     # single-frame PNG
Output "frames/"      # directory of PNG frames + a frames.txt manifest

A tape may have multiple Output lines to emit several formats from one run:

Output "demo.svg"
Output "demo.gif"

Set

Configures a setting. The value is a quoted string, a duration, a number, a boolean, or a bare word.

Set Theme Dracula
Set Cols 100
Set FontSize 22
Set TypingSpeed 40ms
Set TransparentBackground true
Set Mode static

Parser rules for Set:

• All Set commands must come before any action command (Type, a key, Sleep, Wait, Hide, Show, Screenshot). Output, Env, Use, and Exec are not subject to this ordering rule.
• No setting may be set twice. A duplicate Set of the same name is a parse error.
• An unknown setting name is a parse error with a "Did you mean…?" suggestion.

The full catalog of setting names, defaults, and ranges lives in the configuration options reference.

Type

Types text character-by-character at the configured typing speed.

Type "echo hello"
Type@500ms "slow typing"   # override per-character speed for this command

The optional @<duration> suffix overrides the typing speed for that command only (default comes from Set TypingSpeed). Text uses one of the three string quote styles; escape sequences such as \n and \t are interpreted only in double-quoted strings.

Special keys

Each special key sends one keypress. Every special key accepts an optional @<speed> and an optional trailing repeat count.

Enter
Backspace 5          # press Backspace five times
Down@100ms 3         # press Down three times, 100ms apart

Available keys:

Modifier chords

A chord is one or more modifiers — Ctrl, Alt, Shift — each joined with +, followed by a final key. Modifiers may appear in any order. The final key may be a special key or any single letter.

Ctrl+C
Alt+Enter
Shift+Tab
Ctrl+Alt+Shift+Tab

Sleep

Pauses for a fixed duration. Unlike Wait, it does not look at output.

Sleep 1          # bare number = seconds → 1s
Sleep 500ms
Sleep 1.5m

Wait

Blocks until terminal output matches a pattern, or — with no pattern — until output settles.

Wait                       # wait for output to settle (default scope: Buffer)
Wait /Complete/            # wait until "Complete" appears
Wait+Line /\$ $/           # search the current line only
Wait+Screen /done/         # search the whole visible grid
Wait@10s /ready/           # override the timeout for this command
Wait+Screen@5s /Complete/  # combine scope and timeout

• Scope (optional, default +Buffer):
  • +Buffer — output accumulated since the last Wait.
  • +Line — the current line only.
  • +Screen — the entire visible grid.
• @<timeout> (optional) overrides the default wait timeout (Set WaitTimeout, default 15s).
• /regex/ (optional) overrides the default pattern (the shell prompt).

A Wait that times out raises an error.

Hide / Show

Hide stops frame capture; Show resumes it. Commands keep executing while hidden — only capture is paused.

Hide
Type "secret setup"
Enter
Wait
Show

Screenshot

Captures a single frame at the current point in the recording. The format is chosen by the file extension: .svg produces a vector screenshot, .png produces a raster image.

Screenshot "frame.png"   # raster
Screenshot "frame.svg"   # vector (scalable, searchable text)

Exec

Runs a real shell command, capturing actual output. Exec has two forms.

Literal form — a quoted command string:

Exec "dotnet build"
Exec "git status"

The command runs as the session's foreground process; its launch line is never echoed. Later Type/key commands flow to the running program. Multiple Exec lines are joined into one launch. VCR# waits for output to settle (governed by InactivityTimeout / MaxWaitForInactivity) before ending.

Macro form — a bare name plus an argument, expanding a [macro] template defined in vcr.toml:

Exec showcase MyDemo

The macro is expanded before recording. See the vcr.toml reference for defining [macro] templates and their {0} / {name} placeholders.

Env

Sets an environment variable for the session.

Env NODE_ENV "production"
Env API_KEY "secret123"

Use

Applies a named preset from a discovered vcr.toml. This is configuration sugar: the preset's settings are folded in before recording.

Use doc

The tape's own Set lines always win over a preset. When multiple Use lines are present, the later one wins; preset inheritance is applied base-first. See the vcr.toml reference for preset definitions, inheritance, and output templates.

Run

Sugar for Type "command" followed by Enter and a bare Wait (waits for output to settle). It is expanded into those primitive commands before recording.

Run "dotnet --version"

is equivalent to:

Type "dotnet --version"
Enter
Wait

Lexical rules

Comments

A # begins a comment that runs to the end of the line and is ignored. It may start a line or follow a command.

# whole-line comment
Set Theme Dracula   # trailing comment

String literals

There are three quote styles:

Escape sequences interpreted in double-quoted strings:

Single- and backtick-quoted strings pass their contents through verbatim — useful for Windows paths and regex-heavy text where backslashes should not be escaped.

Numbers

Numbers are written as bare integers (100) or decimals (1.5). They are used for counts (e.g. key repeat), sizes, and the numeric part of durations.

Duration literals

A duration is a number followed by a unit suffix, with no space between them.

Sleep 500ms
Wait@10s /ready/
Set StartWaitTimeout 1.5m

Regex patterns

A regex is written between forward slashes and is used by Wait.

Wait /Complete/
Wait /\d{3} tests passed/

VCR# uses .NET regular expressions (System.Text.RegularExpressions). Matching is case-sensitive, single-line by default; an empty pattern (//) is a parse error.

Parser rules

• Ordering. All Set commands must appear before any action command (Type, a key, Sleep, Wait, Hide, Show, Screenshot). Output, Env, Use, and Exec are exempt from this rule.
• No duplicate settings. Setting the same name more than once is a parse error.
• Unknown settings. An unrecognized Set name is a parse error with a "Did you mean…?" suggestion.
• Command names are case-sensitive — use the documented casing (Type, not type). Setting names and true/false literals are case-insensitive.
• Whitespace. Leading and trailing whitespace on a line is ignored; blank lines are ignored; whitespace inside string literals is preserved.
• Unknown theme names are not errors — VCR# falls back to the Default theme. Spelling and spaces still matter (One Dark, not OneDark).

# settings first…
Set Theme Dracula
Set FontSize 24
  
# …then actions
Type "echo hello"
Enter
Wait

See also

• Configuration options reference — every Set setting.
• vcr.toml reference — presets for Use and macros for Exec.
• CLI commands reference — the verbs that run tapes.