为什么要在终端生成二维码？

如果你是开发者，你可能已经习惯在终端完成大部分工作。二维码管理也应该如此——不需要打开浏览器、登录后台、点击按钮，一条命令就够了。

CodeBox CLI 是 CodeBox 平台的官方命令行工具，让你在终端完成所有二维码操作：

一条命令创建带追踪的动态二维码
批量生成 20 个二维码不到 3 秒
JSON 输出无缝集成 CI/CD 流水线
扫码统计数据直接在终端查看

安装和配置

安装 CLI

npm install -g @codebox.club/cli

安装后终端即可使用 codebox 命令：

codebox --version
# 0.1.0

配置 API Key

前往 CodeBox Dashboard 创建 API Key，然后配置：

codebox config set api-key cb_sk_你的密钥

验证配置：

codebox config list
# api-key  cb_sk_...xxxx

创建你的第一个二维码

codebox qr create "https://your-website.com" --name "官网入口"

输出：

+ QR code created
ID          clxxxxxxxxxxxxxxxxxx
Short Link  https://www.codebox.club/s/AbCdEf
Template    default
Keywords    -

使用模板

先搜索合适的模板：

codebox template search "科技"

然后指定模板创建：

codebox qr create "https://your-app.com" --template tech-modern-01 --name "产品码"

或者让系统根据关键词自动匹配：

codebox qr create "https://shop.com" --keywords 餐饮 美食 --name "餐厅点餐码"

查看和管理二维码

列表查看

# 查看所有二维码
codebox qr list

# 只看动态码
codebox qr list --mode DYNAMIC

# 翻页
codebox qr list --page 2 --size 20

更新目标 URL

动态二维码的强大之处——不用重新印刷，直接更新目标：

codebox qr update <id> --url "https://new-landing-page.com"

查看扫码统计

codebox qr stats <id>

输出设备分布、浏览器分布、地域分布等完整统计数据。指定日期范围：

codebox qr stats <id> --start-date 2026-03-01 --end-date 2026-03-24

批量生成

准备一个 JSON 文件 batch.json：

[
  { "content": "https://shop.com/product/1", "name": "商品1", "mode": "DYNAMIC" },
  { "content": "https://shop.com/product/2", "name": "商品2", "mode": "DYNAMIC" },
  { "content": "https://shop.com/product/3", "name": "商品3", "mode": "DYNAMIC" }
]

一条命令批量创建：

codebox qr batch batch.json

输出：

+ Batch complete: 3/3 succeeded, 0 failed
INDEX  STATUS  ID                     LINK                                    ERROR
-----  ------  ---------------------  --------------------------------------  -----
0      OK      clxxx...               https://www.codebox.club/s/xxx          -
1      OK      clyyy...               https://www.codebox.club/s/yyy          -
2      OK      clzzz...               https://www.codebox.club/s/zzz          -

CI/CD 集成

GitHub Actions

在部署流水线中自动为每个版本生成追踪二维码：

name: Deploy & Generate QR
on:
  push:
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # ... 你的部署步骤 ...

      - name: Generate QR Code
        env:
          CODEBOX_API_KEY: $\{{ secrets.CODEBOX_API_KEY }}
        run: |
          npm install -g @codebox.club/cli
          codebox qr create "$DEPLOY_URL" \
            --name "Release $\{{ github.ref_name }}" \
            --json > qr-result.json

脚本自动化

导出所有二维码的统计数据：

#!/bin/bash
codebox qr list --size 50 --json | jq -r '.data[].id' | while read id; do
  echo "=== $id ==="
  codebox qr stats "$id"
  echo
done

JSON 输出模式

所有命令添加 --json 即可输出结构化 JSON，方便程序处理：

# 获取二维码列表的 JSON
codebox qr list --json

# 用 jq 提取特定字段
codebox qr list --json | jq '.data[] | {id, name, scanCount}'

# 保存统计数据到文件
codebox qr stats <id> --json > analytics.json

Webhook 管理

在终端快速配置扫码事件推送：

# 创建 Webhook
codebox webhook create "https://your-server.com/hooks" --events scan.created qrcode.created

# 查看 Webhook 列表
codebox webhook list

# 暂停 Webhook
codebox webhook update <id> --status DISABLED

常见问题

如何在多台电脑上使用？

每台电脑运行一次 codebox config set api-key 即可。配置保存在 ~/.codeboxrc。

静态码和动态码有什么区别？

静态码（--mode STATIC）：内容直接编码在图片中，不消耗额度，但无法追踪扫码数据
动态码（--mode DYNAMIC）：通过短链接跳转，支持更新目标 URL 和查看扫码统计，每个消耗 1 次额度

额度不足怎么办？

CLI 会提示 CREDIT_EXHAUSTED 错误。前往 Dashboard 充值购买额度包，充值后立即生效。

如何连接自部署的 CodeBox？

codebox config set base-url https://your-codebox-server.com

下一步

API 文档：了解完整的 REST API 接口
SDK 文档：在 Node.js 项目中集成 SDK
MCP Server：让 AI Agent 调用二维码能力

终端生成二维码：CodeBox CLI 完全使用指南