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