k9withabone / autocast

Automate terminal demos

autocast

A tool to help automate the creation of terminal demos. Automatically generate an asciicast file for use with asciinema.

Demo created with autocast, see demo.yaml. The demo is also viewable on asciinema.

Features

• Generates asciicast files from the settings and instructions in an input YAML file.
• Fast, run time is dependent upon the run time of the shell commands, with minimal overhead.
• Use bash, python, or a custom shell.
• Customize the output's prompt and secondary prompt, separate from the shell's.
• Use hidden commands for automated setup and cleanup.

Installation

• Download a prebuilt binary from releases.
• Use cargo-binstall to get a prebuilt binary with cargo binstall autocast.
• Build and install with cargo install autocast.

Usage

CLI

$ autocast -h

Automate terminal demos

Usage: autocast [OPTIONS] <IN_FILE> <OUT_FILE>

Arguments:
  <IN_FILE>   Input file to create the asciicast file with
  <OUT_FILE>  Output asciicast file

Options:
      --width <WIDTH>
          Terminal width
      --height <HEIGHT>
          Terminal height
  -t, --title <TITLE>
          Title of the asciicast
      --shell <SHELL>
          Shell to use for running commands [default: bash] [possible values: bash, python]
  -e, --environment <NAME=VALUE>
          Environment variables to use in the shell process
      --environment-capture <ENV_VAR>
          Environment variables to capture [default: TERM] [aliases: env-cap]
  -d, --type-speed <TYPE_SPEED>
          Default time between key presses when writing commands [default: 100ms] [aliases: delay]
      --prompt <PROMPT>
          The shell prompt to use in the asciicast output [default: "$ "]
      --secondary-prompt <SECONDARY_PROMPT>
          The shell secondary prompt to use in the asciicast output [default: "> "]
      --timeout <TIMEOUT>
          Maximum amount of time to let a shell command run before returning with an error [default: 30s]
      --overwrite
          Overwrite output file if it already exists
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version

Use autocast --help to see a more in-depth explanation of the CLI arguments. Also see their corresponding settings in full-example.yaml.

Non-default CLI arguments will override settings specified in the input YAML file.

Input YAML File

For examples, see example.yaml and demo.yaml. For an in-depth explanation of all configuration values, see full-example.yaml.

Instruction Kinds:

• Command
  • Normal shell command or control code.
  • Can be a single line or split across multiple lines.
  • Waits until the shell prompt is displayed to ensure the command has completed.
  • Optionally hidden from asciicast output.
• Interactive
  • Starts an interactive shell command like an editor or TUI app.
  • Requires a list of keys that are used to control the started command.
    • Keys are input in real time (including any waits) while output is continuously captured.
  • After all the keys are fed to the command, it must exit, and the shell returned to the prompt.
  • Like the normal shell command, it waits until the shell prompt is displayed before running the next instruction.
• Wait
  • Adds time between the output of the last instruction and the start of the next.
  • This time is only added in the asciicast output and does not increase the run time of autocast.
• Marker
  • Adds a marker to the asciicast output.
  • Markers are chapters that show in the asciinema web player.
• Clear
  • Adds output events to the asciicast output that will clear the terminal.

Contribution

Contributions/suggestions are very welcome and appreciated! Feel free to create an issue, discussion, or pull request. Especially in need of default configurations for other shells (zsh, fish, etc.) as I have no experience with shells other than bash.

Inspiration

• asciinema
• VHS
• asciinema_automation
• expectrl
  • Used as a dependency, but some of the top level functionality was reimplemented (specifically Session and ReplSession in ShellSession) for autocast's needs.

License

Autocast is licensed under the GNU General Public License v3.0 or later, see the license file for details.

autocast's Issues

Request: !Interactive - long strings

I don't know what the format of this would be, but I think the keys array could be improved by also allowing a string which would be treated a simple list of keys using the current typing speed, without any special parsing for waits or control codes.

This is would be easier to type and understand, and is a bit less verbose:

Maybe something like:

- !Interactive
  keys:
    - h
    - e
    - l
    - l
    - o
    - 2s
    - ^X
    - n

becomes

