shellshot 0.4.0

Transform your command-line output into clean, shareable images with a single command.
Documentation

Crates.io Build Status Dependency Status Documentation License MSRV codecov

Transform your command-line output into clean, shareable images with a single command.

Shellshot is a fast, cross-platform tool written in Rust that captures terminal sessions and transforms them into polished screenshots. Perfect for documentation, presentations, social media, or showcasing terminal workflows.

Features

  • Beautiful Rendering: High-quality image generation with customizable window decorations
  • ANSI Support: Correctly renders ANSI colors, styles, and formatting.
  • Clipboard Integration: Copy screenshots directly to your clipboard with one flag
  • Command Execution: Execute commands and capture their output automatically
  • Customizable: Adjust window decorations, colors, padding, and output filename.
  • Cross-Platform: Works on Windows and Linux

Installation

cargo install shellshot

Usage Examples

Usage Notes

  • On Windows, some commands may require --shell to execute correctly (forces execution inside Bash on Windows).
  • Either --output <file> or --clipboard must be specified, otherwise shellshot will fail.

Basic Usage

On Linux, commands usually work directly:

# Linux

shellshot -o out.png echo "Hello from ShellShot!"

On Windows, some commands (like echo) are shell builtins, not executables. You need to force execution inside a shell using --shell

# Windows

shellshot --shell -o out.png echo "Hello from ShellShot!"

This will execute the command, capture its output, and generate an image file named out.png in the current directory.

echo example

ASCII Art Demo

Demonstrating ShellShot’s full support for ANSI colors and text styles:

ascii example

Command Options

--shell — Force execution inside a shell

The --shell flag forces Shellshot to execute the command inside a shell instead of running it directly. This allows you to pass your command as a single string, enabling more complex shell operations like pipes, redirections, or command chaining.

Why this is needed:

  • Linux/macOS: Forces execution inside sh. Most commands are either executables or shell builtins, so they usually run correctly without --shell. Use it if you want consistent shell behavior (e.g., for complex scripts or shell operators like pipes and redirects).
  • Windows: Forces execution inside Bash. Many common commands like echo or dir are shell builtins, not standalone executables. Using --shell ensures these commands run correctly and supports more complex command strings.

Example:

# Linux — works directly

shellshot -o out.png echo "Hello from ShellShot!"


# Windows — must use --shell because echo is a shell builtin

shellshot --shell -o out.png echo "Hello from ShellShot!"

--no-decoration

Remove window decorations (title bar and control buttons):

shellshot -o out.png --no-decoration rustc --version

--decoration <style> / -d

Specify the decoration style (default: classic):

# Linux

shellshot -o out.png --decoration classic ls --color=always

# Windows

shellshot --shell -o out.png --decoration classic dir

--theme <file|url>

Shellshot supports custom themes (Base16 .yaml or iTerm2 .itermcolors) that affect ANSI color rendering.

Popular sources for themes:

You can load themes from a local path or a URL:

# Local Base16 theme

shellshot --theme path/to/theme.yaml -o out.png rustc --version


# From URL (iTerm2)

shellshot --theme https://example.com/theme.itermcolors -o out.png rustc --version

--output / -o

Specify a custom output filename:

shellshot --output out.png cargo build

shellshot -o screenshots/out.png cargo test

--clipboard

Copy the screenshot directly to your clipboard:

shellshot --clipboard git status

--width / -W et --height / -H

Specify the final image dimensions in columns (width) and rows (height), or use 'auto' (default: auto):

# Linux

shellshot -o out.png --width 70 --height 50 echo "Hello, world!"

# Windows

shellshot --shell -o out.png --width 70 --height 50 echo "Hello, world!"

--timeout / -t

Set a timeout in seconds for command execution:

shellshot -o out.png --timeout 5 ping -c 10 localhost

Examples

shellshot -o out.png cargo --version

shellshot --clipboard git log --oneline -5

shellshot -o out.png --no-decoration python --version


# Linux

shellshot -o out.png echo "Hello, Shellshot!"

shellshot -o out.png --decoration classic ls --color=always


# Windows

shellshot --shell -o out.png echo "Hello, Shellshot!"

shellshot --shell -o out.png --decoration classic dir

Support

For issues and questions:

License

This project is licensed under either of

at your option.