Skip to main content

atmos cast record

Use this command to interpret a VHS-dialect .tape file directly into an asciicast recording — an ad hoc entry point for a one-off tape with no workflow YAML at all. It reuses the exact same interpreter as a type: cast step's tape and source fields (see type: cast); record is the missing third verb alongside play and render: it takes a .tape and produces a .cast (optionally rendered further), the inverse direction of render.

atmos cast record --help

Usage​

atmos cast record <input.tape> --output=<path> [--format=<fmt>] [--mode=<session|steps>] [--shell=<command>] [--shell-init=<clean|user|path>]

Arguments​

input.tape
Required. Path to the VHS-dialect tape file to interpret.

Flags​

--output, -o
Required. Write the recording (or rendered artifact) to this path. A .cast extension keeps the raw recording; any other supported extension (.gif, .mp4, .html, .ascii, .png, .jpg/.jpeg) records to a temporary .cast first, renders it here, and removes the temporary file. An existing file at this path is overwritten on rerun. The tape's own Output directives are honored in addition to this flag, so one run can write several artifacts.
--format, -f
Output format (cast, gif, mp4, html, ascii, png, jpg, jpeg). Optional when --output's extension already identifies the format. When the extension is a recognized one, --format must agree with it in both directions, so --output=demo.gif --format=cast is an error. Use --format to pick the format for an output path whose extension does not identify one.
--mode
Cast mode: session (default) or steps. Defaults to session — the opposite of type: cast's own default — since a bare .tape handed to the CLI is almost always meant to replay as an actual VHS-style session, which commonly includes raw keypresses that only mode: session supports. Use --mode=steps for a tape that only types shell commands, to get real per-command exit codes; the command errors if the tape contains anything mode: steps can't express (see type: cast tape interpretation). The --mode and --format values are validated before recording starts.
--shell

Shell the session starts, as a command line that may include arguments, such as --shell=zsh or --shell="bash -o vi" (environment variable ATMOS_CAST_RECORD_SHELL). It overrides the tape's Set Shell; when omitted, the tape's Set Shell applies, and then $SHELL. The arguments follow the ones --shell-init adds, so a clean startup is kept; to run a command line that manages startup files itself, such as --shell="bash --rcfile demo.rc", pair it with --shell-init=user.

--shell-init

Controls which startup files the session shell loads (environment variable ATMOS_CAST_RECORD_SHELL_INIT): clean starts the shell without the user's startup files so the recording is reproducible, user loads them, and any other value is a path to an rc file that is sourced instead. When omitted, cast.session.shell_init from atmos.yaml applies, and then clean. See shell_init for the per-shell behavior.

Examples​

atmos cast record ./demo.tape --output=demo.mp4
atmos cast record ./demo.tape --output=demo.cast
atmos cast record ./demo.tape --output=demo.gif --mode=steps
atmos cast record ./demo.tape --output=demo.cast --shell-init=user
atmos cast record ./demo.tape --output=demo.gif --shell="bash -o vi"

Recording straight to .cast lets you inspect, play, or render it further without re-interpreting the tape:

atmos cast record ./demo.tape --output=demo.cast
atmos cast play demo.cast
atmos cast render demo.cast --output=demo.gif

See Also​