Atmos Cast

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

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

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:

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.