- !Interactive
  keys:
    - !Str hello
    - 2s
    - ^X
    - n

Loving autocast so far!

Hang with demo - debug mode/extra output?

Trying this out with demo.yaml, but autocast seems to hang after some small status output (reading lines etc.)

autocast demo.yaml demo.cast
Read from file: demo.yaml # hangs here

demo.cast remains empty.

Any way to enable extra logging to see what's going on?

Version 0.1.0 hangs

Hello - Thanks for creating this code!

I am running into an issue where autocast never produces an OUT_FILE, it just hangs instead:

autocast --overwrite example.yml example.cast
Read from file: example.yml

I've also tried demo.yml and full-example.yml (with and without --overwrite option) from your README with the same results. I'm running MacOS Ventura 13.4 (M2 chip). I normally use zsh, but setup a minimal ~/.bashrc since that is the default shell being used per the docs.

If you have any suggestions, I'd be grateful. Happy to provide more details about my setup if that would help. Thanks again. 😄

Demonstrating auto completion does not seem to be possible

I would like to use autocast to demonstrate my generic CLI script's auto
completion features.

As far as I understand this is currently not possible.
Control-I should send a tab character, so I tried to do it with this config.

- !Interactive
  command: 'cli '
  keys:
    - ^C
    - i
    - ^C
    - i

This does not work like I expected though. I think it is because it executes the
command before sending the key codes. It would be nice, if one could defer
execution with a flag, in which case the user would have to send a new line
character in the keys section to manually complete the command.
For example:

 !Interactive
 command: 'cli '
 defer_execution: true
 keys:
    - ^C
    - i
    - ^C
    - i
    - some_autocomletion_input
    - ^C
    - i
    - \n

Cheers!

Would this work with PowerSession-rs?

I haven't got a firm handle on how autocast gets the results it does, so perhaps this is a naive question, but would this tool possibly work with the repo https://github.com/Watfaq/PowerSession-rs which is an asciinema clone able to run on Windows?

---

Thanks a lot for this tool - I realised the need for something exactly like this when I started trying to set up a range of asciinema recordings recently for documentation I was sprucing up.

Create GitHub workflow/action that automatically re-generates a asciinema file (and .gif)

Use case

The problem this tool solves is that cumbersome re-generating of custom asciinema CLI shows once your CLI tool changes etc. This solves a very annoying task. It automates this.

What if we take this paradigm even further?
Can't we create a GitHub workflow to automate it after each change (or tag if CLI output rarely changes and you want to save resources etc.?) For this project it would be a good try?
Going even further, what if why not just create a GitHub Action, so other's can use this, too?

Solution

The GitHub Action should:

• generate a new asciinema file
• optionally upload/update it on the asciinema website
• generate a gif out of it (or is there some Asciinema or other good GitHub Action or so for this already?)

With https://github.com/EndBug/add-and-commit/ the files could in your workflow then automatically be committed in the repository and a bot would automatically update your preview.

Problem: Do asciinema links need to be replaced? If so, ideally it should do this, too – though that would be cumbersome obviously? But if not, the better, then a link can stay stable.

More built-in shell configurations

This is a tracking issue for adding more built-in shell configurations. For a shell to work with autocast, it must accept input on its stdin. The prompt should be changed to something unique so that autocast does not mistake something in a command's output as the prompt. See the bash defaults for an example. If you get a custom shell working, please comment with your configuration and I'll add it to autocast. Feel free to suggest other shells you would like to see built-in configurations for to be added to the list.

• zsh
• fish
• nu

Alternatives

In borgbackup/borg#8040 I asked some project maintainers to switch to your solution, but it appears to be kissing one important requirement: isolation e.g. in containers or VMs.

That said, that's okay for this project IMHO. Maybe it can be listed in the Readme though?

Alternatives mentioned:

At a quick glance autocast appears to be a tool with a similar purpose to TCL expect (which I used). Both allow automated control of software that requires a terminal emulator (TTY). Autocast appears to be more special-purpose. There is a chance a more special-purpose tool can be an improvement over a more general-purpose tool.

borgbackup/borg#8040 (comment)

Maybe add some doc?