@codebox.club/cli

Official CLI for the CodeBox QR code platform.

Installation

npm install -g @codebox.club/cli
# or
pnpm add -g @codebox.club/cli

Quick Start

# Set your API key (get one at https://www.codebox.club/dashboard/apikeys)
codebox config set api-key cb_sk_your_key_here

# Create a QR code
codebox qr create "https://example.com" --mode DYNAMIC --name "My QR"

# List your QR codes
codebox qr list

# View scan analytics
codebox qr stats <qr-id>

# Browse templates
codebox template list
codebox template search "tech"

Authentication

API key is resolved in this order:

1. --api-key flag
2. CODEBOX_API_KEY environment variable
3. ~/.codeboxrc config file

# Option 1: Config file (recommended for local dev)
codebox config set api-key cb_sk_xxx

# Option 2: Environment variable (recommended for CI)
export CODEBOX_API_KEY=cb_sk_xxx

# Option 3: Flag (one-off)
codebox --api-key cb_sk_xxx qr list

Commands

QR Codes

codebox qr create <content>     # Create a QR code
  -m, --mode <STATIC|DYNAMIC>   # Default: DYNAMIC
  -t, --template <id>           # Template ID
  -k, --keywords <words...>     # Keywords for template matching
  -n, --name <name>             # Name
  --logo <url>                  # Logo URL
  --size <px>                   # Size in pixels
  -e, --error-level <L|M|Q|H>  # Error correction level

codebox qr list                  # List QR codes
  -p, --page <n>                # Page (default: 1)
  -s, --size <n>                # Page size (default: 10)
  -m, --mode <mode>             # Filter: STATIC, DYNAMIC, AI
  -k, --keyword <text>          # Filter by keyword

codebox qr stats <id>           # Scan analytics
  --start-date <YYYY-MM-DD>
  --end-date <YYYY-MM-DD>

codebox qr update <id>          # Update QR code
  -u, --url <targetUrl>
  -n, --name <name>
  --status <READY|EXPIRED|DELETED>

codebox qr delete <id>          # Delete QR code
  -f, --force                   # Skip confirmation

codebox qr clone <id>           # Clone QR code
  -n, --name <name>
  -c, --content <content>

codebox qr scans <id>           # List scan events
  -p, --page <n>
  -s, --size <n>
  --start-date <YYYY-MM-DD>
  --end-date <YYYY-MM-DD>

codebox qr batch <file>         # Batch create from JSON (max 20)

Templates

codebox template list            # List all templates
  -c, --category <name>         # Filter by category

codebox template search <keyword> # Search templates

Webhooks

codebox webhook create <url>     # Create webhook
  --events <events...>          # Default: scan.created, qrcode.created

codebox webhook list             # List webhooks
codebox webhook update <id>      # Update webhook
codebox webhook delete <id>      # Delete webhook

Config

codebox config set <key> <value> # Set api-key or base-url
codebox config get <key>         # Get config value
codebox config list              # Show all config
codebox config unset <key>       # Remove config value

Global Options

--api-key <key>   # Override API key
--base-url <url>  # Override API base URL
--json            # Output as JSON (machine-readable)
--version         # Show version
--help            # Show help

JSON Output

All commands support --json for machine-readable output:

codebox qr list --json | jq '.data[].id'
codebox qr stats abc123 --json > stats.json

Batch Create

Create a JSON file with an array of QR code definitions:

[
  { "content": "https://example.com/1", "mode": "DYNAMIC", "name": "Link 1" },
  { "content": "https://example.com/2", "mode": "DYNAMIC", "name": "Link 2" }
]

Then run:

codebox qr batch items.json

Custom Server

For self-hosted CodeBox instances:

codebox config set base-url https://my-codebox.example.com
# or
export CODEBOX_BASE_URL=https://my-codebox.example.com