termshot

Termshot: Generate Beautiful Terminal Screenshots from Your Console Output

Generate beautiful screenshots of your terminal, from your terminal.

Example at a glance: a playful demonstration that mirrors the vibe of real-world terminal art. A simple command can unleash a polished image that looks like a windowed application, making your terminal output suitable for documentation, marketing, or social media. The project embraces a practical philosophy: you don’t need to manually recreate a terminal screen; you can capture exactly what your commands emit and render it as a high-fidelity image.

A quick taste of the featured workflow is shown in a compact shell snippet:

termshot lolcat -f <(figlet -f big termshot)

This command yields a screenshot that showcases the power of termshot to translate textual terminal output into a visually compelling image. The accompanying example image demonstrates the result: a stylized console window containing large, decorative text.

In this blog post, we’ll explore what termshot is, how to install it, how to use it effectively, and why you might want to integrate it into your documentation, demos, or marketing assets. We’ll also walk through a few practical examples and discuss the flags that shape the appearance and behavior of the generated screenshots.

Installation: Getting Termshot on Your System

Termshot provides a straightforward installation path for macOS and Linux users via Homebrew, which is a popular package manager that simplifies tool setup. The installation command is concise and designed to be easy to remember:

brew install homeport/tap/termshot

For those who prefer not to rely on a package manager, the project maintains pre-compiled binaries for Darwin (macOS) and Linux, accessible via the Releases page. This means you can download a ready-made binary, place it in your PATH, and begin capturing terminal output without building from source.

What makes termshot stand out is not merely its ability to take a screenshot, but its fidelity. It reads the ANSI escape codes—often described as “rich text”—that terminal programs emit, and it uses those cues to render a faithful representation of the terminal’s appearance. Unlike some tools that simply apply generic syntax highlighting to a block of text, termshot interprets the actual color, style, and structure reflected by the terminal content, yielding a high-fidelity image that resembles a real windowed terminal.

Usage: How to Capture Terminal Output as an Image

At its core, termshot reads the console output produced by running a command and renders that output into an image file. This makes it a natural companion to common terminal tasks, such as listing files, showing process trees, or running build commands. The typical flow looks like this:

termshot ls -a

Running this will produce an image file named out.png in your current directory by default. The output image captures the terminal’s content, including the text, colors, and line breaks as they would appear in a live terminal session.

If your target command includes pipes or other shell constructs, you may encounter ambiguity in parsing. In such cases, wrap the command in quotes to ensure correct interpretation:

termshot -- "ls -1 | grep go"

This approach preserves the intended pipeline while still allowing termshot to capture the resulting output accurately. The result is a cohesive screenshot that reflects the exact command and its output, or simply the command’s output if you choose not to display the command inline.

Practical visuals accompany the usage examples to illustrate typical results:

• Basic termshot example:

• Termshot with pipes:

• A termshot image that shows the command itself:

• An example featuring a figlet-style banner:

A note about the visuals: the images above reflect how termshot renders the terminal content into a polished image, including window-like decorations, color schemes, and padding that contribute to a professional, publication-ready look.

Flags: Controlling the Look and Feel

Termshot offers a rich set of flags that allow you to tailor the appearance of the screenshot to fit your project’s style. These options are grouped by their focus: aesthetic controls, output targets, and content-related choices.

Flags to control the look

• --show-cmd / -c Include the target command in the screenshot. This is useful when you want to document exactly what was executed, not just the resulting output. Example:

  termshot --show-cmd -- "ls -a"

The resulting image will display the command itself along with its output, making it clear what was run.

• --columns / -C Enforce a wrap after a specified number of columns. This is handy when you want to constrain the horizontal width of the image to fit a particular layout or page.

• --no-decoration Do not draw window decorations (minimize, maximize, and close buttons). This is useful when you want a clean, minimal look for documentation or slides.

• --no-shadow Do not draw a window shadow. A smaller footprint image can be desirable for some designs.

• --margin / -m Add extra space around the window. This helps isolate the terminal content from the edges of the image, which can improve readability in dense layouts.

• --padding / -p Add extra space around the content inside the window. Padding creates airiness and can enhance legibility in screenshots with colorful or dense output.

Flags for output-related settings

