Project

shellfie

0.0
The project is in a healthy, maintained state
shellfieydah/shellfieHomepageDocumentationSource CodeBug TrackerWiki
Generate beautiful terminal screenshot-style PNG images and animated GIFs from YAML configuration files. Perfect for README files and documentation.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
658
Stars
2
Forks
0
Watchers
1
 Releases
Current version
1.0.0
Total releases
3
First release
2026-01-12
Latest release
2026-05-19
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-03-06
Reverse Dependencies
0

 Dependencies

Runtime

mini_magick
>= 4.12
 Project Readme

shellfie

Generate terminal screenshot-style images and animations from YAML.

shellfie

Gem Version Downloads Ruby Version License

shellfie demo

Install

Requirements:

  • Ruby 3.0+
  • ImageMagick 7+
brew install imagemagick
gem install shellfie

For Bundler:

gem "shellfie"

Quick Start

Create terminal.yml:

theme: macos
title: "Terminal - zsh"

window:
  width: 600
  padding: 20

lines:
  - prompt: "$ "
    command: "echo hello"
  - output: "hello"

Generate an image:

shellfie generate terminal.yml -o terminal.png

Use shf as a short alias for shellfie.

CLI

shellfie generate config.yml -o output.png
shellfie generate config.yml -o demo.gif --animate
shellfie generate config.yml -o output.svg --format svg
shellfie generate config.yml -o output.png --scale 2 --no-shadow
shellfie generate config.yml -o output.png --no-header
shellfie validate config.yml
shellfie themes
shellfie init

Common generate options:

Option Description
-o, --output PATH Output path
-t, --theme NAME Override theme
-a, --animate Render animation
-s, --scale FACTOR Output scale: 1, 2, or 3
-w, --width PIXELS Override window width
--format FORMAT png, gif, svg, webp, or apng
--fps FPS Override animation typing FPS
--overflow MODE clip, wrap, or scroll
--no-shadow Disable shadow
--transparent Transparent background
--no-header Headless output
--force Overwrite existing files

Static output supports png, svg, and webp. Animated output supports gif, webp, and apng.

Configuration

Static content uses lines:

theme: macos
title: "Terminal"

window:
  width: 600
  padding: 20
  visible_lines: 8
  overflow: clip

font:
  family: Monaco
  size: 14
  line_height: 1.4

lines:
  - prompt: "$ "
    command: "gem install shellfie"
  - output: |
      Successfully installed shellfie
      1 gem installed

Animations use frames:

theme: macos
title: "Demo"

animation:
  typing_speed: 50
  command_delay: 500
  cursor_blink: true
  loop: true
  palette: global
  dither: true
  scroll_easing: ease_out

frames:
  - prompt: "$ "
    type: "echo hello"
    delay: 500
  - output: "hello"
    delay: 1000

Useful top-level keys:

Key Purpose
theme macos, ubuntu, windows, or custom
color_scheme Built-in color scheme such as dracula
colors Theme color overrides
window Size, padding, wrapping, clipping, scrolling
font Font family, size, line height
animation Typing speed, delays, loop, palette, easing
cursor Cursor style and color
headless Hide window chrome
lines Static terminal content
frames Animated terminal content

ANSI colors and styles are supported in prompt, command, and output, including 8-color, bright, 256-color, and RGB escape sequences.

Themes

Built-in window themes:

  • macos
  • ubuntu
  • windows

Headless output removes window chrome:

headless: true

or:

shellfie generate config.yml -o output.png --no-header

Development

bundle install
bundle exec rspec

License

MIT