Technical Documentation: charmbracelet/freeze

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

Freeze

Generate images of code and terminal output.

Examples

Freeze generates PNGs, SVGs, and WebPs of code and terminal output alike.

Generate an image of code

freeze artichoke.hs -o artichoke.png

Generate an image of terminal output

You can use freeze to capture ANSI output of a terminal command with the
--execute flag.

bash

freeze --execute "eza -lah"

Freeze is also super customizable and ships with an interactive TUI.

Installation

# macOS or Linux
brew install charmbracelet/tap/freeze

# Arch Linux (btw)
yay -S freeze

# Nix
nix-env -iA nixpkgs.charm-freeze

Or, download it:

Packages are available in Debian and RPM formats
Binaries are available for Linux, macOS, and Windows

Or, just install it with go:

go install github.com/charmbracelet/freeze@latest

Customization

Interactive mode

Freeze features a fully interactive mode for easy customization.

bash

freeze --interactive

Settings are written to $XDG_CONFIG/freeze/user.json and can be accessed with
freeze --config user.

Flags

Screenshots can be customized with --flags or Configuration files.

[!NOTE]
You can view all freeze customization with freeze --help.

-b, --background: Apply a background fill.
-c, --config: Base configuration file or template.
-l, --language: Language to apply to code
-m, --margin: Apply margin to the window.
-o, --output: Output location for .svg, .png, .jpg.
-p, --padding: Apply padding to the code.
-r, --border.radius: Corner radius of window.
-t, --theme: Theme to use for syntax highlighting.
-w, --window: Display window controls.
-H, --height: Height of terminal window.
--border.width: Border width thickness.
--border.color: Border color.
--shadow.blur: Shadow Gaussian Blur.
--shadow.x: Shadow offset x coordinate.
--shadow.y: Shadow offset y coordinate.
--font.family: Font family to use for code.
--font.ligatures: Use ligatures in the font.
--font.size: Font size to use for code.
--font.file: File path to the font to use (embedded in the SVG).
--line-height: Line height relative to font size.
--show-line-numbers: Show line numbers.
--lines: Lines to capture (start,end).

Language

If possible, freeze auto-detects the language from the file name or analyzing
the file contents. Override this inference with the --language flag.

bash

cat artichoke.hs | freeze --language haskell

Theme

Change the color theme.

bash

freeze artichoke.hs --theme dracula

Output

Change the output file location, defaults to out.svg or stdout if piped. This
value supports .svg, .png, .webp.

bash

freeze main.go --output out.svg
freeze main.go --output out.png
freeze main.go --output out.webp

# or all of the above
freeze main.go --output out.{svg,png,webp}

Font

Specify the font family, font size, and font line height of the output image.
Defaults to JetBrains Mono, 14(px), 1.2(em).

bash

freeze artichoke.hs \
  --font.family "SF Mono" \
  --font.size 16 \
  --line-height 1.4

You can also embed a font file (in TTF, WOFF, or WOFF2 format) using the
--font.file flag.

To use ligatures in the font, you can apply the --font.ligatures flag.

Line Numbers

Show line numbers in the terminal window with the --show-line-numbers flag.

bash

freeze artichoke.hs --show-line-numbers

To capture only a specific range of line numbers you can use the --lines flag.

bash

freeze artichoke.hs --show-line-numbers --lines 2,3

Border Radius

Add rounded corners to the terminal.

bash

freeze artichoke.hs --border.radius 8

Window

Add window controls to the terminal, macOS-style.

bash

freeze artichoke.hs --window

Background

Set the background color of the terminal window.

bash

freeze artichoke.hs --background "#08163f"

Height

Set the height of the terminal window.

bash

freeze artichoke.hs --height 400

Border Width

Add a border outline to the terminal window.

bash

freeze artichoke.hs --border.width 1 --border.color "#515151" --border.radius 8

Padding

Add padding to the terminal window. You can provide 1, 2, or 4 values.

bash

freeze main.go --padding 20          # all sides
freeze main.go --padding 20,40       # vertical, horizontal
freeze main.go --padding 20,60,20,40 # top, right, bottom, left

Margin

Add margin to the terminal window. You can provide 1, 2, or 4 values.

bash

freeze main.go --margin 20          # all sides
freeze main.go --margin 20,40       # vertical, horizontal
freeze main.go --margin 20,60,20,40 # top, right, bottom, left

Shadow

Add a shadow under the terminal window.

bash

freeze artichoke.hs --shadow.blur 20 --shadow.x 0 --shadow.y 10

Screenshot TUIs

Use tmux capture-pane to generate screenshots of TUIs.

Run your TUI in tmux and get it to the state you want to capture.
Next, use capture-pane to capture the pane and pipe that to freeze.

bash

hx # in a separate pane
tmux capture-pane -pet 1 | freeze -c full

Configuration

Freeze also supports configuration via a JSON file which can be passed with the
--config / -c flag. In general, all --flag options map directly to keys
and values in the config file

There are also some default configurations built into freeze which can be passed by name.

base: Simple screenshot of code.
full: macOS-like screenshot.
user: Uses ~/.config/freeze/user.json.

If you use --interactive mode, a configuration file will be created for you at
~/.config/freeze/user.json. This will be the default configuration file used
in your screenshots.

bash

freeze -c base main.go
freeze -c full main.go
freeze -c user main.go # alias for ~/.config/freeze/user.json
freeze -c ./custom.json main.go

Here's what an example configuration looks like:

json

{
  "window": false,
  "border": {
    "radius": 0,
    "width": 0,
    "color": "#515151"
  },
  "shadow": false,
  "padding": [20, 40, 20, 20],
  "margin": "0",
  "font": {
    "family": "JetBrains Mono",
    "size": 14
  },
  "line_height": 1.2
}

Contributing

See contributing.

Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note!

License

MIT

Part of Charm.

Charm热爱开源 • Charm loves open source

--- METRICS ---

Files Extracted: 1
Estimated Token Budget: ~2682 tokens
Canonical Reference: https://codewiki.google/github.com/charmbracelet/freeze

freeze Documentation

Technical Documentation: charmbracelet/freeze

Overview (`README.md`)

Freeze

Examples

Generate an image of code

Generate an image of terminal output

Installation

Customization

Interactive mode

Flags

Language

Theme

Output

Font

Line Numbers

Border Radius

Window

Background

Height

Border Width

Padding

Margin

Shadow

Screenshot TUIs

Configuration

Contributing

Feedback

License

Table of Contents

Technical Documentation: charmbracelet/freeze

Overview (`README.md`) Copy Section

Freeze

Examples Copy Chapter

Generate an image of code Copy Section

Generate an image of terminal output Copy Section

Installation Copy Chapter

Customization Copy Chapter

Interactive mode Copy Section

Flags Copy Section

Language Copy Section

Theme Copy Section

Output Copy Section

Font Copy Section

Line Numbers Copy Section

Border Radius Copy Section

Window Copy Section

Background Copy Section

Height Copy Section

Border Width Copy Section

Padding Copy Section

Margin Copy Section

Shadow Copy Section

Screenshot TUIs Copy Chapter

Configuration Copy Chapter

Contributing Copy Chapter

Feedback Copy Chapter

License Copy Chapter

Explore Related Technologies & Topics

Overview (`README.md`)

Examples

Generate an image of code

Generate an image of terminal output

Installation

Customization

Interactive mode

Flags

Language

Theme

Output

Font

Line Numbers

Border Radius

Window

Background

Height

Border Width

Padding

Margin

Shadow

Screenshot TUIs

Configuration

Contributing

Feedback

License