@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.
Runtime requirements
Section titled “Runtime requirements”@qrcodesdk/cli requires Node.js 22.12.0 or newer.
Install
Section titled “Install”Install it globally to use qrc anywhere:
npm install -g @qrcodesdk/clipnpm add -g @qrcodesdk/clivp install -g @qrcodesdk/clideno install --global --allow-read --allow-write --allow-env --name qrc npm:@qrcodesdk/clibun add -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 commandqrc. - Yarn 2 and newer have no global install. Use a project dependency or
yarn dlxinstead.
Or add it to a project and run it from there:
npm install -D @qrcodesdk/clipnpm add -D @qrcodesdk/clivp add -D @qrcodesdk/clideno add --dev npm:@qrcodesdk/clibun add -D @qrcodesdk/cliyarn add -D @qrcodesdk/clinpx qrc "https://qrcodesdk.dev"pnpm exec qrc "https://qrcodesdk.dev"vp exec qrc "https://qrcodesdk.dev"deno x --allow-read --allow-write --allow-env npm:@qrcodesdk/cli/qrc "https://qrcodesdk.dev"bunx qrc "https://qrcodesdk.dev"yarn qrc "https://qrcodesdk.dev"Or run it without installing:
npx @qrcodesdk/cli "https://qrcodesdk.dev"pnpm dlx @qrcodesdk/cli "https://qrcodesdk.dev"vp dlx @qrcodesdk/cli "https://qrcodesdk.dev"deno x --allow-read --allow-write --allow-env npm:@qrcodesdk/cli/qrc "https://qrcodesdk.dev"bunx @qrcodesdk/cli "https://qrcodesdk.dev"yarn dlx @qrcodesdk/cli "https://qrcodesdk.dev"Print terminal text
Section titled “Print terminal text”Without --output, qrc prints the code to the terminal. It packs two QR rows into each line and
adds ANSI colors:
qrc "https://qrcodesdk.dev"For full-height, double-width ██ modules, use the full layout:
qrc "https://qrcodesdk.dev" --layout fullANSI colors
Section titled “ANSI colors”--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.
qrc "https://qrcodesdk.dev" --ansi offqrc "https://qrcodesdk.dev" --ansi background--layoutworks only with block output.--ansi backgroundhas a fixed full-cell layout and cannot be combined with--layout, even when writing a file.- File formats validate
--layoutand--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.
Micro QR and rMQR codes
Section titled “Micro QR and rMQR codes”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.
qrc "12345" --symbol microqrc "12345" --symbol micro --version M1 --output micro.svgqrc "HELLO" --symbol micro --version M4 --mask 2 --output micro.pngqrc "HELLO" --symbol rmqr --version R7x43 --output rectangular.svgqrc "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 defaults differ from the library
Section titled “CLI defaults differ from the library”| 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).
Write image files
Section titled “Write image files”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 |
qrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.svgqrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.pngqrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.webpqrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.gifqrc "https://qrcodesdk.dev" --module-size 8 --quiet-zone 4 --output qrcode.jpg --quality 85For any other extension, set the format with --format:
qrc "https://qrcodesdk.dev" --format webp --module-size 8 --quiet-zone 4 --output qrcode.image- SVG output is scalable, but
--module-sizestill sets itswidthandheightattributes. - For a semi-transparent
--background, prefer PNG or WebP. GIF keeps only full transparency. - JPEG has two extra options, accepted only with JPEG output:
--qualitysets the quality from 1 to 100. Default:92.--mattesets the opaque color that transparent pixels blend onto. Default:#ffffff.
Configure generated files
Section titled “Configure generated files”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.
Encoding mode
Section titled “Encoding mode”--mode auto, the default, picks one encoding mode for the whole payload.--optimize-segmentscombines modes when that makes the symbol smaller.--no-optimize-segmentsrestores single-mode detection.- A concrete mode, such as
--mode alphanumeric, skips optimization.
Version and mask
Section titled “Version and mask”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:
qrc "HELLO WORLD" \ --mode alphanumeric \ --version 1 \ --mask 2 \ --module-size 8 \ --quiet-zone 4 \ --output hello.svgThese 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.
UTF-8 ECI
Section titled “UTF-8 ECI”ECI is off by default. Pass --eci to declare UTF-8 explicitly:
qrc "Grüße" --eci--no-eci states the default. It helps when a script builds its flags from variables.
Payloads that start with a hyphen
Section titled “Payloads that start with a hyphen”qrc reads a positional value that starts with - as an option. Pass such a payload in one of two
ways:
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 withExpected at most one payload argument. - With
--payload: it accepts values that start with-. Like every option, it must come before a--.
Options
Section titled “Options”| 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
--foregroundas the ANSI foreground and--backgroundas the ANSI background. --ansi backgrounduses both as cell background colors.- Without ANSI, both colors are ignored.
Interactive and automated use
Section titled “Interactive and automated use”Interactive prompts
Section titled “Interactive prompts”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
Section titled “Scripts and CI”Scripts and CI jobs can rely on this behavior:
qrcnever reads the payload from standard input. Pass it as[payload]or--payload.echo "text" | qrcfails with a missing-payload error.- Missing required values fail instead of opening a prompt.
- Success,
--help, and-Vexit with status0. - Every failure prints
Error: <message>to standard error and exits with status1. 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,
qrcprintsWrote <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:
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 1fiSee Troubleshooting for common CLI errors.
@qrcodesdk/cli
- Version
- v0.0.6
- Downloads
- 722/mo
- Install size
- 765.8 kB
- Bundled size
- —
Related pages
Section titled “Related pages”Support QRCodeSDK
If you find QRCodeSDK useful, please consider sponsoring the project!