termsnap

termsnap

Creates beautiful screenshots, videos, and GIFs based on terminal command output. With full local font and emoji support.

npx termsnap "lolcat -f <(figlet -f banner3 termsnap)"

Features

This project leverages Go-based terminal output proxy combined with web rendering technology to deliver pixel-perfect terminal screenshots.

• Interactive Terminal Support: Capture interactive terminal sessions through Go-based terminal output proxy
• Local Font & Emoji Support: Perfect rendering of your system fonts and emoji characters
• Customizable Themes: Extensive theme customization through configuration files
• Multiple Output Formats: Export as HTML, images (PNG/JPEG/WebP), animated GIFs, videos (MP4/AVI/MOV/WebM), or browser preview
• Animation: Generate animated HTML or video output with typing effects

Usage Examples

# Browser preview
npx termsnap "command" --animate --open

# Save as HTML file
npx termsnap "command" --html

# Save as screenshot
npx termsnap "command" --png

# Save as video
npx termsnap "command" --mp4 --fps 60

# Save as animated GIF
npx termsnap "command" --gif --gif-fps 20 --gif-scale 720

# Custom theme and decoration
npx termsnap "command" --open --theme "vitesse-light" --decoration

# Save as animated HTML file
npx termsnap "command" --animate

Output Formats

Generate your terminal output in multiple formats:

• HTML: Save as standalone HTML file with embedded styling
• Images: Export as PNG, JPEG, or WebP formats
• Animated GIFs: Export as optimized GIF with customizable frame rate and scale
• Videos: Export as MP4, AVI, MOV, or WebM formats with customizable frame rate
• Browser Preview: Open directly in browser (powered by Broz)

Theme Customization

termsnap supports termsnap.config.ts for persistent configuration and theme customization. You can:

• Use built-in themes (vitesse, catppuccin)
• Use remote themes from iTerm2-Color-Schemes VSCode directory
• Create custom themes in termsnap.config.ts

Remote Themes

You can use any theme from the iTerm2-Color-Schemes VSCode directory. If the theme name is not in the built-in list, termsnap will automatically attempt to download it from the repository:

# Use a remote theme (e.g., 0x96f)
npx termsnap "command" --theme "0x96f"

Animated Command Input

When using the --animate option to generate animated HTML output, you can customize the typing animation behavior through typedOptions configuration:

// termsnap.config.ts
import { defineConfig } from './src/index'

export default defineConfig({
  typedOptions: {
    speed: 100, // Typing speed in milliseconds per character
    initialDelay: 0, // Initial delay before starting to type
    pauseAfter: 500 // Pause duration after typing completes
  }
})

Configuration Options

Server Settings

• port - Server port (default: 3000)
• force - Force to download the theme from remote

Output Options

• dpi - Device pixel ratio for screenshot
• png - Generate png and save to file
• jpeg - Generate jpeg and save to file
• webp - Generate webp and save to file
• gif - Generate animated gif and save to file
• gifFps - Frames per second for gif output (default: 20)
• gifScale - Scale for gif output (default: 720)
• fps - Frames per second for video output (default: 60)
• mp4 - Generate mp4 video and save to file
• avi - Generate avi video and save to file
• mov - Generate mov video and save to file
• webm - Generate webm video and save to file
• html - Generate HTML template and save to file
• animate - Generate animated HTML template and save to file
• loop - Loop the animation for a given number of milliseconds
• open - Open browser after generating HTML template

Terminal Styling

• theme - Terminal theme (vitesse-dark, vitesse-light, catppuccin variants, etc.)
• colors - Custom terminal color configuration
• height - Terminal height
• width - Terminal width
• decoration - Draw window decorations (minimize, maximize, close buttons)
• cmd - Show command in the terminal
• typed - Typed command in the terminal

Font Configuration

• fontAspectRatio - Terminal font aspect ratio (default: 0.6)
• fontFamily - Terminal font family
• fontSize - Terminal font size
• fontWeight - Terminal font weight
• lineHeight - Terminal line height

Border & Layout

• borderRadius - Terminal border radius
• borderWidth - Terminal border width
• borderColor - Terminal border color
• boxShadow - Terminal box shadow
• padding - Terminal padding
• margin - Terminal margin

Typed Configuration

• speed - Typing speed in milliseconds per character
• initialDelay - Initial delay before starting to type
• pauseAfter - Pause after typing completes

Cache Management

termsnap caches downloaded binaries and remote themes to improve performance. You can manage the cache using the following command:

# Clean all cached files (binaries and themes)
npx termsnap cache:clean

This command will remove:

• Downloaded Go binaries used for terminal session capture
• Cached remote themes from iTerm2-Color-Schemes repository

Use this command if you're experiencing issues with cached files or want to free up disk space.

Acknowledgments

This project was inspired by:

• termshot - Creates screenshots based on terminal command output
• freeze - Generate images of code and terminal output 📸

Why termsnap?

I wanted a simple way to create screenshots for my CLI tools to include in README files. However, existing tools had limitations with fonts, emoji support, and interactive terminal sessions. This led me to create termsnap - a terminal screenshot tool that feels like recording your terminal sessions with perfect fidelity.

License

MIT License © jinghaihan