atmos-cast

name	atmos-cast
description	Atmos cast recording and rendering: atmos cast play/render, output-format inference (gif/mp4/html/ascii/png/jpg/jpeg), the --cast/ATMOS_CAST auto-recording flag, workflow type: cast (steps/session modes) and type: simulate step types, and committed .cast screengrabs
metadata	{"copyright":"Copyright Cloud Posse, LLC 2026","version":"1.0.0","category":"dev-tooling"}

Atmos Cast

Use this skill for Atmos's built-in terminal session recording and rendering subsystem. A cast is an asciicast v2 recording (.cast) of a terminal session that Atmos can play back or render into shareable artifacts (GIF, MP4, HTML, ASCII, PNG, JPEG).

Related Skills

Need	Load
Workflow step types in general, orchestration, output/UI steps	atmos-workflows
Custom CLI commands with native steps	atmos-custom-commands
Global settings (atmos.yaml non-subsystem options)	atmos-settings

Purpose

Cast recording turns a terminal session into a deterministic, replayable artifact instead of a one-off screen capture. It is used to:

• Record CLI demos and documentation screengrabs as committed .cast files that render identically every time (no flaky video capture, no OS-specific fonts/cursors baked in).
• Capture a workflow or custom-command run as a proof-of-run artifact (CI evidence, runbook reproduction).
• Script fully synthetic "simulated" terminal sessions (typed commands with jitter, styled prompts) for docs and mindset demos, without actually running the commands shown.

Key Commands

Command	Purpose
atmos cast play <input.cast>	Play an asciicast recording back in the terminal
atmos cast render <input.cast> --output=<path>	Render a recording to GIF, MP4, HTML, ASCII, PNG, or JPEG
atmos cast render <input.cast> --output=<path> --format=<fmt>	Render with an explicit format when the output filename's extension doesn't indicate one

Global --cast Flag / ATMOS_CAST

Any Atmos command can be recorded directly, without going through atmos cast:

atmos terraform plan vpc -s dev --cast=demo.cast   # record raw asciicast
atmos terraform plan vpc -s dev --cast=demo.gif    # record, then auto-render to gif, discard the intermediate .cast
atmos terraform plan vpc -s dev --cast              # auto value: record without keeping/rendering (ad hoc)
ATMOS_CAST=demo.cast atmos terraform plan vpc -s dev

--cast/ATMOS_CAST accepts the same extensions as atmos cast render's output-format inference. When the value ends in a renderable extension (not .cast), Atmos records to a temporary cast in the OS temp dir, renders it to the requested output, and removes the intermediate .cast. When the value is .cast, the raw recording is kept at that path. --cast with no path (or true/1/yes/on via env) records without an explicit target.

Recording can also be enabled automatically for every command via atmos.yaml:

# atmos.yaml
cast:
  recording:
    enabled: true
    base_path: "./casts"   # directory intermediate/auto casts are written under
    input: false           # also record stdin keystrokes, not just output
    width: 120
    height: 30

Automatic (config-enabled) recording skips --help and shell-completion invocations so casual --help calls aren't captured; an explicit --cast/ATMOS_CAST still records help output.

Output Format Inference

Both atmos cast render and the --cast/ATMOS_CAST flag infer the render format from the output file's extension. Supported extensions/formats: .gif, .mp4, .html, .ascii, .png, .jpg, and .jpeg (.jpg/.jpeg both map to the jpeg renderer). .cast means "keep the raw recording, do not render."

atmos cast render demo.cast --output=demo.gif                 # format inferred from .gif
atmos cast render demo.cast --output=demo.html                # format inferred from .html
atmos cast render demo.cast --output=demo.out --format=html   # explicit --format for a non-matching extension

--format is required when the output path's extension doesn't map to a supported format (or has none). If both the extension and --format imply a format, they must agree -- Atmos errors on a conflict (e.g. --output=demo.gif --format=html).

Workflow and Custom-Command Step Types

The same recording/rendering engine is available as native step types inside workflows: and custom-command steps: -- no wrapper script needed.

