qr-term

v1.1.0

Published

4 days ago

High-fidelity inline QR code generator & terminal renderer supporting Kitty, iTerm2, Sixel, Half-Block Unicode, and Braille graphics across macOS, Linux, Windows, PowerShell, Bash, and Zsh.

0High
0Medium
0Low

authoritydmc

qr qrcode terminal inline-images kitty-graphics iterm2 sixel cli powershell zsh bash unicode half-block

qr-term 📲

High-fidelity inline QR code generator, terminal renderer & image decoder with automatic protocol detection across macOS, Linux, and Windows (Kitty, iTerm2, Sixel, Half-Block Unicode, and Braille).

Designed both as an interactive CLI utility and a zero-fuss library for CLI applications (e.g. 2FA login prompts, payment links, pairing codes, Wi-Fi share, crypto addresses, and QR image scanning).

✨ Features

🔍 Pure JS/TS QR Code Reader & Decoder: Scan & decode QR codes from PNG and JPEG image files, buffers, clipboard, or piped stdin without native C++ dependencies.
📋 System Clipboard Integration: Read text or screenshot images directly from clipboard to encode or decode with zero hassle.
🖥️ Universal Terminal Support: Automatically detects and uses the highest-quality rendering protocol available in your current terminal.
🎨 Multi-Protocol Engine:
- Kitty Graphics Protocol (Ghostty, Kitty, WezTerm) — native pixel-perfect rendering.
- iTerm2 Inline Images (iTerm2, VS Code Terminal, Warp, Tabby, Mintty) — crisp PNG inline graphics.
- Sixel Graphics (Foot, XTerm, mlterm, WezTerm) — hardware-level bitmap terminal rendering.
- Half-Block Unicode (▀) — universal 1:1 square pixel aspect ratio on any shell (PowerShell, Bash, Zsh, CMD, PuTTY, CI runners).
- Compact Braille (⠓⠚) — ultra-compact micro matrix for tight spaces.
🌈 Full ANSI 24-Bit Truecolor & Monochrome: Custom foreground/background colors with ANSI sequence optimization.
📦 Dual ESM & CommonJS: Full TypeScript definitions (.d.ts) included out of the box.
⚡ Zero Native C++ Build Dependencies: Runs anywhere Node.js runs with pure JavaScript/TypeScript.
🚰 Pipe-Friendly CLI: Supports both direct arguments and standard input pipes for encoding and decoding.

💻 Terminal Compatibility Matrix

🚀 Installation

Global CLI Tool

npm install -g qr-term
# or
npx qr-term "https://example.com"

In Your Project (Library)

npm install qr-term
# or
pnpm add qr-term
# or
yarn add qr-term

🛠️ CLI Usage

# Basic usage (encode text/URL)
qr-term "https://github.com"

# Encode text copied to clipboard
qr-term --clipboard
# or
qr-term -c

# Using alias
qrx "https://github.com"

# Piped input
echo "https://my-auth-link.com" | qr-term

# Custom protocol
qr-term "https://github.com" --protocol kitty
qr-term "https://github.com" --protocol iterm2
qr-term "https://github.com" --protocol sixel
qr-term "https://github.com" --protocol halfblock
qr-term "https://github.com" --protocol braille

# Compact mode (reduced margin)
qr-term "https://github.com" --small

# Custom Colors (Hex or RGB)
qr-term "https://github.com" --fg "#00ffff" --bg "#0f172a"

# Error correction level (L = 7%, M = 15%, Q = 25%, H = 30%)
qr-term "https://github.com" --ecc H

# Decode / scan a QR code image
qr-term decode qr.png
qr-term -d qr.jpg
cat qr.png | qr-term decode

# Decode QR code directly from copied screenshot/image in clipboard
qr-term decode --clipboard
qr-term decode -c

# Verbose decode (shows QR version and boundary coordinates)
qr-term decode qr.png --verbose

# Inspect detected terminal capabilities
qr-term --info

📖 Programmatic API (TypeScript & JavaScript)

1. Print directly to terminal (Auto Protocol)

import { renderQR } from "qr-term";

await renderQR("https://github.com/authoritydmc/qr-term");

2. Decode QR Code from Image File or Buffer

import { decodeQR } from "qr-term";

// From file path
const result = await decodeQR("./qrcode.png");
console.log(result.data); // Extracted text/URL

// From buffer (PNG / JPEG)
const imageBuffer = await fs.promises.readFile("./qrcode.jpg");
const decoded = await decodeQR(imageBuffer);
console.log(decoded.data, decoded.version, decoded.location);

3. Capture formatted string (e.g. for CLI layouts / boxes)

import { generateQR } from "qr-term";

const qrCode = await generateQR("https://auth.company.com/pair?code=88310", {
  protocol: "halfblock",
  small: true,
  foreground: "#38bdf8",
  background: "transparent",
});

console.log(qrCode);

4. Check terminal capabilities programmatically

import { detectTerminalCapabilities } from "qr-term";

const caps = detectTerminalCapabilities();
console.log(caps);

5. Raw QR Matrix Extraction

import { createQRMatrix } from "qr-term";

const matrix = createQRMatrix("Hello World", "M");
// 2D boolean array: matrix[row][col] === true for dark module

⚙️ Options Reference

🧪 Development & Testing

# Clone the repository
git clone https://github.com/authoritydmc/qr-term.git
cd qr-term

# Install dependencies
npm install

# Run automated tests
npm test

# Build dual ESM/CJS & TypeScript declaration bundles
npm run build

🚀 Automated Release & Versioning

You can bump the version, create git tags, and release packages in two automated ways:

Method 1: From GitHub Actions Web UI (1-Click)

Go to Actions -> Automated Version & Release.
Click Run workflow.
Choose release bump type: patch (e.g. 1.0.1), minor (1.1.0), or major (2.0.0).
Click Run workflow. The action will automatically run tests, bump package.json, commit, create git tag vX.Y.Z, push, publish to NPM, and create a GitHub Release with release notes!

Method 2: From Terminal

# Bumps version, creates git tag, and pushes to origin
npm run release:patch  # for bug fixes / patches
npm run release:minor  # for new features
npm run release:major  # for breaking changes

GitHub Actions will automatically pick up the pushed tag and publish the release to NPM & GitHub Releases.