• --clipboard / -b Copy the screenshot to the OS clipboard instead of writing a file. This is platform-dependent, so check your environment to see if the flag is available. It’s convenient for quick sharing without cluttering your filesystem.

• --filename / -f Specify a path where the screenshot should be generated. Absolute paths or relative paths (which resolve against the current working directory) are supported. If not provided, the default is out.png. Examples:

• termshot -- "ls -a" # defaults to /out.png

• termshot --filename my-image.png -- "ls -a"

• termshot --filename screenshots/my-image.png -- "ls -a"

• termshot --filename /Desktop/my-image.png -- "ls -a"

Flags to control content

• --edit / -e Edit the output before generating the screenshot. This opens the rich text output in your configured editor (with vi as a fallback) via $EDITOR. Use this to remove unwanted or sensitive content.

• Example:

  termshot --edit -- "ls -a"

This is especially helpful when the terminal content includes verbose logs or sensitive data that you don’t want in the final image.

Miscellaneous flags

• --raw-write Write command output as-is into the file specified by --filename. No screenshot is created in this mode. The --filename flag has no effect here.

• --raw-read Read input from a provided file instead of executing a command. In this mode, no pseudo-terminal is created to run a command, and the --show-cmd and --edit options are not applicable.

• --version / -v Print the version of termshot installed.

• Example:

  termshot --version
  termshot version 0.2.5

Multiple commands and interactive use

Termshot is designed to work with a live command stream via a pseudo-terminal. For advanced workflows, you can invoke a fully interactive shell, run several commands, and capture the entire session. The screenshot is produced when the shell session ends. This capability enables you to document complex interactions, pipelines, or build processes in a single, cohesive image.

• Example:

  termshot /bin/zsh

This launches an interactive shell; you can type a sequence of commands, observe the live transcript, and terminate the session to generate a final screenshot that captures the entire flow.

Caveats and ongoing work

It’s important to recognize that termshot is a work in progress. While a large portion of ANSI sequences can be parsed, there are commands and programs in existence whose output cannot be parsed correctly yet. Additionally, commands that reset the cursor position can create issues in rendering. The project continues to evolve with the goal of broad compatibility and improved accuracy across diverse terminal tools and color schemes.

Why termshot matters: use cases and benefits

• Documentation that feels authentic: By capturing the exact terminal output, you provide readers with a faithful representation of how a command behaves, including progress indicators, color cues, and line-wrapped content.

• Marketing and social content: The polished, windowed terminal visuals lend themselves to blog banners, GitHub READMEs, and social media posts that require consistent, eye-catching aesthetics.

• Education and tutorials: Instructors can demonstrate commands and outputs with accurate formatting, ensuring learners focus on the content rather than the layout.

• Developer workflows: Share CI-run log snippets or build results as crisp images in reports or release notes, avoiding screenshot invasions into terminal windows.

Visual references and examples

In addition to the code snippets and textual descriptions, termshot demonstrates several concrete visuals that illustrate the tool’s capabilities:

• The basic termshot image demonstrates how a standard directory listing can be captured within a stylized window, with colors and spacing that mimic an actual terminal session.

• A variant showing the command itself, as controlled by the --show-cmd flag, helps readers understand the relationship between the executed command and its output.

• A pipes example illustrates how termshot handles more complex shell constructs, such as pipelines, while preserving the intended output.

• A figlet-style banner example showcases how the tool can combine decorative text with the actual terminal output, yielding images that are both informative and visually striking.

What you can customize in practice

• The overall appearance: window decorations, margins, and padding to control whitespace and framing.

• The content: whether to show the command, whether to include raw output, and whether to limit width with a column constraint.

• The output destination: local files or clipboard, depending on the platform and the flags you choose.

• The content source: either execute a command, or read from a file using raw-read mode, which bypasses the shell entirely.

Tips for creating effective screenshots

• Choose commands with clear color cues: many terminal programs use ANSI color sequences to distinguish information. Termshot leverages these colors to produce faithful visuals.

• Keep the content readable: a modest margin and padding often improves legibility, especially when embedding screenshots in documentation or slides.

• Use a wrapping strategy that matches your layout: the --columns flag helps ensure that images align with your page design and do not overflow horizontal space.

