CLI 命令行工具

使用 @codebox.club/cli 在终端管理二维码、模板和 Webhook，支持 CI/CD 集成和自动化脚本

安装

npm install -g @codebox.club/cli

pnpm add -g @codebox.club/cli

CLI 基于 @codebox.club/sdk 构建，需要 Node.js 18+。安装后可通过 codebox 命令直接使用。

配置 API Key

首次使用前需要配置 API Key。前往 Dashboard 创建 API Key →

# 方式 1：写入配置文件（推荐日常使用）
codebox config set api-key cb_sk_xxxxxxxxxxxxxxxx

# 方式 2：环境变量（推荐 CI/CD）
export CODEBOX_API_KEY=cb_sk_xxxxxxxxxxxxxxxx

# 方式 3：命令行参数（一次性使用）
codebox --api-key cb_sk_xxx qr list

优先级：命令行参数 > 环境变量 > 配置文件（~/.codeboxrc）。

快速开始

# 创建动态二维码
codebox qr create "https://example.com" --name "我的二维码"

# 查看二维码列表
codebox qr list

# 查看扫码统计
codebox qr stats <id>

# 浏览模板
codebox template list

# JSON 输出（适合脚本和管道）
codebox qr list --json | jq '.data[].id'

全局选项

选项	说明
`--api-key <key>`	覆盖 API Key
`--base-url <url>`	覆盖 API 地址（自托管实例）
`--json`	输出 JSON 格式（适合脚本）
`-V, --version`	显示版本号
`-h, --help`	显示帮助信息

二维码命令 `codebox qr`

创建二维码

codebox qr create <content> [选项]

选项	说明	默认值
`-m, --mode <mode>`	`STATIC` 或 `DYNAMIC`	`DYNAMIC`
`-t, --template <id>`	模板 ID	—
`-k, --keywords <words...>`	自动匹配模板的关键词	—
`-n, --name <name>`	二维码名称	—
`--logo <url>`	Logo 图片 URL	—
`--size <px>`	尺寸（像素）	—
`-e, --error-level <level>`	纠错等级：L / M / Q / H	—

示例：

# 创建带模板的动态码
codebox qr create "https://shop.com" --mode DYNAMIC --keywords tech modern --name "店铺码"

# 创建带 Logo 的静态码
codebox qr create "https://example.com" --mode STATIC --logo "https://cdn.example.com/logo.png"

查看列表

codebox qr list [选项]

选项	说明	默认值
`-p, --page <n>`	页码	1
`-s, --size <n>`	每页数量	10
`-m, --mode <mode>`	筛选模式：STATIC / DYNAMIC / AI	—
`-k, --keyword <text>`	关键词搜索	—

扫码统计

codebox qr stats <id> [选项]

选项	说明
`--start-date <YYYY-MM-DD>`	起始日期（默认 30 天前）
`--end-date <YYYY-MM-DD>`	结束日期（默认今天）

返回总扫码数、独立用户数、设备分布、浏览器分布、地域分布等。

更新二维码

codebox qr update <id> [选项]

选项	说明
`-u, --url <targetUrl>`	新的目标 URL
`-n, --name <name>`	新名称
`--status <status>`	READY / EXPIRED / DELETED

删除二维码

codebox qr delete <id> [-f, --force]

默认需要确认，--force 跳过确认。

克隆二维码

codebox qr clone <id> [-n, --name <name>] [-c, --content <content>]

扫码事件

codebox qr scans <id> [选项]

选项	说明	默认值
`-p, --page <n>`	页码	1
`-s, --size <n>`	每页数量	10
`--start-date <YYYY-MM-DD>`	起始日期	—
`--end-date <YYYY-MM-DD>`	结束日期	—

批量创建

codebox qr batch <file>

从 JSON 文件批量创建（最多 20 个）。文件格式：

[
  { "content": "https://page1.com", "mode": "DYNAMIC", "name": "页面1" },
  { "content": "https://page2.com", "templateId": "tech-modern-01" }
]

模板命令 `codebox template`

查看模板列表

codebox template list [-c, --category <name>]

搜索模板

codebox template search <keyword>

按名称、标签、分类、品牌进行模糊搜索。

Webhook 命令 `codebox webhook`

创建 Webhook

codebox webhook create <url> [--events <events...>]

默认订阅事件：scan.created、qrcode.created。

查看列表

codebox webhook list [-p, --page <n>] [-s, --size <n>]

更新 Webhook

codebox webhook update <id> [--url <url>] [--events <events...>] [--status <ACTIVE|DISABLED>]

删除 Webhook

codebox webhook delete <id> [-f, --force]

配置命令 `codebox config`

codebox config set <key> <value>   # 设置配置（api-key 或 base-url）
codebox config get <key>           # 读取配置
codebox config list                # 显示所有配置
codebox config unset <key>         # 删除配置

配置保存在 ~/.codeboxrc 文件中。API Key 显示时自动脱敏。

CI/CD 集成

在 GitHub Actions 中使用：

- name: Install CodeBox CLI
  run: npm install -g @codebox.club/cli

- name: Generate QR codes
  env:
    CODEBOX_API_KEY: $\{{ secrets.CODEBOX_API_KEY }}
  run: |
    codebox qr create "$DEPLOY_URL" --name "v$VERSION" --json > qr.json

在脚本中批量处理：

# 导出所有二维码 ID
codebox qr list --size 50 --json | jq -r '.data[].id' > ids.txt

# 批量查看统计
while read id; do
  codebox qr stats "$id" --json
done < ids.txt

自托管实例

连接自部署的 CodeBox 服务器：

codebox config set base-url https://my-codebox.example.com

或通过环境变量：

export CODEBOX_BASE_URL=https://my-codebox.example.com

错误处理

错误	说明	解决方案
Authentication failed	API Key 无效或已过期	重新创建 API Key
Rate limited	超出频率限制	等待重试或降低请求频率
CREDIT_EXHAUSTED	额度不足	充值额度

On this page