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. Atmos automatically installs the managed agg renderer for GIF and agg plus FFmpeg for MP4 on first use. MP4 is produced from a GIF and can retain GIF palette constraints.

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.

Set a segment's playback duration

Use a type: playback group inside a cast to fit its nested steps into a fixed recorded duration. Grouping the Enter key with the completion wait includes output from the moment the command starts:

- type: write
  text: atmos terraform deploy --stack dev --all
- type: playback
  duration: 4s
  steps:
    - type: key
      key: enter
    - type: wait
      regex: '(?s)Apply .*completed.*> '
      timeout: 90s
- type: pause
  duration: 3s

Place these actions inside mode: session or a nested type: session block. The group's clock starts before its first child and stops after its last child finishes. A deployment that takes 24 seconds therefore plays in 4 seconds, while the preceding typing and following 3-second reading pause keep their normal timing. All captured events, including terminal redraws, retain their content and order; the recorder scales their timestamps proportionally. Elapsed times printed by the command still show its actual execution time.

The duration must be positive. It is an exact playback duration, so a shorter recording is stretched to fit too. Execution, wait timeouts, and cancellation still use real time. Output remains live while recording; only the active group's events are buffered for timing adjustment. Silent groups retain their requested duration. Failed recordings are discarded as usual.

Playback groups also work in mode: steps, wrapping ordinary steps such as shell or atmos. They require an enclosing cast and cannot nest or overlap. Keep typing and reading pauses outside a group when they should retain their original timing.