Skip to content

@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, PNG, WebP, GIF, and JPEG files.

Build a command and preview it in the CLI playground. The playground previews SVG and terminal text only. PNG, WebP, GIF, and JPEG need Node.js APIs.

@qrcodesdk/cli requires Node.js 22.12.0 or newer.

Install it globally to use qrc anywhere:

Terminal window
npm install -g @qrcodesdk/cli
  • Deno grants no permissions by default. Its commands allow reading, writing output files, and reading environment variables such as NO_COLOR. The global install also names the command qrc.
  • Yarn 2 and newer have no global install. Use a project dependency or yarn dlx instead.

Or add it to a project and run it from there:

Terminal window
npm install -D @qrcodesdk/cli
Terminal window
npx qrc "https://qrcodesdk.dev"

Or run it without installing:

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

Without --output, qrc prints the code to the terminal. It packs two QR rows into each line and adds ANSI colors:

Terminal window
qrc "https://qrcodesdk.dev"

For full-height, double-width ██ modules, use the full layout:

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

--ansi controls color output:

Mode Output
blocks UTF-8 block glyphs with ANSI colors
background ANSI-colored spaces, without block glyphs
off Plain block glyphs in the terminal’s own text color, no colors

Without --ansi, qrc uses blocks. It switches to off when standard output is redirected or NO_COLOR is set. An explicit --ansi mode overrides both.

Terminal window
qrc "https://qrcodesdk.dev" --ansi off
qrc "https://qrcodesdk.dev" --ansi background
  • --layout works only with block output. --ansi background has a fixed full-cell layout and cannot be combined with --layout, even when writing a file.
  • File formats validate --layout and --ansi, then ignore them.

Dark terminal themes: without ANSI, dark modules use the terminal’s text color. On a dark theme that draws light modules on a dark background. The code looks inverted and many scanners reject it. Keep ANSI on, or pass --ansi blocks. ANSI output always paints dark modules with --foreground and light modules with --background.

Use --symbol micro for Micro QR codes or --symbol rmqr for rectangular Micro QR codes. The default is --symbol qr, a standard QR Code Model 2 symbol. All three symbol types work with terminal text and every file format.

Terminal window
qrc "12345" --symbol micro
qrc "12345" --symbol micro --version M1 --output micro.svg
qrc "HELLO" --symbol micro --version M4 --mask 2 --output micro.png
qrc "HELLO" --symbol rmqr --version R7x43 --output rectangular.svg
qrc "HELLO" --symbol rmqr --version R7 --error-correction H
Symbol --version --mask Error correction
qr 1 to 40 0 to 7 L, M, Q, H
micro M1 to M4 0 to 3 L or M; Q requires M4
rmqr Exact size such as R7x43, or height R7, R9, R11, R13, R15, R17 Unsupported M or H

Version and mask selection are automatic when omitted. Micro QR uses M2 or larger unless you request M1 explicitly. M1 accepts only numeric data and detects errors without correcting them. For rMQR, a height selector chooses the narrowest width at that height that holds the payload.

Micro QR and rMQR reject --eci and --optimize-segments. Both support --kanji and --mode kanji. A payload or error-correction level that does not fit fails with an error; the CLI does not fall back to a standard QR code. The default two-module quiet zone suits both symbol types.

See Micro QR codes and rMQR codes for capacity and scanner compatibility.

CLI Library renderers
Module size 1 5
Quiet zone 2 4

The small CLI defaults keep terminal text inside a normal window. They apply to files too: without options, a version 1 code becomes a 25 × 25 pixel PNG.

For files, pass --module-size 8 --quiet-zone 4. That gives a 232 × 232 pixel image with the standard four-module quiet zone. The examples below use these values.

The output width is module size × (matrix width + 2 × quiet zone).

Pass --output. The file extension selects the format, ignoring case:

Extension Format Notes
.svg SVG Scales without losing sharpness
.png PNG Lossless
.webp WebP Lossless, usually much smaller than PNG
.gif GIF At most 256 colors; each pixel is fully transparent or opaque
.jpg, .jpeg JPEG Lossy, no transparency
Terminal window
qrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.svg
qrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.png
qrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.webp
qrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.gif
qrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.jpg --quality 85

For any other extension, set the format with --format:

Terminal window
qrc "https://qrcodesdk.dev" --format webp --module-size 8 --quiet-zone 4 --output qrcode.image
  • SVG output is scalable, but --module-size still sets its width and height attributes.
  • For a semi-transparent --background, prefer PNG or WebP. GIF keeps only full transparency.
  • JPEG has two extra options, accepted only with JPEG output:
    • --quality sets the quality from 1 to 100. Default: 92.
    • --matte sets the opaque color that transparent pixels blend onto. Default: #ffffff.
Terminal window
qrc "https://qrcodesdk.dev" \
--output qrcode.svg \
--error-correction H \
--module-size 8 \
--quiet-zone 4 \
--foreground '#111827' \
--background '#ffffff' \
--aria-label 'Scan to open qrcodesdk.dev'

