Make Your CLI Demos a Breeze With Zero Stress and Zero Mistakes

Learn how you can run beautiful, repeatable, scripted CLI demos and showcases with zero stress and zero mistakes

Photo by Joan Gamell on Unsplash

Running live demos can be stressful. You know what you want to say and show. You prepare the CLI commands you want to run to best showcase what you’ve built, but then you waste time typing long commands; you make typos; the commands fail or take too long to complete. Maybe they depend on an external system (network, APIs, cloud, etc.), and of course, it’s not cooperating while you’re running your live demo.

Here’s how you can avoid all of the above by scripting, automating, and recording your demos so that you never have to stress about showcasing again.

Note: All the scripts and code are made available in this repository.

The Script

It’s easy to forget some of the things you want to show or say during the showcase, so you might want to write a script — both in the “theatre” and “programming” sense.

Just writing things down and following this script can make a showcase much smoother, but why not go a step further and make it an actual runnable script?

There are a couple of tools you could use for this. We will talk about two — demo-magic and https://github.com/saschagrunert/demo.

The former is a simple yet powerful set of bash functions and helpers that you can use to automate your demos/showcases as a shell script. To install it, run the following script:

git clone https://github.com/paxtonhare/demo-magic.git
mkdir demo  # Create a working dir for showcase
cp demo-magic/demo-magic.sh demo/demo-magic.sh  # Copy the helpers

# Install "Pipe Viewer" for simulated typing
# MacOS:
brew install pv

# Ubuntu:
apt-get install pv

# Move to showcase directory and create your "script"
cd demo
touch sample.sh
chmod +x sample.sh

Now we need to write our script, which will live in the demo/sample.sh file:

#!/bin/bash

# Include the "demo-magic" helpers
source demo-magic.sh

DEMO_PROMPT="${GREEN}➜ ${CYAN}\W ${COLOR_RESET}"
TYPE_SPEED=30

function comment() {
  cmd=$DEMO_COMMENT_COLOR$1$COLOR_RESET
  echo -en "$cmd"; echo ""
}

clear

comment "# Simple commands:"
pe 'ps aux | head'
pe 'ls -l'

comment "# Print and execute immediately"
pei 'cat some-file'
echo

comment "# Long running:"
pe 'docker build -t some-app .'

comment "# Error prone (dependant on external factors like network):"
pe 'curl --silent -X GET https://httpstat.us/418 -H "Accept: application/json" | jq .'
pe 'curl --silent -i -X POST https://httpbin.org/status/204 --data "{'some':'data'}"'

comment "# Hard to type:"
pe 'openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout example.key -out example.crt -subj "/CN=example.com" -addext "subjectAltName=DNS:example.com,DNS:www.example.net,IP:10.0.0.1" 2>/dev/null'

comment "#  Enter interactive mode..."
cmd  # Run 'ls -l | grep example' to show result of 'openssl ...'

Let’s go over what’s going on here — we start by including the demo-magic.sh so that we can use its helper functions (pe, pei and cmd). Next, we configure the prompt and simulated typing speed, and we also add a helper function of our own — comment — which simply prints text without executing it, so we can describe the commands we're showing.

Then comes the actual script — after clearing the terminal, we run a series of commands using pe and pei. Both print and execute the specified command, but the former waits for enter, and the latter executes immediately. If you want to include an interactive section in your demo, then you can also use cmd command, which lets you type out and run a single command before proceeding with the rest of the script.

And running the above example would result in something like this:

demo-magic Example

The other tool I mentioned is https://github.com/saschagrunert/demo, which uses Golang to build the script instead of the shell (you decide whether that belongs to the pros or cons column). Therefore, to use it, we need to create a Golang project. First, create a go.mod file:

module cli-demo

go 1.20

And install the tool from GitHub:

go get github.com/saschagrunert/demo@latest

Then create a main.go file that will become your demo script:

package main

import (
   demo "github.com/saschagrunert/demo"
   "github.com/urfave/cli/v2"
)

func main() {
   d := demo.New()
   d.Add(simple(), "simple", "Simple commands demo")
   d.Run()
}

func simple() *demo.Run {
   r := demo.NewRun(
      "Simple commands demo",
   )
   r.Step(demo.S(
      "Simple commands:",
   ), nil)
   r.Step(nil, demo.S(
      "ls -l",
   ))
   r.Step(nil, demo.S(
      "cat some-file",
   ))

   return r
}

In main function, we instantiate the demo and add ( Add(...)) demo runs to it. In this case, we only add a single run named simple, but you can use the Add function multiple times. In the demo run function, we create individual steps using r.Step(demo.S(...)), where the first and second parameters represent comment and CLI command, respectively. Either of these can be omitted if you only want to print comment/command.

