Guide

Usage Guide

Reading files, keyboard shortcuts, and features

Overview

This guide walks you through everything you need to read and navigate markdown files with Glow — from launching the interactive terminal UI to rendering remote files and piping content from stdin. Whether you prefer browsing a directory tree with a keyboard-driven interface or rendering a single file directly to your terminal, you'll find the relevant commands, shortcuts, and options here. Mastering these features lets you stay in your terminal without ever reaching for a browser or a heavy editor just to read documentation.

Prerequisites

Before you begin, make sure you have the following:

A Unix-like terminal (macOS, Linux, FreeBSD, OpenBSD) or Windows with a supported package manager
Glow installed on your system (see the Installation section below)
Go 1.21 or later — only required if you plan to build Glow from source
Optional: a $PAGER environment variable set if you want paged output routed to a specific pager other than the default less -r

Installation

Choose the method that matches your operating system or workflow.

Package managers

macOS / Linux (Homebrew)
```
brew install glow
```
macOS (MacPorts)
```
sudo port install glow
```
Arch Linux
```
pacman -S glow
```
Void Linux
```
xbps-install -S glow
```
Nix (one-shot shell)
```
nix-shell -p glow --command glow
```
FreeBSD
```
pkg install glow
```
Solus
```
eopkg install glow
```

Windows — pick whichever package manager you already use:

choco install glow
# or
scoop install glow
# or
winget install charmbracelet.glow

Android (Termux)
```
pkg install glow
```
Ubuntu (Snap)
```
sudo snap install glow
```

Debian / Ubuntu (APT)

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install glow

Fedora / RHEL (YUM)

echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install glow

Install with Go

If you have Go available, this is the fastest cross-platform option:

go install github.com/charmbracelet/glow/v2@latest

Build from source

Requires Go 1.21 or later.

Clone the repository:

git clone https://github.com/charmbracelet/glow.git

Enter the directory:
```
cd glow
```
Build the binary:
```
go build
```

Binary releases

Pre-built binaries for macOS, Linux, Windows, FreeBSD, and OpenBSD — including ARM builds and Debian, RPM, and Alpine packages — are available on the GitHub releases page.

Configuration

If you find yourself passing the same flags on every invocation, create a persistent config file instead. Run the following command to open the file in your $EDITOR:

glow config

Alternatively, place a file named glow.yml in your platform's default config directory. Run glow --help to find the exact path on your system.

Here is a fully annotated example of every available option:

# style name or path to a custom JSON stylesheet (default: "auto")
# "auto" detects your terminal background and chooses "dark" or "light"
style: "light"

# enable mouse wheel support in TUI mode
mouse: true

# pipe output through a pager when rendering from the CLI
pager: true

# maximum column width before word-wrapping occurs
width: 80

# show hidden files and files listed in .gitignore (TUI mode)
all: false

# display line numbers alongside content (TUI mode only)
showLineNumbers: false

# preserve newlines as they appear in the source file
preserveNewLines: false

Key options explained

Option	Default	Effect
`style`	`"auto"`	Controls the visual theme. Set to `"dark"`, `"light"`, or a path to a custom `.json` stylesheet. `"auto"` inspects terminal background color automatically.
`mouse`	`false`	Enables mouse-wheel scrolling inside the TUI. Useful on systems where terminal mouse support is reliable.
`pager`	`false`	When `true`, CLI output is sent to your `$PAGER` (defaults to `less -r`). Keeps long documents readable without scrolling back through your shell history.
`width`	(terminal width)	Hard-wraps rendered output at this column count. Useful on wide monitors where full-width markdown is hard to scan.
`all`	`false`	When `true`, the TUI also lists hidden files and entries that would normally be excluded by `.gitignore`.
`showLineNumbers`	`false`	Adds line numbers in the TUI reader pane. Helpful when referencing specific lines in conversation or review.
`preserveNewLines`	`false`	When `true`, newlines in the source are kept as-is rather than being reflowed by the renderer.

Any option set in glow.yml can be overridden at runtime by passing the equivalent CLI flag.

Usage

Launching the interactive TUI

Run glow with no arguments to open the terminal UI. Glow automatically searches the current directory (and all subdirectories) for markdown files. If you are inside a Git repository, it searches the entire repo.

glow

Use the arrow keys to browse the file list. Press Enter to open a file in the built-in pager. Inside the pager, most less keybindings work — press ? at any time to display the full hotkey reference.

Rendering a specific file

Pass a file path directly to render it immediately without entering the TUI:

glow README.md

Reading from stdin

Pipe any markdown content into Glow using - as the argument:

echo "# Hello" | glow -

This is especially useful for composing Glow with other CLI tools.

Fetching from a URL or GitHub/GitLab