For colors, module size, quiet zones, and scan reliability, see Customize appearance. For how the encoding flags below work, see the builder reference.

  • --mode auto, the default, picks one encoding mode for the whole payload.
  • --optimize-segments combines modes when that makes the symbol smaller.
  • --no-optimize-segments restores single-mode detection.
  • A concrete mode, such as --mode alphanumeric, skips optimization.

This example uses the default standard QR symbol. Other symbol types accept the versions and masks listed above.

Leave mode, version, and mask automatic. Pin them only when a compatibility target or a layout needs a specific mode, symbol size, or mask:

Terminal window
qrc "HELLO WORLD" \
--mode alphanumeric \
--version 1 \
--mask 2 \
--module-size 8 \
--quiet-zone 4 \
--output hello.svg

These flags fix encoding choices, not the implementation. Output files may still change between CLI releases, as the release policy describes. To reproduce exact files, install an exact @qrcodesdk/cli version and keep your generated files as fixtures.

ECI is off by default. Pass --eci to declare UTF-8 explicitly:

Terminal window
qrc "Grüße" --eci

--no-eci states the default. It helps when a script builds its flags from variables.

qrc reads a positional value that starts with - as an option. Pass such a payload in one of two ways:

Terminal window
qrc --output negative.png -- "-42"
qrc --payload "-42" --output negative.png
  • After --: put every option first, then --, then the payload. Everything after -- counts as a payload, so an option placed there fails with Expected at most one payload argument.
  • With --payload: it accepts values that start with -. Like every option, it must come before a --.
Option Description Default
[payload] Positional QR code payload. If it starts with -, end with -- <payload>. -
--payload <value> QR code payload, equivalent to positional [payload]. -
-h, --help Print usage and every option, then exit with status 0. -
-V Print the installed CLI package version. -
--format <text|svg|png|webp|gif|jpeg> Output format, in lowercase. Inferred from the output path. text
-o, --output <path> Required output path for SVG, PNG, WebP, GIF, and JPEG. -
--symbol <qr|micro|rmqr> Symbol type. qr
--mode <auto|numeric|alphanumeric|octet|kanji> QR code mode, in lowercase. kanji loads the Kanji table. auto
--error-correction <L|M|Q|H> Error correction level. Lowercase letters are accepted. M
--version <version> Pin a symbol version or rMQR height. Automatic
--mask <mask> Pin a QR mask 0-7 or Micro mask 0-3. Unsupported for rMQR. Automatic
--optimize-segments Optimize mixed-mode segments in auto mode for standard QR codes. off
--no-optimize-segments Use single-mode detection in auto mode. -
--kanji Encode Shift JIS characters in Kanji mode in auto mode. off
--no-kanji Encode Japanese text as UTF-8 octets in auto mode. -
--eci Emit UTF-8 ECI assignment 26 for standard QR octet segments. off
--no-eci Do not emit UTF-8 ECI assignment 26. -
--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. Validated, then ignored by file formats. compact
--ansi <off|blocks|background> Explicit ANSI output mode. Validated, then ignored by file formats. Environment
--foreground <#rrggbb[aa]> Color of every dark module. #000000
--background <#rrggbb[aa]> Color behind the code, including the quiet zone. #ffffff
--quality <1-100> JPEG quality. Other formats reject it. 92
--matte <#rrggbb> Opaque color for transparent pixels. Other formats reject it. #ffffff
--aria-label <text> SVG aria-label accessible name. Ignored by other formats. -
--title <text> SVG child <title> text. Ignored by other formats. -

Colors must be RGB or RGBA hex values. In terminal text:

  • Block glyphs use --foreground as the ANSI foreground and --background as the ANSI background.
  • --ansi background uses both as cell background colors.
  • Without ANSI, both colors are ignored.

qrc is interactive only when both standard input and standard output are terminals. It then asks for missing values:

  • the payload;
  • the output format, if the path does not reveal it;
  • the output path, for file formats.

In the format menu, choose with the arrow keys, j/k, or a number key, then press Enter. Press Ctrl+C to cancel any prompt. Escape also cancels the format menu.

Scripts and CI jobs can rely on this behavior:

  • qrc never reads the payload from standard input. Pass it as [payload] or --payload. echo "text" | qrc fails with a missing-payload error.
  • Missing required values fail instead of opening a prompt.
  • Success, --help, and -V exit with status 0.
  • Every failure prints Error: <message> to standard error and exits with status 1. This includes invalid options, a payload that does not fit, a write error, and a cancelled prompt.
  • File output overwrites existing files without asking. The parent directory must already exist.
  • After writing a file, qrc prints Wrote <path> to standard error. Standard output stays free for terminal QR code text and pipelines.

This CI step creates the directory first and stops with a clear message on failure:

Terminal window
set -eu
mkdir -p artifacts
if ! qrc \
--payload "https://qrcodesdk.dev" \
--format png \
--module-size 8 \
--quiet-zone 4 \
--output artifacts/qrcode.png; then
echo "QR code generation failed" >&2
exit 1
fi

See Troubleshooting for common CLI errors.

@qrcodesdk/cli

Version
v0.0.6
Downloads
722/mo
Install size
765.8 kB
Bundled size
—
Works with
Works with Node.jsWorks with BunWorks with Deno

Support QRCodeSDK

If you find QRCodeSDK useful, please consider sponsoring the project!