@qrcodesdk/cli

@qrcodesdk/cli generates QR codes from a terminal, shell script, or CI job. The qrc command prints compact UTF-8 terminal text or writes SVG and PNG files.

Runtime requirements

@qrcodesdk/cli requires Node 22.12.0 or newer.

Install

Install it globally when you want qrc available as a command anywhere:

Package manager

npmpnpmvpdenobunyarn

npm install -g @qrcodesdk/cli

You can also run it from a project dependency.

Package manager

npmpnpmvpdenobunyarn

npm install -D @qrcodesdk/cli

Package manager

npmpnpmvpdenobunyarn

npx qrc "https://qrcodesdk.dev"

Or use it without installing it.

Package manager

npmpnpmvpdenobunyarn

npx @qrcodesdk/cli "https://qrcodesdk.dev"

Print terminal text

Without an output file, qrc packs two QR rows into each terminal line and applies ANSI colors:

qrc "https://qrcodesdk.dev"

Use full-height, double-width ██ modules when preferred:

qrc "https://qrcodesdk.dev" --layout full

ANSI styling is disabled automatically when standard output is redirected or NO_COLOR is present. You can also disable it explicitly:

qrc "https://qrcodesdk.dev" --ansi off

Render modules entirely as ANSI-colored spaces, without UTF-8 block glyphs:

qrc "https://qrcodesdk.dev" --ansi background

Use --layout compact or --layout full with block output. --ansi background has fixed full-cell geometry and cannot be combined with --layout. An explicit ANSI mode takes precedence over NO_COLOR and TTY detection.

Write SVG files

An .svg output path selects SVG automatically:

qrc "https://qrcodesdk.dev" --output qrcode.svg

You can also set the format explicitly:

qrc "https://qrcodesdk.dev" --format svg --output qrcode.svg

Write PNG files

An .png output path selects PNG automatically:

qrc "https://qrcodesdk.dev" --output qrcode.png

Or pass the format explicitly:

qrc "https://qrcodesdk.dev" --format png --output qrcode.png

SVG and PNG output require --output. If the extension is not .svg or .png, pass --format explicitly.

Configure generated files

qrc "https://qrcodesdk.dev" \
  --output qrcode.svg \
  --error-correction H \
  --module-size 2 \
  --quiet-zone 3 \
  --foreground '#111827' \
  --background '#ffffff' \
  --aria-label 'Scan to open qrcodesdk.dev'

The CLI exposes matrix and visual options as flags. Leave mode, version, and mask on automatic selection unless you need a compatibility target or deterministic fixture:

qrc "HELLO WORLD" \
  --mode alphanumeric \
  --version 1 \
  --mask 2 \
  --output hello.svg

Enable the UTF-8 ECI declaration:

qrc "Grüße" --eci

The CLI does not emit ECI by default. Use --no-eci to disable it explicitly. For the behavior and tradeoffs behind these flags, see the builder reference. For colors, module size, quiet zones, and scan-reliability guidance, see Customize appearance.

Options

Option	Description	Default
[payload]	Positional QR code payload.	-
--payload <value>	QR code payload, equivalent to positional [payload].	-
-V	Print the installed CLI package version.	-
--format <text|svg|png>	Output format. Inferred from .svg or .png output paths.	-
-o, --output <path>	Required output path for SVG and PNG.	-
--mode <numeric|alphanumeric|octet>	QR code mode.	Auto
--error-correction <L|M|Q|H>	Error correction level.	M
--version <1-40>	Pin a QR code version.	Auto
--mask <0-7>	Pin a QR code mask.	Auto
--eci	Emit UTF-8 ECI assignment 26 for octet segments.	false
--no-eci	Do not emit UTF-8 ECI assignment 26.	false
--module-size <number>	Module size as a positive integer.	1
--quiet-zone <number>	Quiet zone as a non-negative integer.	2
--layout <compact|full>	Text block layout.	compact
--ansi <off|blocks|background>	Explicit ANSI output mode.	Environment
--foreground <#rrggbb[aa]>	Dark module color.	#000000
--background <#rrggbb[aa]>	Light module color.	#ffffff
--aria-label <text>	SVG aria-label accessible name.	undefined
--title <text>	SVG child <title> text.	undefined

Colors must be RGB or RGBA hex values. --module-size must be positive and --quiet-zone must be non-negative. For block-glyph text output, the dark color is the ANSI foreground and the light color is the ANSI background. With --ansi background, both become module background colors.

Interactive and automated use

In an interactive terminal, qrc prompts only for missing required values such as payload, an ambiguous format, or a file output path.

In a non-interactive shell or CI job, missing required values fail with a clear error instead of opening a prompt. Pass every required value explicitly:

qrc \
  --payload "https://qrcodesdk.dev" \
  --format png \
  --output artifacts/qrcode.png

Successful file output writes a confirmation to standard error, leaving standard output available for terminal QR code content and pipeline use.