# atmos cast record

Use this command to interpret a [VHS](https://github.com/charmbracelet/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`](/steps/type/cast#tape-interpretation)); `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`.

## Usage

```shell
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](/steps/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`](/cli/configuration/cast) applies, and then `clean`. See [`shell_init`](/steps/type/cast#fields) for the per-shell behavior.

## Examples

```shell
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:

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

## See Also

- [`type: cast` tape interpretation](/steps/type/cast#tape-interpretation) — the `tape` and `source` step fields this command shares its interpreter with
- [`atmos cast play`](/cli/commands/cast/play) — Replay a cast recording in the terminal
- [`atmos cast render`](/cli/commands/cast/render) — Render a cast recording to media output