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.

Tape interpretation

A cast step can interpret VHS-dialect tape script text directly, in memory, instead of a hand-authored steps: list — useful when you already have a .tape file (for example, one written for the real vhs binary) and want to point Atmos at it directly.

tape

Inline, multi-line VHS-dialect script. Mutually exclusive with tape_file and with an explicit steps: list.

tape_file

Path to an external .tape file, interpreted the same way as tape. Source directives anywhere in it (including nested Sources) resolve relative to the step's working_directory (or the process CWD if unset) — the same base tape_file itself resolves against, matching real vhs, which resolves every Source in a script relative to its own invocation directory, not relative to whichever file a Source happens to be read from.

steps:
  - name: hero-demo
    type: cast
    mode: session
    tape_file: demo/hero.tape
    output:
      mp4: hero.mp4

steps:
  - name: quick-check
    type: cast
    mode: steps
    tape: |
      Type "atmos list stacks" Enter
      Type "atmos validate stacks" Enter
    output:
      cast: quick-check.cast

mode: steps vs mode: session

The existing mode field governs how a tape is translated, and it determines whether a failing typed command actually fails the step:

• mode: steps (exit-code fidelity) — each Type "cmd" Enter becomes a type: simulate child (so it looks typed in the recording) paired with a real type: shell child that actually executes cmd, with a real, tracked exit code. Sleep/Wait are dropped (step execution is already synchronous). A visible cd/export/unset/clear command updates the following real steps' working_directory/env instead of running as its own (state-losing) subprocess. Screenshot is supported. Any directive with no discrete-step equivalent — a bare keypress, Hide/Show, or a Type with no trailing Enter — is a parse-time error naming the offending line, telling you to switch to mode: session.
• mode: session (raw keypress/PTY fidelity) — Type/Sleep/Wait/keypresses (including Ctrl+<letter>) map onto the existing write/key/pause/wait session actions. This keeps mode: session's existing limitation: no per-command exit code, since the whole script drives one continuous PTY session.

Set, Output, Require, Source

VHS directive	Atmos target	Notes
Set Shell, Set Width, Set Height, Set TypingSpeed, Set WaitTimeout	shell, width/height, write_rate, default Wait timeout	An explicit field on the step always wins over a tape-implied value.
Set FontFamily/FontSize/Theme/Margin/Padding/BorderRadius/Framerate/CursorBlink/WaitPattern/...	(ignored)	Cosmetic VHS options with no Atmos rendering analog.
Output <path>	output.*	One per supported extension (.cast, .gif, .mp4, .html, .ascii, .png, .jpg/.jpeg) — .webm and .txt are not supported and produce an error.
Require <program>	a synthesized type: require child	Runs the same tool-presence check as a hand-authored type: require step, before the cast body executes.
Source <file>	inlined directives	Resolved relative to the step's working_directory (or the process CWD) — the same fixed base used for tape_file itself and for every Source, no matter how deeply nested.
Hide / Show	lifted into env:/working_directory:, or literal replay	A Hide...Show region whose commands are only export/unset/cd/clear is lifted into the step's own config (no PTY replay needed); anything else falls back to literal typing while muted. mode: steps has no PTY at all, so Hide/Show are always an error there.
Copy, Paste, Env	(unsupported)	Always a parse error in both modes — rewrite the tape (inline Env as a shell export, replace Copy/Paste with a direct Type) before using tape:/tape_file:.

atmos cast record

For a one-off tape with no workflow YAML at all, use the record subcommand directly:

atmos cast record demo/hero.tape --output=hero.mp4

record builds an ephemeral type: cast step from the tape and runs it through the same interpreter — see atmos cast record for the full flag reference. For the complete supported/ignored/error directive matrix and worked migration examples, see the atmos-vhs skill.