tqrx

README

tqrx

A terminal-first QR generator for fast file output and live interactive preview.

中文说明 · Design · Contributing

tqrx is a small Go tool with two clear workflows:

• CLI for generating PNG / SVG in one command
• -m for printing QR codes directly in the terminal, no file needed
• TUI for editing content, checking preview, and saving in one session
• one shared render path for preview and export, so behavior stays consistent

TQRX  live qr workbench                      [PNG/M] [AUTO] [Ready]

┌──────────────────────────────┐┌────────────────────────────────────────────┐
│ [ Edit ]                     ││ [ Preview ]                                │
│ Compose                      ││ PNG • M • 256px  mods 37/64               │
│ │ https://example.com        ││ Path ./qrcode.png                          │
│ │                            ││                                            │
│ Settings                     ││                 QR PREVIEW                 │
│ Format  [PNG] [SVG]          ││                                            │
│ Size    > 256                │└────────────────────────────────────────────┘
│ Level   [L] [M] [Q] [H]      │  [Save QR]
│ Output  > ./qrcode.png       │
└──────────────────────────────┘

If you want a quick look at the interactive flow, watch the demo below:

https://github.com/user-attachments/assets/286c8d1c-1db2-4a64-a2c5-1a5c01895825

Why

• fast default path: tqrx "https://example.com"
• print QR code in terminal: tqrx -m "https://example.com"
• interactive path when you want to tune before export: tqrx tui
• stable validation around format, extension, size, and correction level
• scan-oriented preview hints such as mods X/Y and suggest M for scan

Install

Today, local build is the most reliable path:

go build -o tqrx .

After the first tagged release, Homebrew Cask is ready for:

brew install --cask crper/tap/tqrx

Quick Start

# default PNG export
./tqrx "https://example.com"

# print QR code directly in terminal
./tqrx -m "https://example.com"

# print in terminal and save to file
./tqrx -m "hello" -o qr.png

# read from stdin
printf 'from-pipe\n' | ./tqrx

# export SVG
./tqrx "hello svg" -f svg -s 256 -o hello.svg -l H

# open the interactive workbench
./tqrx tui

Help:

./tqrx --help
./tqrx tui --help

Notes:

• pass the text to encode as the root positional argument
• -m prints a QR preview in the terminal; combined with -o, it also saves the file
• tui is a reserved subcommand name; to encode the literal text, use ./tqrx -- tui
• if you also need -f / -o / -s / -l, place those flags before --, for example ./tqrx -f svg -o out.svg -- tui
• the default output path is ./qrcode.png

TUI

Common controls:

• Tab / Shift+Tab move focus
• Ctrl+S saves
• Ctrl+R resets all settings to defaults
• Ctrl+T cycles AUTO / LIGHT / DARK
• Enter inserts a newline in content and saves when Save is focused
• mouse focus switching and terminal paste events are supported

Preview behavior:

• the canvas stays high-contrast black on white
• mods X/Y shows current module count versus preview capacity
• small terminals show native preview exceeds viewport; enlarge terminal
• dense previews can suggest a lower correction level, such as suggest M for scan
• long content (> 500 chars) shows content long warning, > 1000 chars shows content very long
• preview metadata keeps scan hints and length warnings visible even when the current draft fails preview validation, so you can keep adjusting without losing context
• once the draft enters Updating, the old QR frame is cleared instead of being kept on screen, and the canvas shows a lightweight updating message

Environment variable:

TQRX_THEME=auto|light|dark

Development

go test ./...
go vet ./...
go build ./...

Git hooks:

go install github.com/evilmartians/lefthook/v2@v2.1.4
lefthook install

• pre-commit auto-runs gofmt -w on staged Go files
• pre-push runs go test ./..., go vet ./..., go build ./...

For TUI iteration with hot reload:

go install github.com/air-verse/air@latest
air

Release

• pushing a v* tag triggers .github/workflows/release.yml
• artifacts are built by .goreleaser.yml
• current targets are darwin/linux/windows + amd64/arm64
• the Homebrew Cask target repository is crper/homebrew-tap

Docs

• README.zh-Hans.md
• CHANGELOG.md
• DESIGN.md
• CONTRIBUTING.md

License

MIT · Copyright (c) 2026 crper

Documentation

Overview

tqrx 命令用于从文本或 stdin 生成二维码文件，也提供交互式终端界面用于 实时预览和导出。