> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.com/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>