shellfie

Take a shell selfie.
Your terminal output deserves better than a blurry screenshot.

import shellfie, { themes } from "shellfie";
import { writeFileSync } from "node:fs";

const script = `
#!/bin/bash

echo "Hello World!"
`;

const svg = shellfie(script, {
  template: "macos",
  theme: themes.draculaPro,
  title: "Syntax highlighting",
  watermark: "\x1b[38;5;242mGenerated by shellfie\x1b[0m",
});

writeFileSync("highlight.svg", svg);

| Feature | shellfie | carbon-now-cli | svg-term | termtosvg | | --------------------------- | -------- | -------------- | -------- | --------- | | Zero dependencies | ✅ | ❌ | ❌ | ❌ | | No native bindings | ✅ | ❌ | ❌ | ❌ | | No headless browser | ✅ | ❌ | ✅ | ✅ | | Full ANSI support | ✅ | ✅ | ✅ | ✅ | | 24-bit true color | ✅ | ✅ | ❌ | ✅ | | Runs in browser | ✅ | ❌ | ❌ | ❌ | | Synchronous API | ✅ | ❌ | ❌ | ❌ | | Built-in Syntax hightligher | ✅ | ❌ | ❌ | ❌ |

Why SVG?

✅ Infinitely scalable — pixel-perfect at any zoom level, retina-ready by default.
✅ Selectable text — copy code directly from the image.
✅ Embeddable everywhere — high quality embedding in READMEs, docs, blogs, everywhere.
✅ Tiny files — 2-10KB vs blurry 500KB+ PNGs.
✅ No rendering pipeline — runs anywhere JavaScript runs.

Install

npm install shellfie

Usage

import shellfie from "shellfie";

const svg = shellfie(terminalOutput, {
  template: "macos",
  title: "npm test",
});

Browser

<script type="module">
  import shellfie from "https://esm.sh/shellfie";

  const svg = shellfie("\x1b[32m$ npm test\x1b[0m\nAll tests passed!", {
    template: "macos",
    title: "terminal",
  });

  document.body.innerHTML = svg;
</script>

Templates

| macOS | Windows | Minimal | | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | | | |

shellfie(output, { template: "macos" }); // default
shellfie(output, { template: "windows" });
shellfie(output, { template: "minimal" });

Custom Templates

Create your own templates with createTemplate:

import shellfie, { createTemplate } from "shellfie";

const myTemplate = createTemplate("my-template", {
  titleBar: true,
  titleBarHeight: 40,
  borderRadius: 10,
  controls: true,
  controlsPosition: "left",
  controlStyle: {
    close: "#ff5f56",
    minimize: "#ffbd2e",
    maximize: "#27c93f",
    radius: 6,
    spacing: 20,
    size: 12,
  },
  padding: 16,
  shadow: true,
  border: false,
  borderColor: "#333333",
  borderWidth: 0,
  header: {
    backgroundColor: "rgb(36, 37, 38)",
    border: false,
  },
});

shellfie(output, { template: myTemplate });

Templates can include default header and footer configurations. User options always override template defaults:

// Template has header.backgroundColor set, but user can override it
shellfie(output, {
  template: myTemplate,
  header: { backgroundColor: "#000000" }, // overrides template default
});

Options

shellfie(input, {
  template?: "macos",                             // 'macos' | 'windows' | 'minimal' | Template
  title?: "my-terminal",                          // window title
  width?: 80,                                     // SVG width in pixels (auto-detected if not set)
  height?: 400,                                   // SVG height in pixels (auto-detected if not set)
  padding?: 16,                                   // number | [v, h] | [top, right, bottom, left]
  controls?: true,                                // show window control buttons
  controlsPosition?: "left",                      // 'left' (macOS) or 'right' (Windows)
  fontSize?: 14,                                  // font size in pixels
  lineHeight?: 1.4,                               // line height multiplier
  fontFamily?: "'SF Mono', Monaco, monospace",    // font stack
  customGlyphs?: true,                            // pixel-perfect box drawing characters
  embedFont?: true,                               // embed default font as base64 (async only)
  customFont?: {                                  // use your own font
    data: base64FontData,                         //   base64-encoded font data
    format: "woff2",                              //   'woff2' | 'woff' | 'ttf'
  },
  theme?: customTheme,                            // custom color theme or see themes below
  language?: "typescript",                        // syntax highlighting: 'auto' | language | false
  watermark?: "Generated by shellfie",            // string or WatermarkConfig (see Watermarks below)
  header?: {                                      // header configuration
    backgroundColor?: "#2d2d2d",                  //   title bar background color
    height?: 40,                                  //   title bar height in pixels
    border?: true,                                //   show bottom border
    borderColor?: "#1a1a1a",                      //   border color
    borderWidth?: 1,                              //   border width in pixels
  },
  footer?: {                                      // footer configuration
    backgroundColor?: "#2d2d2d",                  //   footer background color
    height?: 30,                                  //   footer height in pixels
    border?: true,                                //   show top border
    borderColor?: "#1a1a1a",                      //   border color
    borderWidth?: 1,                              //   border width in pixels
  },
  background?: "#1a1a2e",                         // outer background (see Background section below)
});

Background

Add a background container around the terminal with solid colors or gradients:

// Simple hex color
shellfie(output, {
  background: "#1a1a2e",
});

// Gradient string with direction
shellfie(output, {
  background: "gradient(hotpink, cyan:diagonal)",
});

// Full configuration with padding and border radius
shellfie(output, {
  background: {
    color: "gradient(#ff0000, #0000ff:vertical)",
    padding: 50,
    borderRadius: 20,
  },
});

