vcr.toml and Presets Reference

Overview

vcr.toml is an optional config file that lets multiple tapes share Set values, output locations, and reusable Exec command templates. A tape opts in with Use (for presets) and the macro form of Exec (for macros).

Presets and macros are expanded before recording. PresetResolver rewrites Use and the Exec macro form into primitive commands while the tape is being resolved, so the recording engine never sees a preset or a macro — only the final, flattened settings and actions.

For a task-oriented walkthrough, see the presets how-to guide. For the inverse operation — factoring existing tapes into a shared vcr.toml — see vcr migrate.

Discovery

VCR# locates vcr.toml by walking up the directory tree from the tape file's directory until it finds a file named exactly vcr.toml. The first one found is used.

This means a single vcr.toml at the root of a project applies to every tape beneath it, and a nested vcr.toml overrides the one above it for tapes in that subtree.

File format

vcr.toml is a deliberate TOML subset. It supports two section kinds and simple scalar values only. The following TOML features are not supported:

• Arrays
• Inline tables
• Dotted keys (beyond the section header itself)

There are exactly two section kinds: [preset.NAME] and [macro].

Value types

Values in both section kinds are parsed as one of:

[preset.NAME] sections

A [preset.NAME] section declares a named preset. NAME is case-insensitive and may be quoted ([preset."my doc"]). Repeated [preset.NAME] headers with the same name merge into one preset.

Reserved keys

Three keys inside a preset are reserved and are not settings:

Setting keys

Every key other than the three reserved keys is a setting, using the same names as the tape Set command (see the configuration options reference). Settings are validated at resolve time, so an unknown name or an out-of-range value is reported before recording starts.

[macro] section

The [macro] section holds name = "template" entries that back the macro form of Exec. A tape references one with Exec name arg, which expands the named template.

Templates support two placeholders:

For example, with showcase = "dotnet run --no-build showcase {0}" in [macro], a tape line of Exec showcase demo expands to Exec "dotnet run --no-build showcase demo".

Resolution rules

When a tape is resolved, presets, inheritance, and output derivation combine in a fixed order:

• Inheritance is base-first. If a preset declares inherits, the parent's keys are applied first, then the child preset's keys override them.
• Later Use wins. A tape may have multiple Use lines. When two applied presets set the same key, the one applied later wins.
• The tape's own Set always wins. Any setting the tape sets directly with Set overrides whatever a preset would have applied.
• Output derivation. An applied preset's output template (or, failing that, outDir) supplies the tape's Output. An explicit Output line in the tape takes precedence.

Example

[preset.doc]
theme = "one dark"
cols = 82
transparentBackground = true
endBuffer = 5s
outDir = "assets"          # Output becomes assets/<tape>.svg
  
[preset.landing]
inherits = "doc"
fontSize = 13
output = "assets/{name}.png"
  
[macro]
showcase = "dotnet run --no-build showcase {0}"

Given this config, a tape with Use landing inherits everything from doc (theme, cols, transparent background, end buffer), overrides fontSize to 13, and writes its output to assets/<tape>.png (the output template overrides doc's outDir). A tape with Exec showcase chart runs dotnet run --no-build showcase chart.

See also

• How to share settings with presets — task-oriented guide.
• Configuration options reference — every setting name and value.
• Tape file syntax reference — Use, Run, and Exec.
• CLI commands reference — vcr migrate factors tapes into a vcr.toml.