Glow can fetch and render remote markdown over HTTP, or resolve a GitHub/GitLab repository URL to its README automatically:

# Render a raw remote file
glow https://host.tld/file.md

# Fetch and render a GitHub repo's README
glow github.com/charmbracelet/glow

Controlling word wrap width

Use -w to set the column width at which output wraps. This is useful when your terminal is very wide or when you want consistent output width in scripts:

glow -w 80 README.md

Enabling the pager

Add -p to route rendered output through your pager. The pager defaults to less -r, which understands ANSI color codes, unless you have $PAGER set to something else:

glow -p README.md

Choosing a style

Use -s to select a built-in theme or point to a custom JSON stylesheet:

# Use the light built-in theme
glow -s light README.md

# Use a custom stylesheet
glow -s ~/.config/glow/mytheme.json README.md

When -s is omitted, Glow detects your terminal background and picks dark or light automatically.

Getting help

glow --help

Examples

Browse local markdown files interactively

Launch the TUI from a project directory to discover and read all markdown files:

cd ~/projects/myapp
glow

Glow scans ~/projects/myapp recursively and, if it is a Git repo, respects that boundary. You'll see a list of discovered .md files you can navigate with arrow keys.

Render a local file with word wrap at 60 columns

glow -w 60 docs/guide.md

The output is styled and reflowed so that no line exceeds 60 characters — handy for narrower terminals or side-by-side splits.

Pipe markdown from another command

curl -s https://raw.githubusercontent.com/charmbracelet/glow/master/README.md | glow -

Glow reads from stdin and renders the content in place, letting you preview remote files without saving them.

Render a GitHub repository README directly

glow github.com/charmbracelet/glow

Glow resolves the repository URL, fetches the README, and renders it with full styling — no browser required.

Render with a specific style and paging enabled

glow -s dark -p README.md

This forces the dark theme and pages the output through less -r (or your $PAGER), so you can scroll freely through long documents.

Use a custom JSON stylesheet

glow -s ~/dotfiles/glow/solarized.json README.md

Point -s at any valid Glamour-compatible JSON stylesheet file to apply fully custom colors and typography. See the Glamour style gallery for inspiration.

Open the config file for editing

glow config

This opens glow.yml in your $EDITOR. Add pager: true and width: 80 to those flags permanently so you never have to type them again.

Troubleshooting

Glow renders garbled characters or strips color

Symptom: You see raw ANSI escape codes, boxes, or question marks instead of styled text.

Likely cause: Your terminal does not support 256-color or true-color output, or your $TERM variable is set incorrectly.

Fix: Ensure your terminal emulator supports ANSI color (most modern ones do). Check that $TERM is set to a value like xterm-256color. If piping output to a file or another tool, be aware that color codes will be included — strip them with a tool like sed or use Glow's output only for direct terminal rendering.

The pager shows raw escape sequences

Symptom: Running glow -p opens a pager that displays ^[[1m and similar sequences instead of bold/colored text.

Likely cause: Your $PAGER is set to a program that does not understand ANSI codes (for example, plain more on some systems).

Fix: Glow defaults to less -r, which handles ANSI codes correctly. Either unset $PAGER so Glow uses its default, or explicitly set it:

export PAGER="less -r"

Glow finds no markdown files in the TUI

Symptom: Launching glow with no arguments shows an empty file list.

Likely cause: There are no .md files in the current directory tree, or the files are hidden/gitignored and all is false.

Fix: Navigate to a directory that contains markdown files before running glow, or enable the all option in your config (or pass the equivalent flag) to include hidden and gitignored files:

glow --all

`glow config` opens the wrong editor or nothing at all

Symptom: Running glow config does nothing, throws an error, or opens an unexpected application.

Likely cause: The $EDITOR environment variable is not set or points to an editor that is not in your PATH.

Fix: Set $EDITOR to your preferred editor before running the command:

export EDITOR=nano
glow config

Output is not wrapping at the expected width

Symptom: Text wraps earlier or later than the -w value you specified.

Likely cause: A width value in glow.yml is overriding (or being overridden by) your CLI flag, or the terminal itself is narrower than the requested wrap width.

Fix: CLI flags take precedence over config file values, so passing -w explicitly should always win. Double-check your glow.yml for a conflicting width entry. Run glow --help to confirm the flag syntax for your installed version.

`go install` fails or produces an old version

Symptom: After running go install github.com/charmbracelet/glow/v2@latest, the installed binary is missing or outdated.

Likely cause: Your Go toolchain is older than 1.21, or $GOPATH/bin (or $GOBIN) is not on your $PATH.

Fix: Verify your Go version with go version and upgrade if needed. Then confirm the install directory is on your path:

export PATH="$PATH:$(go env GOPATH)/bin"