Background Options

| Option | Type | Default | Description | | -------------- | ------------------ | ------- | --------------------------------------------- | | color | string \| Gradient | - | Hex color or gradient string | | padding | number | 20 | Space between terminal and background edge | | borderRadius | number | 12 | Border radius of background container |

Gradient Syntax

Gradients use the format gradient(color1, color2:direction:reverse):

"gradient(#ff0000, #0000ff)"           // horizontal (default)
"gradient(hotpink, cyan:vertical)"     // vertical
"gradient(#ff6b6b, #4ecdc4:diagonal)"  // diagonal (top-left to bottom-right)
"gradient(pink, purple:horizontal:reverse)"  // reversed direction

| Direction | Description | | ------------ | ---------------------------------- | | horizontal | Left to right (default) | | vertical | Top to bottom | | diagonal | Top-left to bottom-right |

Add :reverse to reverse the gradient direction.

Watermarks

Add a watermark to the bottom-right corner of your SVG:

// Simple string (supports ANSI codes)
shellfie(output, {
  watermark: "\x1b[90mGenerated by shellfie\x1b[0m",
});

// Full configuration
shellfie(output, {
  watermark: {
    content: "powered by shellfie",
    style: {
      padding: 16, // number | [v, h] | [top, right, bottom, left]
      margin: [0, 8],
      opacity: 0.8,
    },
  },
});

Watermark Options

| Option | Type | Description | | --------- | ------------------- | ------------------------------------------------ | | content | string | Text (with ANSI) or SVG markup | | type | 'text' \| 'markup' | Auto-detected: markup if starts with SVG element | | style | WatermarkStyle | CSS-like positioning and appearance |

WatermarkStyle

Supports CSS shorthand notation for padding and margin:

style: {
  padding: 16,              // all sides
  padding: [8, 16],         // [vertical, horizontal]
  padding: [8, 16, 8, 16],  // [top, right, bottom, left]
  paddingTop: 8,            // individual sides
  margin: 0,
  marginRight: 8,
}

Additional SVG-compatible style properties are passed through:

style: {
  opacity: 0.5,
  filter: "blur(1px)",
  transform: "rotate(-5deg)",
}

Note: Standard CSS properties like border don't work in SVG. Use SVG-specific properties (stroke, stroke-width) or markup watermarks for complex styling.

SVG Markup Watermarks

For advanced watermarks, use raw SVG markup:

shellfie(output, {
  watermark: {
    content: `
      <a href="https://github.com/tool3/shellfie">
        <rect width="100" height="20" rx="3" fill="#333"/>
        <text x="50" y="14" text-anchor="middle" fill="#fff">shellfie</text>
      </a>
    `,
    // type auto-detected as 'markup' since content starts with '<a'
  },
});

The markup is wrapped in a <g> element positioned at the bottom-right, with font-family, font-size, and fill inherited from the theme.

Font Embedding

For portable SVGs that render identically everywhere:

import { shellfieAsync } from "shellfie";

const svg = await shellfieAsync(input, { embedFont: true });

The font gets base64-encoded directly into the SVG. No external requests, no CORS issues, no "why does this look different on their machine" debugging sessions.

Themes

shellfie comes with 35 built-in themes:

import shellfie, { dracula, nord, tokyoNight } from "shellfie";

shellfie(output, { theme: dracula });

| Dracula | Dracula PRO | Nord | | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | | | |

| Tokyo Night | One Dark | One Light | | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | | | |

| Monokai | Catppuccin Mocha | Material | | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | | | |

| GitHub Dark | GitHub Light | VS Code | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | | | |

| Gruvbox Dark | Gruvbox Light | Solarized Dark | | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | | | |

| Solarized Light | SynthWave '84 | Shades of Purple | | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | | | |

| Cobalt | Oceanic Next | Lucario | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | | | |

| Panda Syntax | Hopscotch | Paraiso Dark | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | | | |

| Base16 Dark | Base16 Light | Duotone Dark | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | | | |

| 3024 Night | A11y Dark | Blackboard | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | | | |

| Seti | Twilight | Verminal | | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | | | |

| Yeti | Zenburn | | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | | |

Custom Themes

import shellfie, { createTheme } from "shellfie";

const theme = createTheme({
  name: "ocean",
  background: "#0a2540",
  foreground: "#e6f1ff",
  red: "#ff6b6b",
  green: "#69db7c",
  // ... all 16 ANSI colors
});

shellfie(output, { theme });

Full Color Support

24-bit True Color & 256-color palette

import gradient from "gradient-string";
import shellfie from "shellfie";

const svg = shellfie(gradient.rainbow("Hello World"), {
  template: "macos",
  title: "gradient string",
});

Works with any ANSI output

import Chartscii from "chartscii";
import shellfie from "shellfie";

const chart = new Chartscii(data, {
  barSize: 2,
  fill: "▒",
  colorLabels: true,
  orientation: "vertical",
  valueLabels: true,
});

const svg = shellfie(chart.create(), {
  template: "macos",
  title: "Chartscii",
  padding: 50,
});

CLI tools, test runners, anything

shellfie(execSync("git diff --color=always").toString());
shellfie(execSync("npm test 2>&1").toString());
shellfie(execSync("ls -la --color=always").toString());

Utilities

import { parse, render, stripAnsi, getMaxWidth } from "shellfie";

const lines = parse("\x1b[31mred\x1b[0m text");
const svg = render(lines, options);

stripAnsi("\x1b[31mred\x1b[0m"); // 'red'
getMaxWidth(lines); // 80

Related

• See shellfie-cli for command line usage
• See shellfied for the shellfie web app

License

MIT