🎥 CastWright

🎥 Scripted terminal recording.

ℹ️ Introduction

[!NOTE] The name castwright is a portmanteau of asciicast and playwright.

Have you recorded the same session over and over again, either to hit the right speed or to avoid mistakes? Ever wanted to automate the process of recording terminal sessions, like shell scripts automate the process of running commands? Well, CastWright is here to help.

🪄 Features

• Fast: CastWright is designed to be fast, with running time close to actually executing the given shell commands.
• Efficient: CastWright guarantees constant memory usage, by leveraging streaming I/O.
• Preview: Preview your asciicast without delays whilst CastWright is working, saving you the time for sitting through the entire recording.
• Intuitive: CastWright scripts are very intuitive and similar to an interactive shell, with friendly error messages, making it easy to understand, write, and maintain.
• Customization: CastWright scripts provide various instructions for customizing the produced asciicast, like typing speed or title.

🚀 Installation

If you have cargo-binstall, you can install this tool by running:

cargo binstall castwright

Otherwise, you can install it from source:

cargo install castwright

Pre-built binaries are available at Releases.

📖 Usage

Command Line Interface

$ castwright --help
Usage: castwright [-i <input>] [-o <output>] [-x] [-t] [-v]

🎥 Scripted terminal recording.

Options:
  -i, --input       the path to the input file (`CastWright` script `.cwrt`), or
                    stdin if not provided
  -o, --output      the path to the output file (asciicast `.cast`), or stdout
                    if not provided; If provided, preview mode will be enabled
  -x, --execute     execute and capture the output of shell commands
  -t, --timestamp   include timestamp information in the output
  -v, --version     show version information and exit
  -h, --help        display usage information

CastWright Script

A CastWright script is a text file, conventionally with the .cwrt extension. It is line-based, with each line representing a single instruction. For example:

$ echo "Hello, World!"

Would output an asciicast recording of the following:

$ echo "Hello, World!"
Hello, World!

For multiline commands, use the > prefix and \ suffix, as you would in an interactive shell. For example:

$ echo "Multi-" \
> "line" \
> "command"

Would output an asciicast recording of the following:

$ echo "Multi-" \
> "line" \
> "command"
Multi- line command

In addition, CastWright provides various instructions for customizing the produced asciicast, like typing speed or title. See REFERENCE.md for a detailed reference, or example CastWright scripts under the tests directory.

As a Library

CastWright can also be used as a Rust library, providing a simple API for creating an asciicast from a CastWright script. In addition, the library provides an AsciiCast struct for creating asciicasts in a streaming fashion.

🚫 Caveats

You can find a list of known caveats in CAVEATS.md. Most notably, each command is executed in a separate shell session, which may not be ideal for some use cases.

✅ TODO

• Implement the CastWright script parser.
• Write to an asciicast file.
• Terminal width and height detection.
• Better pub API.
• Run cargo clippy.
• Integration tests.
• Actual command execution and output capture.
  • Use a single shell session, instead of spawning a new one for each command.

🎉 Credits

• asciinema
• autocast
• asciinema-scenario