qrterminal

You can install the qrterminal command line tool using several methods:

macOS (Homebrew): brew install mdp/tap/qrterminal

Go (from source): go install github.com/mdp/qrterminal/v3/cmd/qrterminal@latest

Docker: docker pull ghcr.io/mdp/qrterminal:latest

Manual: Download binaries from the releases page.

To use qrterminal as a dependency in your Go application, use the go get command to fetch the v3 package.

go get github.com/mdp/qrterminal/v3

Use qrterminal.Generate to quickly output a QR code to a writer (like os.Stdout). You must specify the content string, the error correction level, and the target io.Writer.

import (
    "github.com/mdp/qrterminal/v3"
    "os"
)

func main() {
  // Generate a 'dense' qrcode with the 'Low' level error correction and write it to Stdout
  qrterminal.Generate("https://github.com/mdp/qrterminal", qrterminal.L, os.Stdout)
}

The CLI tool allows you to generate QR codes from command line arguments or via standard input (stdin).

Basic usage: qrterminal <URL_OR_TEXT>

With error correction level: Use the -l flag to specify the level (e.g., M for medium). qrterminal <URL_OR_TEXT> -l M

Using Docker: docker run --rm ghcr.io/mdp/qrterminal:latest '<URL_OR_TEXT>'

Piping text via stdin: cat <file> | qrterminal

Piping text via Docker stdin: cat <file> | docker run --rm -i ghcr.io/mdp/qrterminal:latest

# Print a basic QR code
qrterminal https://github.com/mdp/qrterminal

# Using medium error correction
qrterminal https://github.com/mdp/qrterminal -l M

# Piping text from a file
cat wireguard_peer.conf | qrterminal

The IsSixelSupported function checks if the provided io.Writer is os.Stdout and if the terminal environment supports Sixel graphics by querying the terminal capabilities. This is useful if you are implementing custom rendering logic and need to know if high-fidelity Sixel output is possible.

if qrterminal.IsSixelSupported(os.Stdout) {
    // Handle Sixel-specific logic
}

The Generate function is the primary entry point for quickly rendering a QR code to an io.Writer (such as os.Stdout). It automatically detects if the terminal supports Sixel graphics and uses them if available. If Sixel is not supported, it falls back to full block rendering using ANSI escape sequences.

Parameters:

• text: The string content to encode.
• l: The error correction level (use constants H, M, or L).
• w: The destination io.Writer.

package main

import (
	"os"
	"qrterminal"
)

func main() {
	// Generates a QR code with Medium error correction to Stdout
	qrterminal.Generate("https://example.com", qrterminal.M, os.Stdout)
}

If you want to use half-block characters (which provide a denser, more accurate visual representation in many terminals) without manually configuring the Config struct, use GenerateHalfBlock. This function sets up a configuration specifically optimized for half-block rendering using standard black/white characters.

qrterminal.GenerateHalfBlock("https://example.com", qrterminal.L, os.Stdout)

For fine-grained control over the visual output, use GenerateWithConfig. This allows you to customize characters, quiet zones, and rendering modes.

Key fields in Config:

• Level: Error correction level (qrterminal.H, qrterminal.M, or qrterminal.L).
• Writer: The destination io.Writer.
• HalfBlocks: If true, uses half-block characters to achieve higher vertical resolution.
• BlackChar, WhiteChar, BlackWhiteChar, WhiteBlackChar: Custom strings used for rendering different pixel states.
• QuietZone: The width of the white border around the QR code (defaults to 4 if not set).
• WithSixel: If true, attempts to render using Sixel graphics sequences.

config := qrterminal.Config{
	Level:      qrterminal.H,
	Writer:     os.Stdout,
	HalfBlocks: true,
	QuietZone:  2,
}
qrterminal.GenerateWithConfig("my data", config)

The library provides constants for QR code error correction levels, which determine the redundancy of the data:

• qrterminal.H: High error correction.
• qrterminal.M: Medium error correction.
• qrterminal.L: Low error correction.

const (
	H = qr.H
	M = qr.M
	L = qr.L
)

The qrterminal command-line tool generates QR codes directly in your terminal. You can provide the data to be encoded as command-line arguments or via standard input (stdin). If no arguments are provided, the tool reads from stdin until EOF.

Usage Patterns

From command-line arguments:

qrterminal "your data here"

From standard input (stdin):

echo "your data here" | qrterminal

The qrterminal CLI provides several flags to customize the output and error correction of the generated QR code.

Error Correction Levels

• L: Low error correction
• M: Medium error correction
• H: High error correction