# QR Code Data Formats & CLI Reference

## CLI Invocation

Always pipe data via stdin to avoid shell injection. Never interpolate user data into the command string.

```bash
printf '%s' 'ENCODED_DATA' | npx -y qrcode -o output/qr/qr-$(date +%s).png
```

### Options

| Option | Flag | Values |
|--------|------|--------|
| Size | `--width` | Small: 200, Medium: 400 (default), Large: 800 |
| Error correction | `--error-correction-level` | L (7%), M (15%, default), Q (25%), H (30%) |
| SVG output | `--type svg -o output/qr/qr-$(date +%s).svg` | Use instead of PNG when user requests SVG |

Higher error correction allows the QR code to remain scannable even if partially damaged, but reduces data capacity.

## Data Capacity

QR codes have a maximum capacity that depends on the error correction level:

| EC Level | Alphanumeric max | Binary max |
|----------|-----------------|------------|
| L | 4,296 | 2,953 |
| M | 3,391 | 2,331 |
| Q | 2,420 | 1,663 |
| H | 1,852 | 1,273 |

If the encoded data exceeds capacity, the CLI will error. Tell the user the data is too long and suggest reducing it or lowering the error correction level.

## Encoding Formats

### URL

Encode the URL as-is. No special formatting needed.

```
https://example.com/path?query=value
```

### Plain Text

Encode the text as-is.

### Wi-Fi

Collect from the user: network name (SSID), password, and encryption type.

| Field | Required | Values |
|-------|----------|--------|
| SSID | Yes | The network name |
| Password | Yes (unless open) | The network password |
| Encryption | Yes | WPA (covers WPA2/WPA3), WEP, or nopass |
| Hidden | No | true if the network is hidden (default: false) |

Default encryption to WPA if the user doesn't specify.

```
WIFI:T:WPA;S:MyNetwork;P:MyPassword;;
WIFI:T:WPA;S:MyNetwork;P:MyPassword;H:true;;
WIFI:T:nopass;S:OpenNetwork;;;
```

Special characters in SSID or password (`;`, `,`, `"`, `:`, `\`) must be escaped with a backslash.

### vCard (Contact)

Collect from the user: at minimum a name. Phone and email are optional but encouraged.

```
BEGIN:VCARD
VERSION:3.0
N:LastName;FirstName;;;
FN:FirstName LastName
TEL;TYPE=CELL:+441234567890
EMAIL:person@example.com
ORG:Company Name
TITLE:Job Title
URL:https://example.com
END:VCARD
```

Omit any field the user doesn't provide. Do not add placeholder values.

### Email (mailto)

```
mailto:recipient@example.com
mailto:recipient@example.com?subject=Hello&body=Message%20here
```

URL-encode the subject and body values.

### SMS

```
sms:+441234567890
sms:+441234567890?body=Message%20here
```

URL-encode the body value.

## Error Handling

| Error | Cause | User-facing message |
|-------|-------|-------------------|
| CLI exits non-zero | Various | Report the stderr output and suggest the user check their input |
| "Input too long" | Data exceeds QR capacity | "The data is too long for a QR code. Try shorter text or a lower error correction level (L instead of M)." |
| npm/npx failure | Package not available | "QR code package couldn't be downloaded. Check your internet connection and try again." |
| File write error | Permission or disk issue | "Couldn't save the QR code image. Check disk space and try again." |