Skip to main content

​
Overview

CLI mode renders markdown directly to your terminal’s stdout, perfect for quick viewing, piping content, or integrating Glow into scripts and workflows. Unlike TUI mode, CLI mode doesn’t launch an interactive interface—it simply renders and exits.

​
When CLI vs TUI Mode is Used

Glow automatically determines which mode to use based on your command:
  • No arguments provided: glow
  • A directory is provided: glow ~/docs
  • The --tui flag is explicitly set: glow file.md --tui
  • A file path is provided: glow README.md
  • Input is piped to stdin: cat file.md | glow
  • A URL is provided: glow https://example.com/doc.md
  • Reading from stdin explicitly: glow -
  • GitHub/GitLab shortcuts are used: glow github://owner/repo
The logic is implemented in main.go:222-261: 
func execute(cmd *cobra.Command, args []string) error {
    // if stdin is a pipe then use stdin for input
    if yes, err := stdinIsPipe(); err != nil {
        return err
    } else if yes {
        src := &source{reader: os.Stdin}
        defer src.reader.Close()
        return executeCLI(cmd, src, os.Stdout)
    }

    switch len(args) {
    case 0:
        return runTUI("", "")
    case 1:
        // Validate that the argument is a directory
        info, err := os.Stat(args[0])
        if err == nil && info.IsDir() {
            p, err := filepath.Abs(args[0])
            if err == nil {
                return runTUI(p, "")
            }
        }
        fallthrough
    default:
        // CLI mode for files
        for _, arg := range args {
            if err := executeArg(cmd, arg, os.Stdout); err != nil {
                return err
            }
        }
    }
    return nil
}

​
Input Sources

Glow’s CLI mode supports multiple input sources, all parsed through the sourceFromArg() function:

​
1. Local Files

Render a markdown file directly: 
glow README.md
glow /path/to/document.md
glow ~/docs/api.md
Glow will:
  • Open the file from the filesystem
  • Auto-detect if it’s markdown or code (based on file extension)
  • Apply the appropriate glamour styling
  • Render to stdout

​
2. Standard Input (stdin)

Pipe markdown content into Glow: 
cat README.md | glow

echo "# Hello\n\nThis is **markdown**" | glow

# Explicitly read from stdin
glow -
This is detected automatically when stdin is a pipe (using os.Stdin.Stat() to check Mode()).

​
3. HTTP/HTTPS URLs

Fetch and render markdown from the web: 
glow https://raw.githubusercontent.com/charmbracelet/glow/main/README.md

glow https://example.com/docs/guide.md
Glow will:
  • Parse the URL using url.ParseRequestURI()
  • Make an HTTP GET request
  • Check for HTTP 200 status
  • Render the response body
  • Set the base URL for relative links/images
Only http:// and https:// protocols are supported. Other protocols will return an error: “X is not a supported protocol”.

​
4. GitHub Shortcuts

Glow provides convenient shortcuts for GitHub repositories: 
# Fetch and render the README from a GitHub repo
glow github://charmbracelet/glow

# Also works with full GitHub URLs
glow github.com/charmbracelet/glow
glow https://github.com/charmbracelet/glow
The shortcut syntax github://owner/repo is transformed into the proper GitHub URL and fetches the repository’s README automatically.

​
5. GitLab Shortcuts

Similar to GitHub, but for GitLab: 
# Fetch and render the README from a GitLab repo
glow gitlab://owner/repo

# Also works with full GitLab URLs
glow gitlab.com/owner/repo
glow https://gitlab.com/owner/repo

func githubReadmeURL(path string) *url.URL {
    path = strings.TrimPrefix(path, protoGithub)
    parts := strings.Split(path, "/")
    if len(parts) != 2 {
        // custom hostnames are not supported yet
        return nil
    }
    u, _ := url.Parse(githubURL.String())
    return u.JoinPath(path)
}

​
6. Directories (README Detection)

When you provide a directory path in CLI mode, Glow searches for a README file: 
glow ~/my-project
Glow will walk the directory looking for files matching these names (case-insensitive):
  • README.md
  • README
  • Readme.md
  • Readme
  • readme.md
  • readme
The first match is rendered.

​
Rendering Output

By default, CLI mode renders directly to stdout: 
glow README.md
# Beautifully formatted markdown appears in your terminal

​
Pager Mode

For longer documents, use the pager: 
glow README.md --pager
# or
glow README.md -p
This pipes the output through your $PAGER (defaults to less -r if not set).
You cannot use both --pager and --tui flags together. Glow will return an error: “cannot use both pager and tui”.

​
Word Wrap Width

Control the rendering width: 
# Wrap at 80 characters
glow README.md --width 80

# Disable word wrap
glow README.md --width 0

# Auto-detect terminal width (default)
glow README.md
From main.go:192-207: 
// Detect terminal width
if !cmd.Flags().Changed("width") {
    if isTerminal && width == 0 {
        w, _, err := term.GetSize(int(os.Stdout.Fd()))
        if err == nil {
            width = uint(w)
        }

        if width > 120 {
            width = 120  // Maximum 120 for readability
        }
    }
    if width == 0 {
        width = 80  // Default fallback
    }
}

​
Preserve Newlines

By default, Glamour may adjust spacing. To preserve original newlines: 
glow file.md --preserve-new-lines
# or
glow file.md -n

​
Styling

Choose a rendering style: 
# Auto-detect based on terminal background (default)
glow README.md --style auto

# Use a specific built-in style
glow README.md --style dark
glow README.md --style light
glow README.md --style pink

# Use a custom JSON style file
glow README.md --style ~/.config/glow/mystyle.json
When stdout is not a TTY (e.g., piping to a file), Glow automatically uses the notty style for plain output.

​
Code Files

Glow can render code files (not just markdown) by wrapping them in a code block: 
glow main.go
glow script.py
glow config.json
The file extension is detected and used for syntax highlighting.

​
Example Workflows

​
Quick Documentation Preview

# Preview your README before committing
glow README.md

# Compare with remote version
glow github://myuser/myrepo

​
Piping and Processing

# Generate markdown and render it
echo "# Report\n\n**Status**: Complete" | glow

# Combine with other tools
curl -s https://api.github.com/repos/owner/repo/readme | \
  jq -r '.content' | \
  base64 -d | \
  glow

​
Paging Long Documents

# Read a long API reference
glow docs/api.md --pager

# Fetch and page remote docs
glow https://example.com/long-guide.md -p

​
Style Testing

# Try different styles
glow README.md --style dark
glow README.md --style light
glow README.md --style pink
glow README.md --style dracula

​
Integration Examples

​
Shell Scripts

#!/bin/bash
# Display help from a markdown file
glow /usr/share/doc/myapp/help.md

​
Git Aliases

# Add to ~/.gitconfig
[alias]
    readme = !glow README.md
    doc = !glow -p

​
CI/CD Documentation

# .github/workflows/docs.yml
- name: Preview Documentation
  run: |
    glow docs/deployment.md --style light --width 100

TUI Mode

Learn about the interactive file browser

Configuration

Set default options for CLI rendering

Build docs developers (and LLMs) love

Get started for freeTalk to us