@qrcodesdk/cli

Documentation | Live Demo

@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 SVG or terminal text in the CLI playground. The playground does not preview PNG, WebP, GIF, or JPEG output, which requires Node.js APIs.

Runtime requirements

@qrcodesdk/cli requires Node 22.12.0 or newer.

Install

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

npm install -g @qrcodesdk/cli

pnpm add -g @qrcodesdk/cli

vp

vp install -g @qrcodesdk/cli

deno

deno install --global @qrcodesdk/cli

bun

bun add -g @qrcodesdk/cli

yarn

yarn global add @qrcodesdk/cli

You can also run it from a project dependency.

npm install -D @qrcodesdk/cli

pnpm add -D @qrcodesdk/cli

vp

vp add -D @qrcodesdk/cli

deno

deno add --dev @qrcodesdk/cli

bun

bun add -D @qrcodesdk/cli

yarn

yarn add -D @qrcodesdk/cli

npx qrc "https://qrcodesdk.dev"

pnpm exec qrc "https://qrcodesdk.dev"

vp

vp exec qrc "https://qrcodesdk.dev"

deno

deno x npm:@qrcodesdk/cli/qrc "https://qrcodesdk.dev"

bun

bunx qrc "https://qrcodesdk.dev"

yarn

yarn qrc "https://qrcodesdk.dev"

Or use it without installing it.

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

pnpm dlx @qrcodesdk/cli "https://qrcodesdk.dev"

vp

vp dlx @qrcodesdk/cli "https://qrcodesdk.dev"

deno

deno x npm:@qrcodesdk/cli/qrc "https://qrcodesdk.dev"

bun

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

yarn

yarn dlx @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

Write WebP, GIF, and JPEG files

.webp, .gif, .jpg, and .jpeg output paths select WebP, GIF, and JPEG automatically:

qrc "https://qrcodesdk.dev" --output qrcode.webp
qrc "https://qrcodesdk.dev" --output qrcode.gif
qrc "https://qrcodesdk.dev" --output qrcode.jpg --quality 85

WebP output is lossless and usually much smaller than PNG. GIF output has at most 256 colors and binary transparency, so prefer PNG or WebP with a semi-transparent --background.

JPEG output is lossy and has no transparency. --quality sets the JPEG quality from 1 to 100 and defaults to 92. Transparent pixels are blended onto --matte, an opaque color that defaults to #ffffff. Both options are only accepted with JPEG output.

SVG, PNG, WebP, GIF, and JPEG output require --output. If the extension is not .svg, .png, .webp, .gif, .jpg, or .jpeg, pass --format explicitly:

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

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\|webp\|gif\|jpeg> | Output format. Inferred from the output path extension. | - | | -o, --output <path> | Required output path for SVG, PNG, WebP, GIF, and JPEG. | - | | --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 | | --quality <1-100> | JPEG quality. JPEG output only. | 92 | | --matte <#rrggbb> | Opaque color for transparent pixels. JPEG output only. | #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. Choose the output format with the arrow keys, j/k, or a number key, then press Enter. Press Escape or Ctrl+C to cancel a prompt.

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.

Documentation

• @qrcodesdk/cli
• Choose your setup
• Customize appearance
• Terminal text renderer
• SVG string renderer
• @qrcodesdk/node