cast

The cast step type records deterministic terminal demos as asciicast files. It can run nested workflow steps, simulate typed commands, and render additional outputs from the same recording.

steps:
  - name: list-stacks
    type: cast
    mode: steps
    command: atmos list stacks --format=tree
    defaults:
      cast:
        rate: 12ms
        width: 120
        height: 36
      simulate:
        mode: typed
        cursor: true
        rate: 35ms
        prompt:
          text: "> "
          style: command
    output:
      cast: website/static/casts/list-stacks.cast
    steps:
      - type: simulate
        text: atmos list stacks --format=tree
      - type: shell
        output: raw
        command: atmos list stacks --format=tree
      - type: toast
        level: success
        content: Cast recorded.

Fields

mode: Recording mode. Use steps for deterministic nested workflow steps, or session for interactive terminal sessions.
command: Optional command string stored in the asciicast header.
output.cast: Path for the generated .cast file.
output.gif, output.mp4: Optional animated outputs rendered after the cast recording succeeds (require external tools: agg, and ffmpeg for MP4).
output.html, output.ascii, output.png, output.jpg: Optional static outputs rendered natively from the recording's final terminal content — an inline-styled HTML fragment, plain text with no ANSI codes, or a terminal screenshot image. No external tools required. .ascii artifacts are cheap to commit and diff, and can be consumed by other tooling without an asciicast player.
defaults.cast: Recording defaults for the cast step. Supports rate, width, and height. Explicit top-level rate, width, or height fields on the cast step override these defaults.
defaults.simulate: Defaults applied to direct child type: simulate steps. Supports mode, cursor, prompt, rate, jitter, duration, and interval. Explicit fields on the child simulate step override these defaults, including cursor: false.
env: Environment variables available to nested cast steps.
working_directory: Directory inherited by nested steps that do not define their own working directory.
steps: Nested workflow steps to execute while the recorder is active. In steps mode, shell, simulate, toast, and other normal workflow steps can be recorded.

Use shared YAML includes for repeated recording settings when multiple casts should have the same terminal dimensions, playback rate, simulated prompt, or recording environment.

Fields​

Fields