# Shoplazza CLI 概述

> Shoplazza CLI v2 带来了什么：三层命令体系、OAuth 2.0 认证与结构化输出，用于构建 Shoplazza 应用、主题和扩展。

Shoplazza CLI 是一个命令行工具，用于构建 Shoplazza 应用、主题和扩展。它覆盖完整的开发生命周期——从项目脚手架、本地开发到部署和版本管理。

## v2 新特性

Shoplazza CLI v2 是一次全面重写，引入了**三层命令体系**、OAuth 2.0 认证和面向人类开发者与 AI Agent 的结构化输出。

### 三层命令体系

| 层级 | 前缀 | 用途 | 示例 |
|------|------|------|------|
| **快捷命令** | `+` | 高频操作，智能默认值 | `shoplazza products +search --keyword "shirt"` |
| **API 命令** | — | 与平台 API 1:1 映射 | `shoplazza products list --format table` |
| **原始 API** | `api rest` | 任意端点的逃生舱 | `shoplazza api rest GET /openapi/2026-01/products` |

详见 [三层命令体系](./guides/command-layers)。

### 核心能力

* **应用生命周期** — 使用 `app init`、`app dev`、`app deploy` 初始化、开发和部署应用
* **主题开发** — 脚手架、预览、推送和发布主题
* **扩展开发** — 使用内置工具链构建 Checkout 扩展和 Theme 扩展
* **店铺数据** — 通过快捷命令和 API 命令管理商品、订单、客户、折扣等
* **计费与 Webhook** — 创建订阅和注册事件钩子
* **Schema 自省** — 使用 `shoplazza schema` 探索所有可用 API

### 业务域覆盖

| 业务域 | 快捷命令 | API 命令数 |
|--------|----------|-----------|
| 商品 | `+search`, `+create`, `+set-price`, `+stock`, `+publish`, `+unpublish`, `+count` | 78 |
| 订单 | `+search`, `+count`, `+ship`, `+refund`, `+update-tracking` | 36 |
| 折扣 | `+search`, `+rebate`, `+flashsale`, `+mn-discount`, `+percent-code`, `+amount-code`, `+bxgy-code`, `+free-shipping-code` | 15 |
| 客户 | `+search`, `+create` | 11 |
| 店铺 | `+upload-file` | 64 |
| 主题 | `init`, `serve`, `pull`, `push`, `package`, `share` | 15 |
| 计费 | — | 14 |
| Webhook | — | 6 |

## 安装

参见 [安装 Shoplazza CLI](./install)。

## 快速开始

## 命令参考

查看 [命令参考](./commands/) 了解所有可用命令。

## 认证

Shoplazza CLI v2 使用 OAuth 2.0 + PKCE 进行安全认证。支持浏览器交互式登录和 CI/CD 环境下使用 UAT 令牌的非交互式认证。

详见 [认证](./authentication)。

## 输出格式

所有命令通过全局 `--format` 参数支持结构化输出：

| 格式 | 说明 |
|------|------|
| `json` | 结构化 JSON（默认）— 适合脚本和 AI Agent |
| `pretty` | 人类可读的键值对显示 |
| `table` | 带表头的制表符分隔表格 |

还可以使用 `--jq` 表达式过滤 JSON 输出，使用 `--dry-run` 预览请求。

详见 [输出格式](./guides/output-formats)。

## 升级

```shell
npm update -g shoplazza-cli
```

查看当前版本：

```shell
shoplazza version
```

## 主题开发

主题相关的 CLI 使用说明，请参见 [主题 CLI 指南](/zh-CN/docs/theme/developer-tools/shoplazza-cli/)。