How to use the command 'vhs' (with examples)
The ‘vhs’ command is a powerful tool designed to simplify the process of creating GIFs from terminal sessions. By leveraging tape files, ‘vhs’ can record your terminal input and output, validate the syntax of these files, convert them into GIFs, and even publish them online for easy sharing. This can be particularly useful for software developers, educators, or technical writers who need to demonstrate command-line procedures or workflows. ‘VHS’ provides a clean and efficient way to capture and share these demonstrations without the need for complex video editing software.
Use case 1: Create a tape file
Code:
vhs new path/to/file.tape
Motivation:
Creating a tape file is the first step in documenting a terminal session. A tape file acts as a script or blueprint that tells ‘vhs’ what commands you want to record. This is perfect for setting up a series of steps you want to display in a GIF without needing to execute them immediately. It’s akin to drafting a screenplay before filming a movie.
Explanation:
vhs: This invokes the VHS tool, signaling that you’re about to perform an operation related to creating GIFs from terminal sessions.new: This subcommand tells VHS to create a new tape file.path/to/file.tape: This argument specifies the location and name for the new tape file. You can choose any directory and filename that suits your organizational needs.
Example output:
A new tape file is created at the specified path, ready for you to edit and add your terminal commands.
Use case 2: Record inputs to a tape file
Code:
vhs record > path/to/file.tape
Motivation:
Recording inputs directly to a tape file is like capturing a live session. This is useful when you want to document a workflow as you actively work through it on the terminal, allowing you to capture actual command inputs instead of scripting them beforehand.
Explanation:
vhs: The command initiates the use of the VHS tool.record: This subcommand starts the recording of terminal inputs.>: This symbol indicates redirection of the output, in this case, to a file.path/to/file.tape: This specifies the file where the recorded session will be stored.
Example output:
User’s terminal inputs during the session get recorded into the tape file at the specified path until the session is terminated.
Use case 3: Record inputs to a tape file using a specific shell
Code:
vhs record --shell shell > path/to/file.tape
Motivation:
Sometimes, specific workflows require the use of a particular shell (e.g., bash, zsh, etc.). Recording with a specific shell ensures that the tape accurately represents the session as it would occur in that shell, accounting for any shell-specific syntax or features.
Explanation:
vhs: Calls the VHS tool to perform the following operation.record: Induces the tool’s recording mode.--shell shell: Specifies which shell to use for the session. Replace ‘shell’ with your shell of choice, like ‘bash’ or ‘zsh’.>: Redirects the session output into the specified file.path/to/file.tape: Indicates the file where the recording will be saved.
Example output:
The recording specifically captures the session as it would occur in the chosen shell, stored in the designated file.
Use case 4: Validate the syntax of a tape file
Code:
vhs validate path/to/file.tape
Motivation:
Validating a tape file ensures that the commands within it are error-free and correctly formatted before proceeding to create a GIF. This step helps prevent errors that could arise during GIF generation due to issues within the tape file.
Explanation:
vhs: Begins the VHS command sequence.validate: This subcommand prompts VHS to check the tape file for syntax errors.path/to/file.tape: The path to the tape file that needs validation.
Example output:
The tool outputs a message indicating whether the tape file’s syntax is correct or if there are errors that need addressing.
Use case 5: Create a GIF from a tape file
Code:
vhs < path/to/file.tape
Motivation:
Once your tape file is set with the desired commands, converting it into a GIF makes it easy to share a visual representation of your terminal session. GIFs are universally supported and easy to embed in documents, websites, and more.
Explanation:
vhs: Initiates the use of the VHS tool.<: This symbol indicates input redirection, with VHS taking instructions from the specified tape file.path/to/file.tape: The tape file that contains the session to convert into a GIF.
Example output:
A GIF is generated based on the tape file’s content, depicting the terminal session visually.
Use case 6: Publish a gif to https://vhs.charm.sh
Code:
vhs publish path/to/file.gif
Motivation:
Publishing a GIF online provides an easy way to distribute and share your terminal session recordings with a broader audience, enabling quick access via a shareable link.
Explanation:
vhs: Starts the VHS tool.publish: This command uploads the GIF to the VHS publishing service.path/to/file.gif: Specifies the GIF file to be published.
Example output:
The system provides a URL where others can view the published GIF, enabling easy sharing.
Conclusion:
The ‘vhs’ command is an invaluable tool for anyone looking to document, validate, and share terminal processes effectively through GIFs. Each of these use cases showcases the versatility of ‘vhs’ in recording, editing, and distributing terminal sessions. Whether you’re creating a comprehensive software tutorial or a simple task demonstration, ‘vhs’ streamlines the creation and sharing process, making it accessible for all users, regardless of their technical expertise.