Now you can build it and run it with this command:

go build
./cli-demo --all

And again, a complete example would look like the following:

Golang Tool Example

To keep things concise and readable, I didn’t include the full code used to create the above GIF, but you can find it here.

One advantage of this tool over demo-magic are that it includes setup and teardown functions, so you can easily prepare and destroy the environment of your demo. It also produces an executable that can be useful for distributing the demo. On the other hand, though, this tool doesn't have an option for customizing prompts or changing the speed of simulated typing, With that said, the whole code is less than 300 lines so you could add these features quite easily.

Recording

Most of the time, you might be satisfied with a runnable script. You will use it once during a live demo/showcase and never touch it again. However, in some cases, you might want to (pre)record the demo and share it. For example, so you can add an example GIF to a GitHub repository. For that, you can use a tool called terminalizer.

The nice thing about this tool is that it doesn’t record an actual video of your screen/window, rather it generates a YAML file based on what you type in the terminal. This file can then be adjusted/fixed, so we can do some “post-processing” — such as removing frames — just by changing the generated YAML before rendering GIF from it.

To install it, run the following:

# You might need 'sudo'
npm install -g terminalizer

terminalizer init
# The global config directory is created at
# /home/martin/.terminalizer

After installing with npm, we initialize terminalizer which creates a global configuration file at /home/user/.terminalizer/config.yaml. You can leave the config as is, but I recommend adjusting some options:

frameDelay: 150
# If you want to force size of window
cols: 140
rows: 75

frameBox:
  type: floating
  title: <Demo Specific>  # or null
  style:
    backgroundColor: "#263238"
    border: 0px black solid

theme:
  background: "transparent"
  foreground: "#afafaf"
  cursor: "#c7c7c7"
  black: "#2E3436"
  red: "#CC0000"
  # ...

As I mentioned, terminalizer only records strokes, not the actual screen, so this config allows us to change the styling of the final render, including color scheme, window size, etc.

By default, terminalizer will use the same pauses between strokes/typing as was during recording, which might mean that there will be unnecessarily long or short pauses. To fix that, we can change the frameDelay value to a specific number of milliseconds between each frame.

Another configuration you might want to change is framebox, which sets the terminal window title, size, and style. Finally, I also like to set theme to the same color palette I use in the terminal.

If you want some inspiration, then my configuration can be found here.

With the global config ready, we can run terminalizer config, which will copy the default config into the current directory. We can then record our demo in this directory without making changes to the default config:

terminalizer record demo --config config.yaml

# ... perform the demo commands

# CTRL+D to stop recording...

# Successfully Recorded
# The recording data is saved into the file:
# /home/.../demo.yml

# ---------

terminalizer play demo

# https://github.com/faressoft/terminalizer/issues/29
# sudo chown -R <YOUR_USERNAME> /usr/lib/node_modules/terminalizer/render/
terminalizer render demo
# ...
# Successfully Rendered
# The animated GIF image is saved into the file:
# /home/martin/.../render1677937002675.gif

Running terminalizer record demo will start screen (keystroke) recording, and hitting CTRL+D will stop and save the results into ./demo.yaml. You can then use terminalizer play demo to replay the demo right in the terminal as if you were typing it. Afterward, when you're satisfied with the recording, you can run terminalizer render demo which will render a GIF using the style configuration in config.yaml.

To then combine the scripting and recording into one piece, you can do something like this (that is — my preferred workflow):

# ... Edit 'main.go'
go build
# OR
cp template.sh my-cool-demo.sh
# Edit 'my-cool-demo.sh'

# -----

# Start recording:
terminalizer record demo
# Start scripted demo:
./cli-demo --all -i
# OR
./my-cool-demo.sh
# ... Go through the demo
# CTRL+D
terminalizer play demo  # To check
# ... Adjust demo.yml
terminalizer render demo  # To render

The GIFs that this will produce can be pretty big — in my case, upwards of 40MBs — so you might want to use the --step N argument with the render command to skip some frames. Alternatively, you can also run it through https://gifcompressor.com/.

Finally, while rendering GIFs has been so far sufficient for me, you might also want to render videos, which terminalizer can't do. For that, I recommend checking out asciinema which renders output that is closer to a proper video format.

Conclusion

While the point of this article was to provide a way to make your showcases and demos a little less stressful and smoother, another big benefit of using these tools is better quality — running a cool, impressive, fancy demo can make a big difference. Having a fancy showcase can keep the audience engaged and can help you leave a good impression even if you’re showcasing something boring.

Why I Will Never Use Alpine Linux Ever Again

Want to Connect?

This article was originally posted at martinheinz.dev.