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]
Arguments:
Input file to create the asciicast file with
Output asciicast file
Options:
--width
Terminal width
--height
Terminal height
-t, --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
```</p>
<p>Use <code>autocast --help</code> to see a more in-depth explanation of the CLI arguments. Also see their corresponding settings in <a href="./full-example.yaml">full-example.yaml</a>.</p>
<p>Non-default CLI arguments will override settings specified in the input YAML file.</p>
<h3>Input YAML File</h3>
<p>For examples, see <a href="./example.yaml">example.yaml</a> and <a href="./demo.yaml">demo.yaml</a>. For an in-depth explanation of all configuration values, see <a href="./full-example.yaml">full-example.yaml</a>.</p>
<p>Instruction Kinds:</p>
<ul>
<li>Command
<ul>
<li>Normal shell command or control code.</li>
<li>Can be a single line or split across multiple lines.</li>
<li>Waits until the shell prompt is displayed to ensure the command has completed.</li>
<li>Optionally hidden from asciicast output.</li>
</ul></li>
<li>Interactive
<ul>
<li>Starts an interactive shell command like an editor or TUI app.</li>
<li>Requires a list of keys that are used to control the started command.
<ul>
<li>Keys are input in real time (including any waits) while output is continuously captured.</li>
</ul></li>
<li>After all the keys are fed to the command, it must exit, and the shell returned to the prompt.</li>
<li>Like the normal shell command, it waits until the shell prompt is displayed before running the next instruction.</li>
</ul></li>
<li>Wait
<ul>
<li>Adds time between the output of the last instruction and the start of the next.</li>
<li>This time is only added in the asciicast output and does not increase the run time of autocast.</li>
</ul></li>
<li>Marker
<ul>
<li>Adds a marker to the asciicast output.</li>
<li>Markers are chapters that show in the asciinema web player.</li>
</ul></li>
<li>Clear
<ul>
<li>Adds output events to the asciicast output that will clear the terminal.</li>
</ul></li>
</ul>
<h2>Contribution</h2>
<p>Contributions/suggestions are very welcome and appreciated!
Feel free to create an <a href="https://github.com/k9withabone/autocast/issues">issue</a>, <a href="https://github.com/k9withabone/autocast/discussions">discussion</a>, or <a href="https://github.com/k9withabone/autocast/pulls">pull request</a>.
Especially in need of default configurations for other shells (zsh, fish, etc.) as I have no experience with shells other than bash.</p>
<h2>Inspiration</h2>
<ul>
<li><a href="https://asciinema.org/">asciinema</a></li>
<li><a href="https://github.com/charmbracelet/vhs">VHS</a></li>
<li><a href="https://github.com/PierreMarchand20/asciinema_automation">asciinema_automation</a></li>
<li><a href="https://crates.io/crates/expectrl">expectrl</a>
<ul>
<li>Used as a dependency, but some of the top level functionality was reimplemented (specifically <a href="https://docs.rs/expectrl/latest/expectrl/session/struct.Session.html"><code>Session</code></a> and <a href="https://docs.rs/expectrl/latest/expectrl/repl/struct.ReplSession.html"><code>ReplSession</code></a> in <code>ShellSession</code>) for autocast's needs.</li>
</ul></li>
</ul>
<h2>License</h2>
<p>Autocast is licensed under the <a href="https://www.gnu.org/licenses/gpl-3.0.en.html">GNU General Public License v3.0</a> or later, see the <a href="./LICENSE">license</a> file for details.</p>
</body></html>