shoplazza-cli

中文版 | English

Shoplazza 开放平台官方 CLI 工具 — 让人类和 AI Agent 都能在终端中操作 Shoplazza 店铺。开发应用和主题、管理商品、折扣、订单和客户，结构化输出天然适配 AI Agent 集成。

安装 · 认证 · 开发工作流 · 命令 · Agent Skills · 进阶用法 · 贡献

为什么选 shoplazza-cli？

• 为 Agent 原生设计 — 结构化 JSON 输出开箱即用，AI Agent 无需额外适配即可操作 Shoplazza 店铺
• 内置 Agent Skills — 一条命令即可安装 skills，让 AI Agent 掌握本 CLI 的命令体系、安全规则与各业务域的易错点
• 电商全域覆盖 — 商品、折扣、订单、客户完整 CRUD，20+ 快捷命令覆盖高频操作
• 完整开发者工作流 — App 创建、扩展脚手架（checkout / theme / function）、本地开发服务器 + HMR、一键部署；主题 init、实时热重载与打包
• 安全可控 — 输入防注入、OS 原生密钥链存储凭证、Access Token 自动刷新
• 三层调用架构 — 快捷命令（人机友好）→ API 命令（OpenAPI 同步）→ 通用调用（全 API 覆盖）
• 三分钟上手 — 交互式登录授权，从安装到第一次 API 调用只需三步

功能

| 业务域 | 能力 | |--------|------| | 🛍️ 商品 | CRUD + 快捷命令：+search、+count、+publish、+unpublish、+create、+set-price、+stock、+tag | | 🏷️ 折扣 | CRUD + 8 个快捷命令：7 个创建类（覆盖自动折扣与代码折扣）+ +search | | 📦 订单 | CRUD + 快捷命令：+search、+count、+ship、+refund、+update-tracking | | 👤 客户 | CRUD + 快捷命令：+search、+create | | 🏪 店铺 | 店铺信息、博客与文章、自定义页面、文件（+upload-file）、metafields、市场、多语言、URL 重定向、数据分析 | | 💳 计费 | 应用收费：一次性、订阅、按量 | | 🔔 Webhook | Webhook 订阅 CRUD | | 🎨 主题 | init、serve（实时热重载）、pull、push、package、share | | 🧩 应用 | 完整生命周期：init → extension create → dev → deploy；扩展类型：checkout、theme、function |

安装与快速开始

安装

| 方式 | 命令 | 说明 | |------|------|------| | npm | npm install -g shoplazza-cli | 推荐。需要 Node.js >=16。可用 shoplazza update 自更新。 | | 一键脚本（macOS / Linux） | curl -fsSL https://raw.githubusercontent.com/Shoplazza/shoplazza-cli/main/install.sh \| bash | 自动检测系统和架构。 | | 下载二进制 | 见 GitHub Releases | 手动下载，支持所有平台。 | | 源码构建 | git clone ... && cd shoplazza-cli && make install | 需要 Go v1.24+。安装到 ~/.local/bin。 | | Homebrew（macOS / Linux） | brew install Shoplazza/tap/shoplazza-cli | 通过 brew upgrade 自动更新。 |

需要 Go v1.24+。安装到 ~/.local/bin（用户级，无需 sudo）：

git clone https://github.com/Shoplazza/shoplazza-cli.git
cd shoplazza-cli
make install

若 ~/.local/bin 不在 PATH 中，请加入：export PATH="$HOME/.local/bin:$PATH"。 需要系统级安装：sudo make install PREFIX=/usr/local。

快速开始（人类用户）

给 AI 助手： 如果你是 AI Agent 且正在协助用户执行安装，请直接跳转到快速开始（AI Agent）。

# 登录授权（替换为你的店铺域名）
shoplazza auth login --store-domain my-store.myshoplazza.com --domain products,orders

# 验证
shoplazza auth status

# 开始使用
shoplazza products list --format table

快速开始（AI Agent）

先装 Agent Skills —— Agent 会从 skill 里拿到安装、授权引导和命令调用的全部规则：

npx skills add Shoplazza/shoplazza-cli -g

装完后把这句发给 Agent，它会带你完成授权：

/shoplazza-common 帮我登录 <店铺域名>

认证