type: cast

A cast step wraps a set of child steps (or a scripted shell session) and records everything they produce into an asciicast. It supports two mode: values:

mode: steps (default) -- runs nested child steps (any step type, including type: simulate) through the normal step executor and records their combined output:

steps:
  - type: cast
    name: demo-plan
    mode: steps           # optional, this is the default
    width: 120
    height: 30
    output:                # CastOutput: any subset of these paths
      cast: demo.cast       # keep the raw recording
      gif: demo.gif         # also render to gif
      html: demo.html       # also render to html
    steps:
      - type: simulate
        mode: typed
        text: "atmos terraform plan vpc -s dev"
      - type: atmos
        command: terraform plan vpc -s dev

mode: session -- drives an interactive shell directly with a scripted list of session actions instead of running typed steps. Each child step's type: is the session action:

Action	Fields	Purpose
write	text, rate	Type literal text into the session
key	key, interval	Send a single keypress (e.g. enter, tab, ctrl+c)
pause	duration	Wait a fixed duration before the next action
wait	text or regex (exactly one), timeout	Block until the session output matches

steps:
  - type: cast
    name: demo-session
    mode: session
    shell: bash
    steps:
      - type: write
        text: "atmos workflow deploy-vpc -s dev\n"
      - type: wait
        regex: "Apply complete!"
        timeout: 2m
      - type: key
        key: enter

Cast-level fields: width/height (recording dimensions), rate (default output pacing), title, command, env, and output (a CastOutput: cast, gif, mp4, html, ascii, png, jpg -- any subset). defaults.cast (rate/width/height) and defaults.simulate (see below) set shared defaults for child steps so they don't need to repeat the same values.

type: simulate

A simulate step (used as a child of a mode: steps cast) replays scripted terminal activity without actually running a command -- useful for docs/demo casts that show a command's output verbatim rather than depending on live infrastructure. Two mode: values:

• mode: typed (default) -- types text character-by-character at the terminal, then presses enter. Fields: text (required), rate (base per-character delay), jitter (0-1, randomizes per-character timing deterministically so re-recording the same script is reproducible), duration (delay before the simulated enter/output), interval (pause after the step, before the next), cursor (show the terminal cursor while typing), and prompt (SimulatePrompt: text and style, where style is one of the theme styles -- body, command, label, muted, info, notice).
• mode: prompt -- renders just the prompt (and optional cursor), without typing anything; used to show an idle prompt between recorded actions.

steps:
  - type: cast
    mode: steps
    defaults:
      simulate:
        prompt:
          text: "$ "
          style: command
        jitter: 0.3
    steps:
      - type: simulate
        mode: typed
        text: "atmos version"
        cursor: true
      - type: atmos
        command: version
      - type: simulate
        mode: prompt

Common Patterns

• Committed docs screengrabs: record demo commands to a .cast file, commit it, and render it at doc-build time (or check in the rendered HTML/image too). The .cast source stays deterministic across environments; re-rendering never depends on terminal fonts or timing.
• CI proof-of-run artifacts: wrap a workflow's real steps in type: cast with output.gif or output.html so a pipeline can publish what actually ran, not just its exit code.
• Fully synthetic demos: use type: simulate steps exclusively (no real atmos/shell children) to script a "fake" but visually authentic terminal walkthrough for marketing/docs content, independent of any live stack or component.
• Mixing real and simulated steps: interleave type: simulate (to narrate/type the command) with the real type: atmos/type: shell step that actually executes it, so the recording looks hand-typed while the executed output is genuine.
• Synthetic directory transitions: when the story enters a generated or nested directory, show type: simulate with cd <directory> before the first command there. This is display-only; keep working_directory on every real child step so execution does not depend on simulated terminal state.
• Prefer atmos cast render over ad hoc --cast=<gif> one-liners when a .cast source should be kept and re-rendered into multiple formats later; use --cast=<ext> for quick one-shot capture when only the rendered artifact matters.