> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 苏小强 CLI

> 使用 sxq 把 superun 项目同步到本地、推送代码、预览编译、正式上线并执行数据库迁移。

**苏小强 CLI** 用于在 superun 项目和本地目录之间同步文件，终端命令是 `sxq`。你可以在熟悉的 IDE 或 AI 编程智能体中修改项目，再把改动推送回 superun、生成预览并正式上线。

<Note>
  苏小强 CLI 与 superun 产品内的 AI 助手“苏小强”名称相同，但不是同一个东西。产品内的苏小强负责咨询和使用帮助；`sxq` 命令负责从终端管理项目。
</Note>

它是**项目开发和发布工具**，不能替代用于操作线上业务数据和接口的 [superun CLI](/superun/cli/superun-cli)。

## 准备工作

你需要：

* Node.js 18 或更高版本；
* 目标 superun 项目的访问权限；
* 项目的 `sessionId`，可以在 superun 项目页面的 URL 中找到。

## 安装并登录

```bash theme={null}
npm install -g suxiaoqiang-cli
sxq login
```

`sxq login` 会打开浏览器完成授权。也可以使用已有 token：

```bash theme={null}
sxq login --token <token>
```

## 关联并拉取项目

创建一个空目录，把它关联到远端项目，然后拉取文件：

```bash theme={null}
mkdir my-app
cd my-app
sxq link <sessionId>
sxq pull
```

关联时会校验项目是否属于当前账号。首次拉取为全量拉取，之后为增量拉取并进行三方合并。

## 修改并推送代码

完成本地修改后，把改动推送回 superun：

```bash theme={null}
sxq push -m "调整首页文案"
```

`sxq push` 会先拉取远端变化。如果文件无法自动合并，命令会中止，并在文件中写入 Git 风格的 `<<<<<<<`、`=======` 和 `>>>>>>>` 冲突标记。

处理全部冲突、删除标记并测试后，再次运行 `sxq push`。项目 `.gitignore` 匹配的文件，以及 `node_modules`、`dist`、`.git` 等内置忽略项不会同步。

## 预览和正式上线

触发 debug 编译并等待预览地址：

```bash theme={null}
sxq publish
```

确认预览无误后，正式上线待发布版本：

```bash theme={null}
sxq deploy
```

只查看发布状态，不触发上线：

```bash theme={null}
sxq deploy --status
```

<Warning>
  `sxq deploy` 会改变线上应用，并可能产生云服务费用。确认前请检查关联项目、预览结果和目标区域。
</Warning>

## 执行数据库迁移

在 `supabase/migrations/` 下创建以下格式的迁移文件：

```text theme={null}
<数字>_<描述>.sql
```

建议使用时间戳作为前缀，例如：

```text theme={null}
supabase/migrations/20260709120000_create_orders.sql
```

然后执行远端还不存在的迁移：

```bash theme={null}
sxq db push
```

迁移按文件名顺序执行，遇到第一个失败后停止。迁移成功后，服务端会自动将文件保存为项目附件。不要通过 `sxq push` 推送迁移文件，CLI 会直接拦截。

## 命令速查

| 命令                                                   | 用途                     |
| ---------------------------------------------------- | ---------------------- |
| `sxq login [-y] [--token <token>]`                   | 通过浏览器授权，或校验并使用已有 token |
| `sxq link <sessionId> [-y]`                          | 把当前目录关联到项目             |
| `sxq pull`                                           | 拉取并合并远端项目文件            |
| `sxq push [-m <message>]`                            | 先拉取；没有冲突时再推送本地改动       |
| `sxq publish`                                        | 编译 debug 预览并输出地址       |
| `sxq deploy [-y] [-m <message>] [--region CN\|INTL]` | 上线待发布版本并等待完成           |
| `sxq deploy --status`                                | 查看待上线和已发布版本，不触发上线      |
| `sxq db push`                                        | 执行新增的 SQL 迁移           |
| `sxq config set\|get\|unset\|list`                   | 管理 `host` 和 `lang` 配置  |
| `sxq upgrade`                                        | 从 npm 升级 CLI           |

在 CI 或 AI 智能体中，可以为需要确认的命令添加 `-y`。在非交互环境中，CLI 会直接报错并给出提示，不会一直等待输入。

<CardGroup cols={2}>
  <Card title="npm 上的苏小强 CLI" icon="npm" href="https://www.npmjs.com/package/suxiaoqiang-cli">
    查看已发布的软件包和当前版本。
  </Card>

  <Card title="源代码" icon="github" href="https://github.com/AiGuangInc/suxiaoqiang-cli">
    阅读完整参考资料或提交问题。
  </Card>
</CardGroup>