# 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.

```yaml
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.