• When sharing publicly, consider sensitivity: if the command output includes sensitive or private data, the --edit flag or --raw-read mode lets you sanitize or customize the content before rendering.

A brief look at the historical and practical context

Termshot is designed with an appreciation for pragmatic, developer-friendly tooling. It sits in a space alongside web-based tools that generate screenshots from code or content, but it differentiates itself by respecting actual terminal semantics. Rather than applying generic highlighting to an arbitrary text sample, termshot interprets the terminal's ANSI sequences, producing a high-fidelity representation that’s ideal for both technical and marketing purposes.

For teams that maintain documentation or share ongoing project progress, the ability to generate consistent visuals with minimal effort can be a real time-saver. It reduces the friction involved in capturing, formatting, and updating screenshots for complex terminal workflows. The result is a streamlined workflow where a developer can run a command, apply a few options for styling, and publish the resulting image in minutes rather than hours.

Notes and ongoing work

As with any actively developed open-source project, termshot continues to improve. The maintainers acknowledge that certain edge cases remain challenging, and there are commands whose outputs pose parsing difficulties. If you encounter a scenario where termshot does not render as expected, consider contributing a bug report or proposing a fix. Community input helps drive enhancements that broaden compatibility and reliability.

Conclusion: A tool worth trying for terminal-focused visuals

Termshot fills a niche that blends practicality with aesthetics. It enables you to produce precise, publication-quality images of terminal output with minimal overhead. From documentation to marketing assets, the ability to render a terminal window—complete with its own decorations, padding, and color fidelity—opens up new possibilities for presenting command-driven work. The combination of straightforward installation, a robust set of flags, and support for both single commands and interactive shells makes termshot a compelling option for developers who care about the presentation of terminal output.

If you’re curious about the exact command-line behavior and want to see how your own commands translate into screen captures, give termshot a try. Start with a simple example like listing files in a directory, then experiment with options such as --show-cmd, --columns, and --padding to dial in the look you want. And if you’re preparing a project page, a README, or a blog post, you’ll appreciate how quickly you can generate consistent visuals that communicate clearly and look professional.

Important caveat: the project’s current status

This project is a work in progress. Although a large portion of ANSI sequences can be parsed, there are certainly commands that create output that cannot yet be parsed accurately. Also, commands that reset the cursor position are known to create issues. As development continues, termshot aims to broaden compatibility and improve rendering fidelity across a wider range of terminal programs and scenarios.

Images included from the Input

• Example figlet-based screenshot:

• Basic termshot result:

• Termshot with pipes:

• Terminology and command-output display:

Bonus: a quick reference for commands used in examples

• Basic listing:

• Command: ls -a

• Purpose: reveal all files, including hidden ones, in the current directory.

• Piping in terminal:

• Command: ls -1 | grep go

• Purpose: show a simple filtered list; demonstrates how to handle pipelines within termshot’s quoting approach.

• Decorative banner:

• Command: termshot lolcat -f <(figlet -f big termshot)

• Purpose: creates a stylized screenshot that blends decorative typography with actual command output, illustrating creative space for banners and marketing visuals.

If you’re exploring termshot for the first time, start with the straightforward scenarios described above, then progressively introduce flags to tailor your screenshots. The combination of command fidelity, customization options, and straightforward installation makes termshot a practical addition to any developer’s toolkit for producing polished terminal visuals. And as the project matures, more features and improved parsing will further reduce any remaining gaps between terminal reality and its image representation.

End note: usage, exploration, and contribution

• To capture a single command’s output:
• Example: termshot ls -a
• To include the command in the image:
• Example: termshot --show-cmd -- "ls -a"
• To adjust the image’s size and padding:
• Use --columns, --margin, and --padding as appropriate.
• To save or share quickly:
• Use --filename to direct the output to a specific path, or --clipboard on supported platforms.

This blog post has walked you through the core ideas behind termshot, its installation path, typical workflows, and the flag-driven customization that makes it versatile for various contexts. By turning terminal transcripts into polished visuals, termshot helps teams document, showcase, and communicate command-line work with clarity and style.

And with that, you’re ready to begin experimenting with termshot, leveraging its capabilities to produce impressive, publication-ready terminal screenshots that faithfully reflect your commands and their outputs.