Skip to main content

Crate shellshot

Crate shellshot 

Source
Expand description

Shellshot

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.

Structs§

Args
Command-line arguments for shellshot

Enums§

WindowDecorationType
Type of window decoration to apply around the rendered content

Functions§

run_shellshot
Main entry point for shellshot logic