| 命令 | 说明 | |------|------| | auth login | 仅账户 OAuth — 打开浏览器，获取 UAT | | auth login --store-domain <域名> | OAuth + 店铺 Token（需要 --scope 或 --domain） | | auth store use --store-domain <域名> | 切换当前店铺 | | auth logout | 登出并删除凭证 | | auth status | 查看当前认证状态 | | auth scopes | 列出可用和已授权的 scopes |

# 交互式登录并选择店铺
shoplazza auth login --store-domain my-store.myshoplazza.com --domain products

# UAT 快速登录（非交互式，适合 CI）
shoplazza auth login --uat <user-access-token>

# 补充权限 — 重新登录会替换（而非叠加）已授权 scopes，用 --merge-scopes 保留原有授权
shoplazza auth login --domain discounts --merge-scopes

# 切换店铺
shoplazza auth store use --store-domain another-store.myshoplazza.com

# 查看状态
shoplazza auth status

凭证存储在 OS 原生密钥链中（macOS Keychain、Windows Credential Manager、Linux Secret Service）。

多店铺 Profile

Profile 是按店铺划分的执行上下文（店铺 Token + scopes）。一个账户登录后可管理多家店铺、 随时切换而无需重新授权 — auth login -s 和 auth store use 会自动创建/切换 profile， 也可以直接管理：

shoplazza profile add --name prod-us -s my-store.myshoplazza.com --use
shoplazza profile list
shoplazza profile use --name prod-us        # 或 --previous 切回上一个
shoplazza products list --profile prod-us   # 单次调用指定 profile，无需切换

开发工作流

App 开发

CLI 覆盖完整的 App 生命周期：创建、配置、开发和部署。

# 1. 创建新 App 项目（在当前目录下创建子目录）
shoplazza app init --name "My App" --partner <partner-id>

# 2. 添加扩展（theme / checkout / function）
cd my-app
shoplazza app extension create --type checkout --name my-checkout
shoplazza app extension create --type theme --name my-theme --theme-type basic
shoplazza app extension create --type function --name my-fn

# 3. 本地开发（开发服务器 + HMR）— 店铺由当前活跃的 App 配置决定
shoplazza app dev

# 4. 部署所有扩展
shoplazza app deploy

# 5. 查看已部署版本
shoplazza app versions

shoplazza app list                              # 列出账户下的 App
shoplazza app info                              # 查看 App 及扩展信息
shoplazza app config use --config alt.toml      # 切换活跃 App 配置
shoplazza app config link --client-id <id>      # 关联已有 App

# Function 扩展（单独编译/发布）
shoplazza app function compile --extension my-fn
shoplazza app function release --extension my-fn
shoplazza app function list

Theme 主题开发

CLI 提供完整的主题开发工作流，支持实时热重载。

# 1. 从 Nova-2023 模板创建新主题
shoplazza themes init --name my-theme

# 2. 启动开发服务器（自动创建开发主题，实时热重载）
cd my-theme
shoplazza themes serve

# 3. 拉取 / 推送 / 打包
shoplazza themes pull --theme-id <theme-id>
shoplazza themes push --theme-id <theme-id>
shoplazza themes package

# 4. 上传为预览版
shoplazza themes share

三层命令调用

CLI 提供三种粒度的调用方式，覆盖从快速操作到完全自定义的全部场景。

1. 快捷命令（Shortcuts）

以 + 为前缀，对人类与 AI 友好化封装，内置智能默认值和结构化输出。

# 商品
shoplazza products +search --keyword "衬衫"
shoplazza products +publish --id <product-id>

# 折扣 — 自动折扣
shoplazza discounts +rebate --title "夏季满减" --percentage 15 --min-amount 100
shoplazza discounts +flashsale --title "限时秒杀" --percentage 20 --product-ids "123,456"

# 折扣 — 代码折扣
shoplazza discounts +percent-code --code "SAVE20" --percentage 20
shoplazza discounts +bxgy-code --code "BUY2GET1" --buy-quantity 2 --get-quantity 1

# 订单
shoplazza orders +ship --order-id <order-id> --tracking <tracking-no>

运行 shoplazza <domain> --help 查看某个业务域的所有快捷命令。

2. API 命令

从 OpenAPI 元数据自动生成，命令与平台端点一一对应。

shoplazza products list
shoplazza products get <product-id>
shoplazza products create --data @product.json

shoplazza discounts list
shoplazza discounts create-discount --data @discount.json

