Demos and Playgrounds
Relevant source files
The following files were used as context for generating this wiki page:The demos directory provides a structured environment for creating, managing, and documenting various demonstrations of the caro CLI tool. It contains scripts for recording terminal sessions, generating animated GIFs, and dedicated playground environments for showcasing specific features. The primary goal is to produce assets for presentations, website content, and documentation.
Sources: demos/ORGANIZATION.md, demos/README.md
Demo Infrastructure
The demo system is organized into several key directories, each serving a distinct purpose. This structure separates recording scripts, output files, documentation, and isolated testing environments.
Sources: demos/ORGANIZATION.md:5-20
Directory Structure
The following diagram illustrates the organization of the demos directory.
Sources: demos/ORGANIZATION.md:5-20
| Directory | Purpose |
|---|---|
asciinema/ | Contains executable shell scripts (.sh) for recording demos and their resulting session recordings (.cast). |
vhs/ | Holds VHS configuration files (.tape) used to generate animated GIFs (.gif) from terminal commands. |
docs/ | A repository for all documentation related to the demos. |
playground/ | A Node.js web application environment for demonstrating web-related interactions. |
sysadmin-playground/ | An environment tailored for server operations and system administration demos. |
Sources: demos/ORGANIZATION.md:5-20, demos/demo_playground/README.md:3-5
Prerequisites
To use the full capabilities of the demo system, the following tools are required:
asciinema: For recording terminal sessions.agg: A tool for creating animated GIFs fromasciinemarecordings.- A compiled
carobinary with theembedded-mlxfeature.
Sources: demos/ORGANIZATION.md:53-56
Demo Management Script
The demo.sh script is the central tool for managing the entire demo lifecycle, from recording to playback and asset generation.
Sources: demos/demo.sh, demos/ORGANIZATION.md:22-40
Workflow
The script automates several key actions based on user commands. The general workflow is depicted below.
Commands
The script accepts several commands to perform different actions on the defined demos.
| Command | Description | Example |
|---|---|---|
list | Lists all available demo scripts found in the asciinema directory. | ./demo.sh list |
record <name> | Records a specific demo using asciinema rec. The output is saved as a .cast file. | ./demo.sh record vancouver |
play <name> | Plays back a previously recorded .cast file. | ./demo.sh play website |
gif <name> | Generates an animated GIF from a .cast file using agg. | ./demo.sh gif vancouver |
upload <name> | Uploads a .cast file to asciinema.org. | ./demo.sh upload website |
record-all | Iterates through all available demos and records each one. | ./demo.sh record-all |
Sources: demos/demo.sh:10-101, demos/ORGANIZATION.md:25-40
Predefined Demos
The repository includes several predefined demo scripts, each tailored for a specific audience and purpose.
| Demo Name | Purpose | Duration | Audience | Content Focus |
|---|---|---|---|---|
vancouver | For the Vancouver.Dev community event presentation. | ~60 seconds | Local developers | Full feature showcase. |
website | For the hero section of the caro.sh homepage. | ~30 seconds | Website visitors | A quick and impressive feature highlight. |
sysadmin | For a technical operations audience. | ~45 seconds | SysAdmins, DevOps, SREs | Log analysis and operational tasks. |
Sources: demos/ORGANIZATION.md:42-51
Example Demo Script: website-hero-demo.sh
This script is designed to create a short, visually appealing demo for the project's website. It uses comments with a special # ➤ prefix to simulate typed commands, which are then executed by the run function within the script. This creates a clean, automated, and repeatable recording.
#!/bin/bash
# shellcheck disable=SC2016
# ... (helper functions) ...
# ➤ caro "find all video files larger than 1GB and show their disk usage"
run 'caro "find all video files larger than 1GB and show their disk usage"'
# ➤ caro "compress all .log files in the current directory into a single archive named logs.tar.gz"
run 'caro "compress all .log files in the current directory into a single archive named logs.tar.gz"'
# ➤ caro "show me the 5 largest directories in my home folder"
run 'caro "show me the 5 largest directories in my home folder"'
Sources: demos/asciinema/website-hero-demo.sh
Playgrounds
To ensure demos are run in a clean and predictable state, dedicated playground environments are used.
demo_playground
This is a simple Node.js application environment. It is used for demos that require a web context, such as interacting with a local server or web-based tools. The README.md file for this playground contains instructions to install dependencies with npm install and start the application with npm start.
Sources: demos/demo_playground/README.md:3-9, demos/ORGANIZATION.md:18-19
sysadmin-playground
This environment is set up for demos targeting system administrators and DevOps engineers. It likely contains sample log files, system configurations, or other artifacts needed to showcase caro's capabilities in an operational context.
Sources: demos/ORGANIZATION.md:20-21