DOCSEARCHbyAlgolia
Submit Docs

freeze

repository·main·Indexed 26 days ago

https://github.com/charmbracelet/freeze

A tool for generating high-quality images (PNG, SVG, WebP) of code snippets and terminal output. It features syntax highlighting, ANSI color parsing, and a TUI for interactive customization of fonts, themes, borders, and window appearance.

Tokens
5.6K
Snippets
15
Records
31
Agent score
87%

What's inside freeze

  1. Install Freeze

    main

    You can install Freeze using various package managers depending on your operating system, or by using Go.

    macOS or Linux (Homebrew):

    brew install charmbracelet/tap/freeze

    Arch Linux:

    yay -S freeze

    Nix:

    nix-env -iA nixpkgs.charm-freeze

    Go:

    go install github.com/charmbracelet/freeze@latest

    Binaries for Linux, macOS, and Windows, as well as Debian and RPM packages, are also available on the releases page.

    # macOS or Linux
brew install charmbracelet/tap/freeze

# Arch Linux (btw)
yay -S freeze

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

# Or, just install it with `go`:
go install github.com/charmbracelet/freeze@latest

  2. Use Interactive Mode for customization

    main

    Freeze includes a fully interactive TUI for easy customization. Running this mode will allow you to adjust settings visually.

    Settings configured in interactive mode are saved to $XDG_CONFIG/freeze/user.json. You can access these saved settings using freeze --config user.

    freeze --interactive

  4. Configure Freeze via JSON

    main

    Freeze supports configuration via a JSON file passed with the --config or -c flag. All CLI flags map directly to keys in the JSON file.

    Built-in configuration templates:

    • base: Simple screenshot of code.
    • full: macOS-like screenshot.
    • user: Uses ~/.config/freeze/user.json (the default if interactive mode was used).

    Example JSON configuration:

    {
  "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
}

  5. Use Interactive Mode to configure Freeze

    main
    If you prefer a guided setup, use the --interactive flag. This will run a form to collect your preferences. If you are using the default configuration, your changes will be saved to the user configuration file.

  6. Use Freeze CLI to generate code or terminal output images

    main

    Freeze is a CLI tool used to generate high-quality images (SVG or PNG) of code snippets or terminal output. It supports syntax highlighting via Chroma, ANSI color parsing, and various customization options like margins, padding, borders, and shadows.

    Core Capabilities

    • Generate images from code: Provide a file or pipe input to create a syntax-highlighted image.
    • Generate images from terminal output: Use the --execute flag to run a command and capture its output as an image.
    • Support for ANSI: Automatically detects and parses ANSI color codes to preserve terminal styling in the output.
    • Output Formats: Supports .svg (default) and .png (via libsvg or resvg).
    • Interactive Mode: Use the --interactive flag to configure settings via a form.

    Basic Usage Patterns

    From a file:

    freeze path/to/file.go

    From stdin (piping):

    cat file.go | freeze

    From a command execution:

    freeze --execute "ls -la"

    Specifying a language for syntax highlighting:

    freeze --language go path/to/file.go

  9. Configure window appearance (Border, Radius, Window Controls)

    main

    Customize the terminal window appearance:

    • --border.radius: Set corner radius.
    • --window: Display macOS-style window controls.
    • --border.width and --border.color: Set border thickness and color.

  10. Show and limit line numbers

    main

    Use --show-line-numbers to display line numbers in the window. To capture only a specific range of lines, use the --lines flag with a comma-separated range.

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

  11. Configure padding and margin

    main

    Apply padding or margin to the window. You can provide 1 value (all sides), 2 values (vertical, horizontal), or 4 values (top, right, bottom, left).

    # Padding examples
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 examples
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

  12. Customize fonts

    main

    Specify the font family, size, and line height. You can also embed a specific font file (TTF, WOFF, or WOFF2) using --font.file and enable ligatures with --font.ligatures.

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