@qrdx/cli 0.0.4 → 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Ritesh Bucha and QRdx contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,64 @@
 # @qrdx/cli
 
-QR code generator CLI for developers. Generate styled, scannable QR codes as SVG or PNG — fully non-interactive, CI-friendly.
+QR code generator CLI for developers. Generate styled, scannable QR codes as SVG, PNG, WebP or vector EPS. It runs non-interactively in scripts and CI, and guides you with prompts when run in a terminal. It renders with the same [`qrdx`](https://www.npmjs.com/package/qrdx) library as the [QRdx](https://qrdx.dev) web app.
+
+> [!NOTE]
+> This README documents `@qrdx/cli` 0.0.6, the version in this repository. WebP output is new in 0.0.6; 0.0.5 has every other option here. Run `npm view @qrdx/cli version` to see what npm installs. Until it is 0.0.6, get WebP from the [image API](https://qrdx.dev/docs/developers/image-api): `curl -o qr.webp "https://api.qrdx.dev/v1/qr?data=https://example.com&format=webp"`.
 
 ## Install
 
-```bash
-# Install the qrdx library package (includes the CLI binary)
-npm install -g qrdx
+Run without installing:
 
-# Or install the standalone CLI package
-npm install -g @qrdx/cli
+```bash
+npx @qrdx/cli generate "https://example.com" -o qr.svg
 ```
 
-Or run without installing:
+Or install globally, which gives you the `qrdx` command:
 
 ```bash
-npx qrdx generate "https://example.com" -o qr.svg
+npm install -g @qrdx/cli
+qrdx generate "https://example.com" -o qr.svg
 ```
 
+PNG and WebP output use [sharp](https://sharp.pixelplumbing.com). It is an optional dependency that npm installs automatically when your platform supports it; if it is missing, SVG and EPS output still work and the CLI tells you how to fix PNG and WebP.
+
+> The `qrdx` npm package is the React library. The CLI lives only in `@qrdx/cli`.
+
 ## Usage
 
 ```bash
 qrdx generate <data> [options]
 ```
 
+`gen` and `g` are aliases for `generate`, and `qrdx <data>` works too.
+
 **Options**
 
 | Flag | Short | Default | Description |
 |------|-------|---------|-------------|
-| `--output` | `-o` | — | Output path — extension sets format (`.svg` or `.png`) |
-| `--size` | | `512` | Output pixel size |
+| `--output` | `-o` | `qr.svg` | Output path; the extension sets the format (`.svg`, `.png`, `.webp` or `.eps`) |
+| `--format` | | from the extension | `svg`, `png`, `webp` or `eps`, for a file name without an extension |
+| `--size` | | `512` | Output size: pixels for SVG, PNG and WebP, points (72 per inch) for EPS |
 | `--level` | `-l` | `Q` | Error correction: `L` `M` `Q` `H` |
 | `--body` | | `square` | Body dot pattern |
 | `--eye` | | `square` | Corner eye pattern |
 | `--dot` | | `square` | Corner dot pattern |
-| `--fg` | | `#000000` | Foreground color |
-| `--bg` | | `#ffffff` | Background color |
-| `--eye-color` | | — | Corner eye color override |
-| `--dot-color` | | — | Corner dot color override |
-| `--logo` | | — | Center logo URL |
+| `--fg` | | `#000000` | Foreground color (hex or JSON gradient) |
+| `--bg` | | `#ffffff` | Background color (hex or JSON gradient) |
+| `--eye-color` | | matches `--fg` | Corner eye color (hex or JSON gradient) |
+| `--dot-color` | | matches `--fg` | Corner dot color (hex or JSON gradient) |
+| `--logo` | | — | Center logo image URL (use with `--level H`) |
+| `--no-logo` | | — | Skip the logo prompt in interactive mode |
 | `--margin` | | `0` | Quiet zone margin (modules) |
+| `--template` | | — | Decorative template: `Arrow` `StandardBox` `SquareBorder` `StrikedBox` `Halloween` |
+| `--frame` | | — | Call-to-action frame: <!-- catalogue:FRAME_STYLES -->`none`, `banner-bottom`, `banner-top`, `border`, `rounded-border`, `speech-bubble`, `banner-top-bottom`, `speech-bubble-top`, `chat-bubble`, `circle`, `polaroid`, `phone`, `ticket`, `badge`, `envelope`, `tag`, `menu-card`, `sticker`, `gradient-border`, `focus`<!-- /catalogue --> |
+| `--frame-text` | | `Scan me` | Frame label, up to 24 characters (`""` hides it) |
+| `--frame-color` | | `#000000` | Frame color (hex) |
+| `--frame-text-color` | | white on banners | Frame label color (hex) |
+| `--help` | `-h` | | Show all options |
+| `--version` | `-v` | | Show the version |
+
+Invalid values (unknown pattern, template, frame, level, size, output extension, malformed gradient JSON, frame text over 24 characters or a non-hex frame color) exit with code `1` and a message listing the accepted values. `--frame-text` or a frame color without `--frame` uses `banner-bottom`. A frame adds space around the code, so the file is larger than `--size`.
 
 ## Examples
 
@@ -50,6 +69,12 @@ qrdx generate "https://qrdx.dev" -o qr.svg
 # High-res PNG for print
 qrdx generate "https://qrdx.dev" -o qr.png --size 2048 --level H
 
+# Lossless WebP for a website: the PNG's pixels in a smaller file
+qrdx generate "https://qrdx.dev" -o qr.webp --size 1024
+
+# Vector EPS for a print shop or Illustrator, 2 inches wide
+qrdx generate "https://qrdx.dev" -o qr.eps --size 144
+
 # Branded style
 qrdx generate "https://qrdx.dev" \
   --body circle --eye rounded \
@@ -59,7 +84,17 @@ qrdx generate "https://qrdx.dev" \
 # With center logo
 qrdx generate "https://qrdx.dev" \
   --logo "https://qrdx.dev/logo.png" --level H \
-  -o logo-qr.svg
+  -o logo-qr.png
+
+# Gradient foreground
+qrdx generate "https://qrdx.dev" -o gradient.svg \
+  --fg '{"type":"linear","stops":[{"color":"#6366f1","offset":0},{"color":"#ec4899","offset":100}],"angle":135}'
+
+# Template
+qrdx generate "https://qrdx.dev" --template Arrow -o arrow.svg
+
+# "Scan me" frame
+qrdx generate "https://qrdx.dev/menu" --frame banner-bottom --frame-text "Scan for the menu" -o menu.png
 
 # Wi-Fi QR
 qrdx generate "WIFI:T:WPA;S:MyNetwork;P:MyPassword;;" -o wifi.svg
@@ -68,27 +103,59 @@ qrdx generate "WIFI:T:WPA;S:MyNetwork;P:MyPassword;;" -o wifi.svg
 qrdx generate
 ```
 
+## Batch: a code for every row of a CSV
+
+```bash
+qrdx batch products.csv -o codes --format png --size 1024 --body circle
+```
+
+`qrdx batch` (or `qrdx b`) reads a CSV and writes one static QR code per row into a folder, with the same columns as the free [bulk generator](https://qrdx.dev/tools/bulk). The content comes from a column named `value`, `url`, `link`, `data`, `content`, `text` or `qr` (else the first column), and file names from one named `file name`, `name`, `label`, `id`, `title` or `sku` (else `qr-00001.svg`, `qr-00002.svg` and so on). Pick others with `--value-column` and `--name-column`, by header name or column number, and use `--no-header` when the first row is a code.
+
+Every style option of `generate` applies to all the codes. The file is read as a stream and each code is written as soon as it's made, so there's no row limit; nothing is uploaded and no account is needed. Rows that can't be encoded are skipped and listed, with the reason, in `errors.csv` in the output folder. `--jobs` sets how many codes render at a time (4 for SVG, 8 for PNG and EPS by default).
+
 ## Patterns
 
-**Body** (`--body`): `square` `circle` `circle-large` `diamond` `circle-mixed` `pacman` `rounded` `small-square` `vertical-line`
+**Body** (`--body`): <!-- catalogue:BODY_PATTERN -->`circle`, `circle-large`, `square`, `diamond`, `circle-mixed`, `pacman`, `rounded`, `small-square`, `vertical-line`, `horizontal-line`, `liquid`, `liquid-horizontal`, `liquid-vertical`, `classy`, `classy-rounded`, `leaf`, `plus`, `hexagon`, `star`, `heart`, `random-dots`, `mosaic`, `octagon`<!-- /catalogue -->
+
+**Eye** (`--eye`): <!-- catalogue:CORNER_EYE_PATTERNS -->`square`, `rounded`, `gear`, `circle`, `diya`, `extra-rounded`, `message`, `pointy`, `leaf`, `drop`, `octagon`, `bevel`, `squircle`, `cushion`, `shield`, `petal`, `leaf-reverse`<!-- /catalogue -->
+
+**Dot** (`--dot`): <!-- catalogue:CORNER_EYE_DOT_PATTERNS -->`square`, `rounded`, `circle`, `message`, `message-reverse`, `diya`, `diya-reverse`, `rounded-triangle`, `leaf`, `drop`, `plus`, `cross-rounded`, `hexagon`, `octagon`, `flower`, `heart`, `squircle`, `dots`, `extra-rounded`, `leaf-reverse`, `drop-reverse`<!-- /catalogue -->
+
+See them all at [qrdx.dev/docs/styles](https://qrdx.dev/docs/styles). Every option decodes in our tests; `square` and `rounded` eyes scan most reliably, and `circle` eyes may be missed by strict scanners. Curly eyes and diamond, star and banner dots were retired because they don't scan reliably.
+
+## Gradients
+
+Pass a JSON object to `--fg`, `--bg`, `--eye-color` or `--dot-color`:
+
+```bash
+# Linear (angle in degrees: 0 = left→right, 90 = top→bottom)
+--fg '{"type":"linear","stops":[{"color":"#6366f1","offset":0},{"color":"#ec4899","offset":100}],"angle":135}'
+
+# Radial
+--bg '{"type":"radial","stops":[{"color":"#fef9c3","offset":0},{"color":"#fde047","offset":100}]}'
+```
+
+Each gradient needs at least 2 stops; `offset` is a percentage from 0 to 100.
 
-**Eye** (`--eye`): `square` `rounded` `gear` `circle` `diya` `extra-rounded` `message` `pointy` `curly`
+## EPS
 
-**Dot** (`--dot`): `square` `rounded` `circle` `diamond` `message` `message-reverse` `diya` `diya-reverse` `rounded-triangle` `star` `banner`
+`.eps` files are vector PostScript (EPSF-3.0) for print shops and design tools. `--size` is the width in points, so `--size 144` is 2 inches. Linear and radial gradients print as smooth PostScript Level 3 shadings, and there is no transparency. PNG and JPEG logos are embedded; other logo formats are converted with sharp when it is installed, and otherwise left out with a warning.
 
 ## Interactive mode
 
-When run in a TTY without flags, `qrdx generate` starts a guided prompt flow — output path, then optionally advanced customizations (patterns, colors, logo).
+When run in a TTY without an output path or data, `qrdx generate` starts a guided prompt flow: data, output path, then optional customizations (patterns, colors, template, logo, margin). In CI (`CI=true`) or when stdin/stdout is not a TTY it never prompts.
 
 ## Requirements
 
-Node.js ≥ 18
+Node.js ≥ 22
 
 ## Links
 
-- [qrdx.dev](https://qrdx.dev) — web app
-- [github.com/qrdx/qrdx](https://github.com/qrdx/qrdx) — source
+- [CLI docs](https://qrdx.dev/docs/developers/cli)
+- [qrdx.dev](https://qrdx.dev): the web app, with static and dynamic QR codes, hosted pages and scan analytics
+- [Image API](https://qrdx.dev/docs/developers/image-api) and [MCP server](https://qrdx.dev/docs/developers/mcp): QR codes over HTTP or from AI assistants, with nothing to install
+- [github.com/bucharitesh/qrdx](https://github.com/bucharitesh/qrdx): the source
 
 ## License
 
-MIT
+[MIT](./LICENSE) © Ritesh Bucha and QRdx contributors. Versions before 0.0.5 were published under AGPL-3.0-or-later.