> ## 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.

# superun CLI

> 使用 superun CLI，以當前使用者身份操作執行中應用的資料、RPC 和 Edge Functions。

**superun CLI** 把執行中應用的後端能力帶到終端機。它可以查詢和修改 PostgREST 資料、呼叫 Postgres RPC，並通過 OpenAPI 清單發現和呼叫 Edge Functions。

它用於**操作和自動化應用**，不負責下載專案原始碼或發佈專案。如需本地開發和上線，請使用[蘇小強 CLI](/superun/cli/suxiaoqiang-cli)。

## 準備工作

你需要：

* Node.js 20 或更高版本；
* 你有權使用的應用後端 URL 和 anon key；
* 該應用支援的一種登入方式。

對於在 superun 中建立的應用，建議從 **研發 → 技能庫 → Agent 友好** 開始。系統生成的安裝指引已包含當前應用的配置，也是連線可信 AI 助手的推薦方式。詳見 [Agent 友好](/superun/integrations/agent-friendly)。

## 安裝

```bash theme={null}
npm install -g superun-cli
```

確認 `superun` 命令可用：

```bash theme={null}
superun --version
```

## 連線應用並登入

註冊後端，並為它設定一個本地別名：

```bash theme={null}
superun init \
  --name shop \
  --url https://<project>.supabase.co \
  --anon-key <anon-key>
```

然後以應用使用者身份登入：

```bash theme={null}
superun login --browser
```

如果已有 access token，也可以直接使用：

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

執行寫操作前，先確認當前身份：

```bash theme={null}
superun whoami
```

## 操作應用資料

```bash theme={null}
# 檢視開放的表和 RPC
superun db tables

# 查詢資料
superun db select orders --eq status=pending --limit 20

# 插入資料
superun db insert notes --data '{"body":"明天跟進"}'

# 更新匹配的資料
superun db update orders --eq id=42 --data '{"status":"paid"}'

# 呼叫 Postgres 函式
superun db rpc sales_summary --data '{"days":7}'
```

`update` 和 `delete` 預設必須帶過濾條件。只有顯式新增 `--all` 才能執行全表操作。

所有請求都使用當前使用者的會話，因此應用的行級安全策略（RLS）仍然生效。命令只能訪問當前登入使用者有權訪問的資料。

## 呼叫 Edge Functions

CLI 會從應用的 OpenAPI 清單發現應用專屬函式。建議從分組逐級檢視到單個函式：

```bash theme={null}
# 檢視函式分組
superun fn

# 檢視一個分組中的函式
superun fn <tag>

# 檢視單個函式的輸入輸出約定
superun fn <tag> <name> --help

# 呼叫函式
superun fn <tag> <name> --data '{"orderId":"42"}'
```

應用接口發生變化後，重新整理本地快取的函式清單：

```bash theme={null}
superun app refresh
```

## 管理多個應用

```bash theme={null}
superun app list
superun app use <alias-or-id>
superun app show
```

如需只讓一條命令使用另一個已配置應用，可新增 `-a`，無需切換當前應用：

```bash theme={null}
superun -a staging db tables
```

## 命令速查

| 類別             | 命令                                                                                      |
| -------------- | --------------------------------------------------------------------------------------- |
| 應用配置           | `init`、`app list`、`app use`、`app show`、`app set`、`app refresh`、`app remove`、`app where` |
| 身份認證           | `login`、`whoami`、`logout`                                                               |
| 資料和 RPC        | `db tables`、`db select`、`db insert`、`db update`、`db delete`、`db rpc`                    |
| Edge Functions | `fn`、`fn <tag>`、`fn <tag> <name>`                                                       |

使用 `superun <command> --help` 檢視全部引數和輸入要求。

## 安全與排查

* 敏感寫操作前，先執行 `superun app show` 和 `superun whoami`。
* access token 和 refresh token 都屬於敏感憑據。只把 Agent 友好安裝指引交給可信的 AI 助手或執行環境。
* `401` 通常表示當前會話對這個後端已失效。請使用同一應用簽發的 token 重新登入。
* 如果 `superun fn` 為空或內容過期，請執行 `superun app refresh`。應用必須提供有效的 CLI 清單才能發現函式。
* 資料庫和函式呼叫可能立即產生業務影響，執行前請檢查命令和請求資料。

<CardGroup cols={2}>
  <Card title="npm 上的 superun CLI" icon="npm" href="https://www.npmjs.com/package/superun-cli">
    檢視已發佈的軟體套件和當前版本。
  </Card>

  <Card title="原始碼" icon="github" href="https://github.com/AiGuangInc/superun-cli">
    閱讀完整參考資料或提交問題。
  </Card>
</CardGroup>