Syntheraqr CLI Docs

Install

Linux and macOS — one line:

curl -fsSL https://syntheraqr.netlify.app/install | bash

Installs to ~/.local/bin/syntheraqr from a prebuilt GitHub release, falling back to a source build if no binary matches your system. Set SYNTHERAQR_DEST to install elsewhere.

Usage


# Inline terminal preview (default)
syntheraqr "https://syntheraqr.site"

# Save as PNG / JPG / SVG / WebP (format from the extension)
syntheraqr "https://syntheraqr.site" -o qr.png
syntheraqr "hello" --style square -o hello.jpg
syntheraqr "hello" --style dots -o dots.svg
syntheraqr "hello" --transparent -o hello.webp

# Customize like the web version
syntheraqr "hello" --fg "#0f172a" --bg "#f8fafc" --transparent

# Diagonal gradient (fg → fg2)
syntheraqr "grad" --fg "#0f172a" --fg2 "#6366f1" -o grad.svg

# Open the saved file with the system viewer
syntheraqr "hello" -o qr.png --open

# Interactive prompt when no text is given (TTY)
syntheraqr

# Unix-filter style: pipe bytes to files or other tools
echo "https://example.com" | syntheraqr --stdout > qr.png
syntheraqr "data" --stdout --format svg > qr.svg

Text comes from the TEXT argument, piped stdin, or an interactive prompt when run bare in a terminal.

Options

Option	Description	Default
--fg <HEX>	Foreground (dot) color	#0f172a
--fg2 <HEX>	Secondary color → diagonal gradient	off
--bg <HEX>	Background color	#f8fafc
--transparent	Transparent background	off
--style rounded\|square\|dots	Dot style	rounded
-e, --error L\|M\|Q\|H	Error correction level	M
-s, --size <PX>	Output size in pixels	260
-m, --margin <PX>	Quiet zone in pixels (matches the web app)	4
-o, --output <FILE>	Save to file (png/jpg/jpeg/svg/webp)	—
-f, --format <FMT>	Force output format	inferred
--stdout	Write image bytes to stdout	—
--no-show	Skip the terminal preview	off
--open	Open the saved file with the system viewer	off
-q, --quiet	Suppress informational messages	off
--completions <SHELL>	Print shell completion script	—
--force-kitty	Force kitty graphics preview	—
--force-block	Force half-block character preview	—

Commands

decode — read a QR back to text


syntheraqr decode qr.png
syntheraqr decode qr.png | wc -c

update — self-update from GitHub Releases


syntheraqr update --check     # report installed vs latest version
syntheraqr update             # download and install the latest version
syntheraqr update --force     # reinstall even if already up to date

Downloads the new binary, verifies it runs, and atomically replaces the running executable. Requires an internet connection. Self-update exists in 0.2.0+ — older installs must reinstall once via the install command above.

completions — shell tab-completion


syntheraqr --completions bash > /etc/bash_completion.d/syntheraqr
syntheraqr --completions zsh > _syntheraqr
syntheraqr --completions fish > syntheraqr.fish

Terminal preview

When stdout is a TTY, the QR is rendered inline automatically. The preview strips the quiet zone so the code fills the screen; saved files keep your --margin. Both come from the same rendering engine as this website.

smart_display Kitty graphics protocol — kitty, Ghostty, WezTerm, iTerm2, Warp, Terminal.app. Auto-detected (env hints + a live 150 ms probe); sizes itself to ~75% of the terminal and adapts on resize. Override with --force-kitty / --force-block.
text_fields Half-block fallback — ▀ glyphs with 24-bit truecolor everywhere else: Alacritty, xterm, VS Code, tmux, SSH.
terminal Piping — when stdout is not a TTY, image bytes are written to stdout instead of previewing.

Offline & network

Everything you'd do day-to-day is computed locally by the binary — no internet, no external services, no CDN assets:

✓ QR generation (encoding)
✓ All styles, colors, gradients, finder patterns
✓ PNG / JPG / SVG / WebP encoding
✓ Terminal preview (kitty + half-block)
✓ decode — reading QR images back to text
✓ Completions, help, version

Only two things need the internet: syntheraqr update (fetches the latest version from the GitHub API) and installing. Generate, style, save, preview, and decode all work fully offline.