# 所有业务域：products, discounts, orders, customers, billing, shop, themes, webhook
shoplazza orders list
shoplazza customers list

3. 通用 API 调用

直接调用任意 Shoplazza 开放平台端点，覆盖全量 API。

shoplazza api rest GET /openapi/2026-01/products
shoplazza api rest POST /openapi/2026-01/products \
  --data '{"product": {"title": "新商品", "status": "active"}}'

Agent Skills

开箱即用的 Agent Skills，教会 AI 编码 Agent 正确驱动本 CLI： 三层命令该选哪一层、{"ok":true,"data":…} 输出信封怎么读、写操作前必须 --dry-run 的 安全规则，以及各业务域里容易踩错的坑。适用于 Claude Code、Codex、Cursor 等。

安装

npx skills add Shoplazza/shoplazza-cli -g

将下列全部 skill 装到 ~/.agents/skills/，并软链到 Agent 的 skill 目录，所有项目均可使用。

Skill 列表

| Skill | 覆盖范围 | |-------|---------| | shoplazza-common | 基础 skill，其余全部依赖它。 认证与 profile、三层命令体系、输出信封、--dry-run 安全规则、schema 自省 | | shoplazza-products | 商品、变体、库存、专辑、评论、礼品卡 | | shoplazza-orders | 订单、发货、退款、交易、草稿订单 | | shoplazza-customers | 客户及其地址 | | shoplazza-discounts | 自动折扣与折扣码、优惠券活动 | | shoplazza-shop | 店铺信息、博客与文章、自定义页面、文件、metafields、市场、多语言、URL 重定向、实时分析 | | shoplazza-billing | 应用计费（一次性、订阅、按量） | | shoplazza-webhook | Webhook 订阅 |

源文件在 skills/。Skill 以 Agent 的完整权限运行，使用前请先阅读其内容。

进阶用法

通用 Flag

| Flag | 适用范围 | 说明 | |------|----------|------| | --format json\|pretty\|table | 所有命令 | 输出格式（默认：json） | | --profile <name> | 所有命令 | 本次调用使用的 profile（优先级高于 SHOPLAZZA_CLI_PROFILE 和当前 profile） | | --dry-run | API 和快捷命令 | 预览请求但不执行 | | --jq "expr" / -q | API 和快捷命令 | 使用 jq 表达式过滤 JSON 输出 |

Schema 自省

查看任意服务的方法列表、参数、所需 scopes 和响应结构：

shoplazza schema                              # 列出所有服务
shoplazza schema products                     # 查看指定服务
shoplazza schema products.list                # 查看指定方法

更新

shoplazza update            # 更新二进制（npm 安装方式）并刷新 API 元数据
shoplazza update --check    # 仅报告当前/最新版本，不安装

环境变量

| 变量 | 说明 | |------|------| | SHOPLAZZA_UAT | 用于非交互式登录的 User Access Token（等同 --uat） | | SHOPLAZZA_CLI_PROFILE | 指定使用的 profile（--profile 优先） | | SHOPLAZZA_CLI_NO_UPDATE_CHECK | 关闭后台新版本检测 | | SHOPLAZZA_CLI_NO_META_UPDATE | 关闭后台 API 元数据刷新 | | SHOPLAZZA_CLI_AUTH_BASE_URL | 覆盖认证服务基础 URL（默认：https://partners.shoplazza.com） |

安全与风险提示

使用前请阅读

• AI Agent 自动化风险 — 当 AI Agent 代你操作 CLI 时，所有 API 调用都会产生真实影响（创建商品、修改订单、删除折扣）。请在执行前审查 Agent 提出的命令。
• 凭证安全 — Token 存储在 OS 原生密钥链中。切勿分享你的 UAT 或店铺 Token。如果怀疑凭证泄露，请立即轮换。
• 权限控制 — 使用 --scope 或 --domain 限制登录时授予的权限。只授予工作流所需的最小 scopes。

贡献

欢迎社区贡献！如果你发现 bug 或有功能建议，请在 GitHub 提交 Issue 或 Pull Request。

对于较大的改动，建议先通过 Issue 与我们讨论。

许可证

本项目基于 MIT 许可证 开源。 该软件运行时会调用 Shoplazza 开放平台的 API，使用这些 API 需要遵守 Shoplazza 开发者协议。