---
title: "CLI"
description: "beeuni 命令行工具、其身份验证模型、开发迭代流程以及所有命令。"
---

`beeuni` 命令行界面（CLI）可通过终端（你的笔记本电脑或会话沙箱）控制 Beeuni。本页介绍日常开发循环，然后列出所有稳定的命令和标志。

<a id="install"></a>

## 安装

```sh
curl -fsSL https://beeuni.ai/install | bash
```

安装程序会为 macOS 和 Linux 下载预构建的二进制文件。不支持 Windows。

| 命令 | 作用 |
| --- | --- |
| `beeuni update` | 重新运行安装脚本并获取最新的二进制文件。 |
| `beeuni uninstall [-y\|--yes] [--keep-auth] [--keep-home]` | 移除二进制文件、`/usr/local/bin` shim 和已存储的令牌。`--keep-auth` 会保留令牌。`--keep-home` 会保留 `~/.beeuni`。 |
| `beeuni version` | 打印 CLI 版本。 |

<a id="auth-model"></a>

## 身份验证模型

Beeuni 按主机存储身份验证信息，而非全局存储。主机是一个 Beeuni API 端点。使用 `cloud` 连接到 Beeuni。

配置文件位于 `~/.config/beeuni/config.json`，权限模式为 `0600`。使用 `BEEUNI_CONFIG_FILE` 覆盖其路径。

CLI 遵循以下层级：主机 → 账户 → 项目 → 会话。你登录主机，在其中选择账户，在该账户中选择项目，然后在项目中开启会话。`beeuni hosts login` 会依次执行前三个步骤：登录、选择账户，然后设置默认项目。

每个令牌都以 `beeuni_pat_` 开头。用户令牌来自 `beeuni login`，可访问你所属的所有账户和项目。项目令牌会为会话沙箱自动签发，并限定于单个项目。请参阅[令牌范围](#token-scope)。

<a id="the-dev-loop"></a>

## 开发循环

本循环假设已安装 CLI 并运行过 `beeuni login`。请参阅[快速入门](/docs/zh/quickstart)了解设置方法。

1. **关联代码仓库**

    启动新项目，或将现有代码仓库文件夹关联到项目。

    创建新项目的脚手架：

    ```sh
    beeuni init my-app
    cd my-app
    ```

    `beeuni init` 会使用通用入门模板创建项目目录。其
    `beeuni.yaml` 声明 `beeuni_version: 2` 并运行 默认运行时
    [运行框架](/docs/zh/work/harnesses)。

    将已有的克隆代码仓库关联到已创建的项目：

    ```sh
    beeuni projects link <project-id>
    ```

    此命令会在当前目录写入 `.beeuni/link.json`。Beeuni 每次从此文件夹运行命令时，都会读取该文件以查找你的项目。如果你打算先运行 `beeuni ship`，请跳过此步骤。如果尚无关联项目，它会为你关联一个新项目。

2. **提交代码**

    ```sh
    beeuni ship
    ```

    `beeuni ship` 会检查你的 `beeuni.yaml`、提交本地更改、推送分支，并提示你补齐任何缺失的密钥或连接。每次想要将本地更改同步到云端项目时，都运行此命令。如果尚未关联项目，首次运行还会创建云端项目和代码仓库。

3. **运行并连接会话**

    使用提示启动会话：

    ```sh
    beeuni sessions new --prompt "Build the login page" --wait
    ```

    每个会话都在自己的沙箱和分支中运行。`--wait` 会一直等待，直到会话就绪。

    从终端连接到会话：

    ```sh
    beeuni connect
    ```

    如果没有会话 ID，`beeuni connect`（别名：`attach`）会打开绑定项目的会话选择器——运行中的会话会立即连接，已停止的会话会先启动，而 `+ New session` 会启动一个全新的沙箱——然后进入连接到该会话的完整 默认运行时 TUI。传入 ID 可跳过选择器：`beeuni connect <session-id>`。

    CLI 会为你管理 `opencode` 二进制文件：首次连接时，它会下载会话服务器运行的确切版本，并将其缓存在 `~/.beeuni/opencode/<version>/` 下，确保 TUI 和服务器版本始终一致。设置 `BEEUNI_OPENCODE_BIN` 可强制使用你自己的二进制文件。

    pi [运行框架](/docs/zh/work/harnesses)中的会话没有 默认运行时 服务器。
    `beeuni connect` 遇到此类会话时会以状态码 1 退出，并显示消息 `This session's runtime does
    not support attaching a terminal client.`

    如需使用更轻量的逐行聊天，而非完整 TUI，请运行：

    ```sh
    beeuni sessions chat
    ```

    这会打开与你最近一次会话的交互式聊天。添加 ID 可指定某个会话：`beeuni sessions chat <id>`。

    如需在终端中使用完整产品——会话列表、对话记录和撰写框、沙箱中的 shell，以及 Files、Review、Apps、Customize 和 Account 界面——请运行实验性终端客户端：

    ```sh
    beeuni tui        # or: beeuni t, or beeunit
    beeunit --project <id> --new --terminal   # new session + sandbox shell, one command
    ```

    它会使用你当前所在主机的登录信息。请参阅[TUI 页面](/docs/zh/cli#sessions)。

    如需在沙箱中打开原始 shell（不涉及代理），请运行：

    ```sh
    beeuni sessions shell
    ```

    随时列出正在运行的会话：

    ```sh
    beeuni sessions ls
    ```

4. **通过更改请求进行审查**

    会话中有可供合并的提交时，代理会创建更改请求（CR）。你可以通过 CLI 列出、检查和合并这些请求。

    ```sh
    beeuni cr ls
    beeuni cr diff 1
    beeuni cr merge 1
    ```

    `beeuni cr ls` 会列出关联项目的更改请求。`beeuni cr diff <cr>` 会显示统一补丁。`beeuni cr merge <cr>` 会将其合并到项目的默认分支。可使用 CR 编号或完整 ID。

<a id="reference"></a>

## 参考

<a id="auth-commands"></a>

### 身份验证命令

| 命令 | 作用 |
| --- | --- |
| `beeuni login [--host <name>] [--api <url>] [--token <pat>] [--account <slug>] [--no-project]` | 登录当前主机或指定的主机。默认会打开浏览器；`--token` 可在无头模式下登录。`--no-project` 会跳过默认项目选择。 |
| `beeuni logout [--host <name>]` | 移除当前主机或指定主机的令牌。 |
| `beeuni whoami [--host <name>] [--json] [--token-only]` | 打印已登录用户和当前账户。 |
| `beeuni token [--host <name>]` | `beeuni whoami --token-only` 的快捷方式。 |

`beeuni hosts login` / `hosts logout` / `hosts whoami` 是规范形式。`login` / `logout` / `whoami` 是针对当前主机操作的快捷方式。

<a id="hosts"></a>

### 主机

| 命令 | 作用 |
| --- | --- |
| `beeuni hosts ls [--json]` | 列出所有主机及其身份验证状态。 |
| `beeuni hosts login [<name>] [--token <pat>] [--api <url>] [--account <slug>] [--no-project]` | 登录主机。若名称未知，则会先注册该主机。 |
| `beeuni hosts logout [<name>]` | 移除某个主机的令牌。 |
| `beeuni hosts use <name>` | 切换当前主机。 |
| `beeuni hosts add <name> --url <url> [--dashboard-url <url>] [--login]` | 注册新主机。`--login` 会在注册后立即登录。 |
| `beeuni hosts rm <name> [--force]` | 移除主机。 |
| `beeuni hosts info [<name>] [--json]` | 显示某个主机的详细信息。 |
| `beeuni hosts current [--json]` | 打印当前主机名称。 |

以 `http://` 开头的远程主机 URL 会规范化为 `https://`。CLI 绝不会通过纯 HTTP 向远程主机发送令牌。`localhost` 不受此限制。

<a id="accounts"></a>

### 账户

| 命令 | 作用 |
| --- | --- |
| `beeuni accounts ls [--json]` | 列出你在当前主机所属的账户。 |
| `beeuni accounts use [<slug-or-id>]` | 切换当前账户。 |
| `beeuni accounts current [--json]` | 打印当前账户。 |
| `beeuni accounts info [<slug-or-id>] [--json]` | 显示某个账户。 |

<a id="members"></a>

### 成员

查看账户成员及其账户角色。角色包括 `owner`、
`admin` 和 `member`。所有者和管理员在每个
项目中都隐式拥有 Manager 权限，因此只有 `member` 角色需要按项目单独授权。

| 命令 | 作用 |
| --- | --- |
| `beeuni members ls [--json]` | 列出成员、角色和项目数量。 |
| `beeuni members invite <email> --role admin\|member [--project <id>:<role>]` | 按电子邮件邀请。已有 Beeuni 账户的用户会立即加入；其他人会收到包含邀请链接的邮件。`--project` 可重复指定，并在接受邀请时生效。需要 `member.invite`。 |
| `beeuni members set-role <user\|email> --role owner\|admin\|member` | 更改账户角色。需要 `member.update`；`owner` 角色仅限所有者授予。 |
| `beeuni members rm <user\|email> [-y\|--yes]` | 移除成员并撤销其令牌。需要 `member.remove`。 |
| `beeuni members super-admin <user\|email> on\|off` | 授予或撤销超级管理员绕过权限。需要 `member.super_admin.grant`。 |
| `beeuni members invites ls [--json]` | 列出你发送的待处理邀请。 |
| `beeuni members invites cancel <invite-id>` | 取消一项待处理邀请。 |
| `beeuni members invites resend <invite-id>` | 重新发送邮件并刷新 14 天有效期。 |

`<user>` 是用户 ID，或已加入账户的人员的电子邮件地址。
选项：`--account <id>`、`--host <name>`、`--json`、`-y`。

<a id="groups"></a>

### 组

账户组是一组命名的人员集合，你可以一次性为其授予角色。使用 `beeuni access grant --group <id> --role <key>` 将组绑定到作用域；使用 `beeuni access revoke <assignment-id>` 撤销绑定。

| 命令 | 作用 |
| --- | --- |
| `beeuni groups ls [--json]` | 列出组及其成员数和项目数。 |
| `beeuni groups create <name> [--description <t>]` | 创建组。 |
| `beeuni groups set <group> [--name <n>] [--description <t>\|--no-description]` | 重命名组或修改组描述。 |
| `beeuni groups rm <group> [-y\|--yes]` | 删除组。其授权也会一并删除。 |
| `beeuni groups members <group> [--json]` | 列出组成员。 |
| `beeuni groups add <group> <user>...` | 添加一个或多个成员。 |
| `beeuni groups remove <group> <user>` | 移除一名成员。 |
| `beeuni groups projects <group> [--json]` | 列出该组可访问的项目及其角色。 |

`<group>` 可以是组 ID 或组的完整名称。读取操作需要 `group.read`。
`create`、`set` 和 `add` 需要 `group.update` 或 `group.members.manage`，以及企业 `rbac` 权益。`rm` 和 `remove` 用于清理，永远不受权益限制。

<a id="tokens"></a>

### 令牌

账户的非交互式凭据。读取操作需要 `token.read`。每位账户成员都可以创建和撤销自己的个人密钥（`token.personal.create`、`token.personal.revoke`）；个人密钥代表你操作，且携带的角色不会超过你自己的角色。服务账户和他人的密钥需要 `token.create` / `token.revoke`（所有者和管理员）。

| 命令 | 作用 |
| --- | --- |
| `beeuni tokens ls [--mine] [--json]` | 列出账户的个人 API 密钥。`--mine` 可缩小范围，仅显示你创建的密钥。 |
| `beeuni tokens new <name> [--expires <when>] [--project <id>]` | 创建密钥。密钥仅显示一次。`--project` 将其绑定到一个项目，且永远无法离开该项目。 |
| `beeuni tokens rm <token-id> [-y\|--yes]` | 立即撤销密钥。 |
| `beeuni tokens apps ls [--json]` | 列出你已连接的应用：你使用 Sign in with Beeuni 批准的应用和 MCP 客户端，涵盖所有账户。 |
| `beeuni tokens apps rm <client-id> [-y\|--yes] [--json]` | 撤销已连接的应用：其令牌会立即失效，并且必须再次请求授权。 |
| `beeuni tokens service-accounts ls [--json]` | 列出服务账户。 |
| `beeuni tokens service-accounts new <name> [--description <t>] [--expires <when>]` | 创建服务账户。持有者凭据仅显示一次。 |
| `beeuni tokens service-accounts disable <id>` | 停用服务账户：它将无法再进行授权；删除并重新创建后才能恢复。 |
| `beeuni tokens service-accounts rm <id> [-y\|--yes]` | 永久删除服务账户。 |

个人 API 密钥代表你操作，并随你的成员资格一同失效。服务账户代表自身操作，不会继承任何访问权限：新建的服务账户没有任何权限。使用 `beeuni access grant --service-account <id> --role <key>` 为其授予权限。
`--expires <when>` 接受 ISO-8601 时间或向前的时间跨度：`30d`、`12h`、`6w`、`1y`。

<a id="billing"></a>

### 计费

读取当前账户的套餐、额度和支出。仅支持读取：套餐变更、充值和付款方式需要在控制面板中操作。

| 命令 | 作用 |
| --- | --- |
| `beeuni billing status [--json]` | 套餐、额度、席位和订阅。 |
| `beeuni billing transactions [--limit <n>] [--offset <n>] [--type <a,b>] [--json]` | 额度账本，按最新时间排序。默认每页 50 条。 |
| `beeuni billing transactions --summary\|--breakdown\|--usage [--days <n>]` | 额度流入/流出、余额拆分（即将过期/不过期/每日），或额度使用摘要。`--days` 是 `--summary` 和 `--usage` 的时间窗口；默认为 30。 |
| `beeuni billing costs [--since <iso>] [--until <iso>] [--json]` | 统计账户在指定时间窗口内的支出，并按模型细分。默认窗口为 30 天，采用半开区间 `[from, to)` UTC。 |
| `beeuni billing costs --by project\|session [--sort <k>] [--limit <n>] [--offset <n>] [--csv <file>]` | 按项目或会话汇总支出。`--sort` 接受 `total_desc`（默认）、`total_asc`、`recent` 或 `name_asc`（仅限 `--by project`）。`--csv` 需要 `--by`。 |

过滤器：`--project <id>`、`--session <id>` 和 `--owner <id>`（会话，配合 `--by session`）。选项：`--account <id>`、`--host <name>`、`--json`。

<a id="projects"></a>

### 项目

命令按以下顺序解析“该项目”：

1. `--project` 标志。
2. `BEEUNI_PROJECT_ID` 环境变量。
3. 当前工作目录中准确匹配的 `.beeuni/link.json`。
4. 由 `beeuni projects use` 设置的全局默认项目。

| 命令 | 作用 |
| --- | --- |
| `beeuni projects ls [--all] [--query <text>] [--json]` | 列出当前账户中的项目。`--all` 会涵盖你所属的所有账户。`--query`（别名 `-q`）按名称、ID 或仓库过滤。 |
| `beeuni projects info [<id>] [--json]` | 显示一个项目。默认显示已关联或默认项目。 |
| `beeuni projects use [<id>]` | 设置全局默认项目。如果项目属于其他账户，则切换当前账户。 |
| `beeuni projects unset` | 清除全局默认项目。 |
| `beeuni projects link [<id>]` | 将当前目录绑定到项目。写入 `.beeuni/link.json`。 |
| `beeuni projects unlink` | 移除 `.beeuni/link.json`。 |
| `beeuni projects open [<id>]` | 在浏览器中打开项目的控制面板页面。 |
| `beeuni projects clone [<id>] [dir]` | 通过经过身份验证的 Beeuni git 代理克隆项目仓库。 |
| `beeuni projects rm [<id>] [-y\|--yes]` | 删除项目及其由 Beeuni 管理的 git 仓库。你自行连接的仓库永远不会被修改。 |
| `beeuni projects set [<id>] [--name <n>] [--branch <b>] [--manifest <path>] [--json]` | 更新一个项目的设置。只写入你传入的字段。不传入任何字段则退出 `2`。别名：`update`。 |
| `beeuni projects set [<id>] --icon <emoji>\|--no-icon\|--glyph <name>:<color>\|--no-glyph` | 设置或移除项目图标。 |
| `beeuni projects rename [<id>] <name>` | `beeuni projects set --name <name>` 的别名。 |
| `beeuni projects features [ls] [--json]` | 列出所有功能标志及其键、状态、来源和稳定性。 |
| `beeuni projects features enable\|disable\|reset <flag>` | 将项目覆盖设置为开启、关闭，或清除覆盖，使标志遵循平台默认值。 |
| `beeuni projects cli-tokens ls [--json]` | 列出项目的 CLI 令牌。 |
| `beeuni projects cli-tokens new [--name <name>] [--expires-at <iso>]` | 创建项目范围的 CLI 令牌。密钥仅显示一次。 |
| `beeuni projects cli-tokens rm <token-id> [-y\|--yes]` | 撤销一个项目 CLI 令牌。 |
| `beeuni projects upgrade [<id>] [--json]` | 启动代理会话，将 v1 `beeuni.toml` 迁移到 v2 `beeuni.yaml`，并创建变更请求。 |

一个项目只能显示一个图标，因此写入 `--icon` 会清除字形，写入 `--glyph` 会清除表情符号；同时传入两者会被拒绝。字形颜色：`grey`、`red`、`orange`、`yellow`、`lime`、`blue`、`purple`、`magenta`。`set` 和 `features` 需要 `project.settings.write`。如果平台将某个标志标记为不可用，无论项目覆盖设置如何，该标志都会保持关闭。

项目 CLI 令牌绑定到一个项目——API 会拒绝其在其他项目中的使用。会话沙箱使用其与会话绑定的 `BEEUNI_TOKEN`。`cli-tokens ls` 需要项目读取权限；`new` 和 `rm` 需要 `project.credentials.issue`。无论项目是否声明代理，会话绑定的令牌都不能创建或撤销项目令牌（`403`）。项目 CLI 令牌遵循账户的 PAT 政策：当账户要求过期时间时，传入 `--expires-at`；超过最大生命周期的过期时间会返回 `400`。

`beeuni projects upgrade` 需要项目写入权限。默认代理会刷新 marketplace 基线、重写清单、运行 `beeuni validate`，并创建变更请求。它绝不会合并：由人工审查差异。

<a id="project-scaffold"></a>

### 项目脚手架

`beeuni init [project-name] [options]` 创建新的项目目录。启动模板会写入 v2 `beeuni.yaml`、`agents/`、`skills/`、`memory/` 和 `harnesses/opencode/`。该命令可以配置本地编码工具发现，而不会更改云端 默认运行时 运行时。该命令不会写入 `.beeuni/link.json`。`beeuni ship` 或 `beeuni projects link` 会创建该文件。

| 标志 | 含义 |
| --- | --- |
| `--name <project>` | 项目名称。 |
| `--primary <agent>` | 主要代理。 |
| `--agents <csv>` | 要配置的本地编码代理集成。 |
| `--force` | 就地配置当前目录，而不是创建新的脚手架目录。 |
| `--overwrite` | 覆盖现有文件。 |
| `--no-git` | 跳过 git init。 |
| `-y, --yes` | 不提示。 |

本地编码工具选择不会更改云端 默认运行时 运行时。

`beeuni init` 不包含 marketplace 选择器。添加 marketplace 技能属于代理导入操作：启动会话并要求代理导入技能。

<a id="ship"></a>

### 发布

`beeuni ship` 会将当前分支暂存、提交并推送到项目的 git 仓库。首次运行时创建项目；之后可随时再次运行以同步。别名：`beeuni deploy`。

每次运行：
- 运行 [`beeuni validate`](#manifest-validation) 检查：`beeuni.yaml` 会检查与 [`imports:`](/docs/zh/project/manifest#imports) 中列出的每个文件合并后的内容、沙盒 Dockerfile、代理接线和仓库大小（使用 `--no-verify` 跳过）。出错会阻止发布，警告则不会。
- 提交工作树中的所有未提交更改（使用 `--no-commit` 跳过）。
- 提示输入缺失的 `env` 密钥（使用 `--no-env` 跳过）。
- 将当前分支推送到同名远程分支。
- 连接仍需授权的已声明连接器（使用 `--no-connect` 跳过）。

现有的 GitHub `origin` 会通过 Beeuni GitHub App 关联。其他任何现有的 `origin` 都会按原样注册。不提供 `origin` 时，会创建由 Beeuni 管理的 Git 仓库。

| 选项 | 作用 |
| --- | --- |
| `--name <project>` | 新项目的显示名称。 |
| `--account <id\|slug>` | 创建项目的账号（仅首次发布时）。 |
| `--origin <managed\|git-url>` | 覆盖推断出的来源选择。 |
| `--github-token <pat>` | 使用此令牌而非 GitHub App 关联 GitHub 来源。 |
| `-m, --message <text>` | 提交消息。 |
| `--no-commit` / `--no-verify` / `--no-env` / `--no-connect` | 跳过对应步骤。 |
| `-y, --yes` | 不提示。 |
| `-n, --dry-run` | 显示将执行的操作；不做任何更改。 |
| `--project <id>` / `--host <name>` | 指定非默认项目或主机。 |

<a id="apps"></a>

### 应用

Apps 可托管静态网站、服务器、后台任务和数据库。每个 App 有稳定的 URL。发布包含代码与配置；部署失败不会替换当前发布。

```bash
beeuni apps list
beeuni apps show main
beeuni apps connect main
beeuni apps launch --template convex --slug main
beeuni apps deploy dist --type static --spa
beeuni apps machines main
beeuni apps volumes main
```

通过 `uses` 连接应用，使用 `beeuni apps connect` 提供的连接示例。不要在客户端代码中放入管理凭据。

运行中的资源消耗账户额度，在 Billing 和 Usage 中查看余额与用量。Apps 不再单独设置月度预算。

[Apps](/docs/feature-flags/apps)

### 会话

每个会话都在自己的分支上的一个沙盒中运行。

| 命令 | 效果 |
| --- | --- |
| `beeuni sessions ls [--mine\|--shared\|--automated] [--search <q>] [--label <label>]... [--json]` | 列出会话。`--label` 可重复使用；会话必须带有每个指定标签。只要列出的会话中有任何一个带标签，就会显示 LABELS 列。 |
| `beeuni sessions status [--all] [--json]` | 显示所有会话及其代理当前正在执行的操作。别名：`overview`、`ps`。 |
| `beeuni sessions info <id> [--json]` | 详细视图：状态、分支、代理、沙箱 URL。 |
| `beeuni sessions new [--prompt "<text>"] [--agent <name>] [--model <id>] [--wait] [--connect] [--json]` | 启动会话。`--connect` 会在 默认运行时 TUI 就绪后将其连接上（隐含 `--wait`）；在没有该选项的交互式终端中，CLI 会在创建后询问是否连接。`--model <id>` 会覆盖项目的默认模型；通过 API 密钥或 ChatGPT 订阅运行的模型会使用你可用于该模型的所有密钥，并在这些密钥之间轮换。`--wait` 会阻塞，直到会话运行（最长约 5 分钟）。使用 `--secret <id>` 或 `--no-secrets` 缩小 Secret 的访问范围。这些 Secret 选项需要后端令牌。使用 `--connector <alias>=<authorization-id>` 或 `--no-connectors` 设置 Connector 访问权限。使用 `--require-connector <alias>` 要求在配置前进行授权。范围选项可重复使用。使用 `--context <key>=<value>` 传入非机密的运行时上下文。`--label <label>`（可重复使用）用于分类会话；`--meta <key>=<value>`（可重复使用）用于在会话元数据中存储字符串。 |
| `beeuni sessions chat [<id>] [--prompt "<text>"] [--queue \| --steer] [--new] [--agent <name>] [--json]` | 与会话的代理交谈。默认以交互方式运行。别名：`talk`。也可使用顶层命令 `beeuni chat`。`--queue` 仅限单次使用：将提示存入会话的持久收件箱后立即返回，而不是交给运行时处理。`--steer` 以同样方式存储提示，正在运行的轮次会在下一步读取它而不会停止。如果没有正在运行的轮次，则会启动一个轮次。无法接收指令的会话会将其作为 `--queue` 运行。 |
| `beeuni sessions connect [<id>] [-- <opencode args>]` | 将 默认运行时 TUI 连接到会话的 默认运行时 服务器。也可使用顶层命令：`beeuni connect` / `beeuni attach`。不指定 id 时，会打开会话选择器（运行中、已停止但可重启，或新建）。CLI 会自动下载版本匹配的 `opencode` 二进制文件（缓存位置：`~/.beeuni/opencode/<version>/`；覆盖项：`BEEUNI_OPENCODE_BIN`）。pi 会话没有 opencode 服务器：该命令会以 `1` 退出，并改为列出 `beeuni sessions shell` 和 `beeuni sessions chat`。 |
| `beeuni tui [--host <name>] [--project <id>] [--session <id>] [--new] [--agent <name>] [--terminal] [--no-sidebar] [--mouse] [--install] [--uninstall]` | **实验性功能。** 打开 Beeuni 终端客户端：会话、对话记录、编辑框、沙箱 Shell、Files、Review、Apps、Customize 和 Account。别名：`beeuni t` 和 `beeunit`。`--new` 会在启动时于项目中创建会话（`--agent` 选择代理），`--terminal` 会打开并聚焦沙箱 Shell，`--no-sidebar` 会在不显示侧边栏的情况下启动（`Alt+B` 可切换侧边栏），`--mouse` 会将鼠标交给应用（默认关闭，以便终端中的选择、复制和链接点击继续正常工作）。TUI 是独立的约 80 MB 二进制文件；首次运行时会询问，然后将版本匹配的 `beeuni-tui` 安装到 `~/.beeuni/tui/<version>/`；后续 CLI 更新会在不询问的情况下更新它，并复用未更改的二进制文件。`--install` 会在不提示的情况下执行此操作，`--uninstall` 会将其移除。默认使用当前主机，除非 `--host` 指定其他主机；如果没有主机登录，则会打开自己的登录屏幕。`?` 会打印所有按键绑定。参见 [/docs/cli#sessions](/docs/zh/cli#sessions)。 |
| `beeuni sessions shell [<id>] [--new]` | 在沙箱中打开原始交互式终端，不带代理。重新连接到会话已有的终端；`--new` 始终启动一个新终端。别名：`terminal`、`ssh`。 |
| `beeuni sessions shell <id> ls [--json]` | 列出会话的终端：id、状态、命令。无需 TTY。 |
| `beeuni sessions shell <id> kill <pty-id>` | 结束一个终端。下次连接时，环境 Shell 会重新启动；其中运行的任何程序都不会重新启动。 |
| `beeuni sessions forward <id> --port <sandbox>[:<local>]` | 将沙箱端口转发到你的机器，方式类似 VS Code，使代理打印的 `http://localhost:3000` 可在你自己的浏览器中使用。`--port` 可重复使用；未指定本地端口时，若同号端口空闲则使用该端口，否则使用下一个空闲端口；`:0` 会请求操作系统分配临时端口。HTTP 和 WebSocket 都会转发（开发服务器热重载可正常工作）。每条转发都会打印一行 `⇄ localhost:N → sandbox:M`，并在前台持续运行，直到按下 Ctrl+C。不会启动已停止的会话——而是打印解决方法 `beeuni sessions restart`。别名：`ports`。 |
| `beeuni sessions log [<id>] [--limit <n>] [--json]` | 只读地打印最近的消息。运行中的会话会实时读取；已停止的会话会从每轮结束时保存的对话记录中读取，因此不会仅为读取而唤醒会话。消息来源会写到 stderr，因此 `--json` 输出保持不变。别名：`messages`、`history`。 |
| `beeuni sessions attachments <id> [--download <attachment-id>\|--all] [--out <dir>] [--json]` | 列出并下载会话存储的文件——用户附加的文件，以及代理展示过的文件副本。会话停止时也可使用：列表和文件内容都不依赖其沙箱。下载不会覆盖文件；如果文件名已被占用，新文件名会变为 `name (1).ext`。 |
| `beeuni sessions pending <id> [--json]` | 列出待处理的工具权限或问题提示。别名：`prompts`。 |
| `beeuni sessions approve <id> [<req-id>] [--always] [--reject] [--message "<text>"]` | 回答权限提示。 |
| `beeuni sessions answer <id> [<req-id>] [--option <v>]... [--text "<text>"] [--reject]` | 回答问题提示。 |
| `beeuni sessions digest [--since <7d>] [--json]` | 多会话精简审阅。已停止会话的对话记录来自其保存的副本，并标记为 `saved`（如果该副本未包含第一条消息，还会标记为 `partial`）。别名：`review`、`summary`。 |
| `beeuni sessions scope <id> [scope options] [--json]` | 读取或替换 Secret 和 Connector 的访问权限。别名：`access`。管理 Secret 时使用 `--secret <id>`、`--no-secrets` 或 `--inherit-secrets`。管理 Connector 绑定时使用 `--connector <alias>=<authorization-id>` 或 `--no-connectors`。管理必需的 Connector 时使用 `--require-connector <alias>` 或 `--no-required-connectors`。指定的类别会替换当前值；未指定的类别保持不变。更改会在下一条提示中生效。如果会话已读取 Secret，则移除的 Secret 值仍会保留在现有上下文中。 |
| `beeuni sessions preview <id> [port] [--port <n>] [--list] [--json]` | 打印沙箱端口的可点击预览 URL。默认端口：`3000`。`--list` 会改为打印命名的候选项。 |
| `beeuni sessions restart <id>` | 重启会话的沙箱。 |
| `beeuni sessions rename <id> <name>` | 设置会话名称。传入 `""` 可清除名称。 |
| `beeuni sessions update [<id>] [--label <l>]... [--unlabel <l>]... [--clear-labels] [--meta <key>=<value>]... [--unmeta <key>]... [--json]` | 更改会话标签和元数据。`--label` 用于添加，`--unlabel` 用于移除，`--clear-labels` 会先清空列表；`--meta` 用于设置字符串键，`--unmeta` 用于移除键。不指定 id 时，会更新 `$BEEUNI_SESSION_ID`，以便代理为其运行所在的会话添加标签。别名：`label`。 |
| `beeuni sessions rm <id>...` | 停止并删除一个或多个会话。 |
| `beeuni sessions open <id>` | 在浏览器中打开会话的仪表板页面。 |
| `beeuni sessions stop <id> [--json]` | 暂停会话。沙箱会原地停止，磁盘内容会保留。别名：`pause`。需要 `project.session.stop`。 |
| `beeuni sessions start <id> [--wait] [--json]` | 唤醒会话：配置缺失的沙箱、恢复已停止的沙箱，并解析其运行时。可重复安全执行。别名：`wake`。`--wait` 会阻塞直到就绪（最长约 5 分钟）；如果会话最终处于失败或停止状态，则以 `1` 退出。 |
| `beeuni sessions warm [--exclude <id>] [--json]` | 预先创建即将使用的会话，让沙箱提前启动。会复用已有的未使用预热会话。预热会话在收到第一条提示前不会显示在 `sessions ls` 中。 |
| `beeuni sessions model <id> <model-id> [--json]` | 在会话运行期间更改其模型。活动沙箱会切换到新模型并重启运行时，从而结束当前正在运行的轮次；已停止的会话会保存该值，供下次启动时使用。如果会话未选择新模型提供商的密钥，则会使用你可用于该提供商的所有密钥。 |
| `beeuni sessions compact <id> [--json]` | 总结目前为止的对话，并根据总结继续。运行时未列出 `session.compact` 的会话会以原因 `1` 退出。 |
| `beeuni sessions queue <id> [ls] [--json]` | 列出会话持久收件箱中仍在等待的提示。 |
| `beeuni sessions queue <id> rm <prompt-id>` | 丢弃一个排队的提示。模型步骤开始回答后会拒绝（`409`）。 |
| `beeuni sessions queue <id> now <prompt-id>` | 接下来运行一个排队的提示：将它重新排到顺序规则之前，并解除会话的暂停状态。 |
| `beeuni sessions queue <id> hold\|release` | 暂停所有排队的提示（Stop 按钮执行的操作），或解除暂停。 |
| `beeuni sessions approvals <id> [ls] [--json]` | 列出此会话正在等待人工处理的所有受管控连接器调用。 |
| `beeuni sessions approvals <id> approve\|deny <execution-id>` | 允许一个受管控的连接器调用运行，或拒绝它。智能体会收到通知，并在没有该调用的情况下继续。 |
| `beeuni sessions files <id> <subcommand> [--json]` | 读取和编辑沙盒中的实时工作区：`ls [<path>]`、`status`、`find <query>`、`write <path>`、`touch <path>`、`mkdir <path>`、`mv <from> <to>`、`rm <path>`。 |
| `beeuni sessions share <id> [--mode private\|project\|members] [--member <id\|email>] [--group <id>] [--show] [--json]` | 设置 Beeuni 内哪些人可以打开此会话。不带 `--mode` 时，会显示当前设置且不做任何更改。`--member` 和 `--group` 可重复使用。 |
| `beeuni sessions links <id> ls [--json]` | 按时间倒序列出此会话上创建过的所有公开链接。 |
| `beeuni sessions links <id> create [options]` | 为预览端口或一个工作区文件创建一个公开、无需身份验证的链接。 |
| `beeuni sessions links <id> revoke <share-id>` | 撤销一个公开链接。 |

`sessions queue`需要`project.session.start`，与发送消息所需的权限相同。排队的提示会在终端关闭后继续保留，并在会话可以接收时送达。使用`beeuni sessions chat <id> -p "…" --queue`将提示放入队列，或使用`--steer`引导正在运行的轮次。`sessions queue ls`会显示每个提示的`DELIVERY`（`steer`、`queue`或`interrupt`）；对于作为`queue`运行的引导提示，还会显示原因：`unsupported`（会话无法在轮次进行期间接收消息）、`not_prompter`（另一位成员的轮次正在运行）或`turn_ended`。

`sessions approvals`会持久保留：与`sessions pending`不同，即使沙盒重启也不会丢失。操作需要`project.members.manage`权限，或由启动会话的用户本人执行。智能体绝不能处理自己的审批。

`sessions attachments`读取会话的私有文件存储，而不是工作区。文件会在发送时存入其中，智能体展示的每个文件也会在轮次结束时存入其中。

`sessions files`读取智能体当前正在编辑的工作树，即尚未提交的内容；`beeuni files`则读取已提交的仓库。除非路径以`/workspace`、`/tmp`、`/home`或`/opt`开头，否则会在`/workspace`下解析。若沙盒处于休眠状态，此命令会将其唤醒。选项：`--from <local path>`（`write`会改为读取此文件，而不是标准输入）、`--content`（`find`会使用 ripgrep 搜索内容，而不是文件名）、`--limit <N>`（`find`文件名数量上限），以及`-y`，用于跳过`rm`确认。

`sessions share`由所有者管控：如果项目管理员原本无权读取该会话，API 就会拒绝操作。共享会话只能使用与整个项目共享的提供商密钥运行：使用你自己的密钥运行的模型，会改用该提供商的项目密钥；如果项目没有可用于运行该模型的密钥，共享请求会被拒绝（`409 SHARED_SESSION_NEEDS_PROJECT_KEY`）。

`sessions links create`选项：`--port <n>`（默认`3000`；拒绝`22`、`8000`和 opencode 端口）、`--path <p>`（默认`/`）、`--preview <id>`（指定候选项——`web`、`vite`、`dev-server`、`api-docs`——而非`--port`/`--path`）、`--file <path>`（共享一个工作区文件，而不是预览；始终为只读）、`--mode view\|interactive`（默认`view`；`interactive`允许写入和使用 WebSocket，对`--file`无效）、`--label <text>`和`--expires <iso>`。创建链接需要会话所有者权限，因为链接本身无需登录；列出和撤销链接也允许项目管理员操作。

在沙盒内，`BEEUNI_SESSION_ID`是你自己的会话 ID。

<a id="change-requests"></a>

### 更改请求

更改请求（CR）会在任意 Git 托管平台上将一个分支合并到另一个分支。这是智能体将会话工作合并到默认分支的唯一方式。请参阅[更改请求](/docs/zh/work/change-requests)。

| 命令 | 作用 |
| --- | --- |
| `beeuni cr ls [--status open\|merged\|closed\|all] [--project <id>]` | 列出 CR。默认值：`--status open`。 |
| `beeuni cr show <cr> [--project <id>]` | 显示一个 CR，包括其合并预览。别名：`info`。 |
| `beeuni cr diff <cr> [--no-color] [--json]` | 输出 CR 的统一差异。 |
| `beeuni cr open --title "<text>" [--description "<text>"] [--head <ref>] [--session <id>] [--base <ref>]` | 创建 CR。别名：`new`、`create`。在沙盒内，`--head`和`--session`会自动设为默认值。`--base`默认为项目的默认分支。 |
| `beeuni cr merge <cr> [--message "<text>"]` | 合并一个处于打开状态的 CR。可快进时执行快进合并，否则执行三方合并。 |
| `beeuni cr close <cr>` | 关闭一个处于打开状态的 CR，不进行合并。 |
| `beeuni cr reopen <cr>` | 重新打开一个已关闭的 CR。已合并的 CR 不能再更改状态。 |
| `beeuni cr merge-preview <cr> [--json]` | 报告 CR 是否可以合并，并列出所有冲突路径。别名：`preview`。 |
| `beeuni cr request-changes <cr> --message "<text>"` | 请求创建该 CR 的智能体对其进行修改。别名：`changes`。 |
| `beeuni cr version-diff --from <ver> --into <ver> [--json]` | 在创建 CR 前，对比两个版本并进行总结。 |

`request-changes`会将备注记录在 CR 上，并发送到发起该 CR 的会话；如果其沙盒处于休眠状态，则会启动沙盒。此操作需要`project.review.act`，即 Review Center 使用的相同权限叶节点，而不是`gitops.push`。

`<cr>`接受项目内编号（`3`）或完整 ID。在沙盒内，CLI 会自动读取会话令牌，无需登录或链接。

<a id="review"></a>

### 审核

项目的审核收件箱汇集所有等待人工决策的内容：更改请求、策略要求审批的连接器工具调用，以及智能体提交以供签核的输出、决策和批次。与仪表板中的 Review Center 保持同步。所有项目默认启用；`project.review.read`和`project.review.act`分别控制读取和操作权限。

| 命令 | 作用 |
| --- | --- |
| `beeuni review ls [--segment <s>] [--kind <k>] [--json]` | 列出收件箱项目。默认值：所有类别。 |
| `beeuni review show <item-id> [--json]` | 完整显示一个项目。 |
| `beeuni review act <item-id> <verdict> [--message <text>]` | 处理一个项目。`--message`用于附带备注。 |
| `beeuni review bulk <verdict> <id> [<id> …]` | 在一次调用中处理多个原生项目。 |
| `beeuni review submit --kind <k> --title <t> [options]` | 提交输出、决策或批次以供审核。 |

判定结果：`approve`、`reject`、`changes`、`answer`、`dismiss`。类别：`needs_you`、`waiting`、`done`。类型：`change`、`approval`、`output`、`decision`、`batch`。

判定结果的处理方式取决于项目 ID。对于`cr:<id>`，`approve`会合并更改，`reject`会关闭它，`changes`会将备注发回创建该请求的智能体（需要`--message`）。对于`call:<id>`，`approve`会允许工具调用运行，`reject`会拒绝它；连接器审批不接受其他判定结果——请先使用`beeuni review show`查看其参数。其他所有 ID 都会交由原生操作端点处理，该端点接受所有判定结果。

`bulk`仅处理原生 ID。连接器审批需要单独审核参数，更改请求则需要查看其差异，因此这两类项目会被报告并跳过——这与仪表板的多选规则相同。

`submit`选项：`--kind output\|decision\|batch`（必填）、`--title <text>`（必填）、`--summary <text>`、`--risk none\|low\|medium\|high`（默认`none`）、`--detail <json>`（JSON 对象）、`--agent <name>`和`--session <id>`（当它不属于此项目的会话时会被忽略）。

读取需要`project.review.read`，处理判定需要`project.review.act`，而`submit`需要`project.review.submit`。

<a id="secrets"></a>

### 密钥

存储在项目中的加密值。默认情况下，启动时会将密钥作为普通环境变量注入每个会话沙箱（环境暴露）。强制交付——沙箱持有句柄，由 Beeuni 在沙箱外替换为真实值（出口强制暴露，以及 `beeuni secrets call`）——目前处于实验阶段。启用 `secrets_egress` 功能标志（Settings → Feature flags）即可使用；关闭该标志时，`beeuni secrets delivery … egress` 会返回 `403` `feature_disabled`。参阅 [Secrets](/docs/zh/project/secrets)。

| 命令 | 作用 |
| --- | --- |
| `beeuni secrets ls` | 按标识符和清单 `env` 规范列出密钥，并显示谁可以使用各个值。标记必需但缺失的值。 |
| `beeuni secrets set NAME=VALUE ... [--identifier <id>] [--scope runtime\|connector] [--only-me]` | 新建或更新一个或多个密钥。`NAME=-` 从标准输入读取值。`--scope connector` 在服务端为连接器网关保留该值。`--only-me` 使新值仅对你可用。 |
| `beeuni secrets share IDENTIFIER --user <email\|id\|me> --group <id> --agent <name> \| --everyone` | 设置谁可以使用该值。用户可以直接使用，或在自己的私有会话中使用；智能体则可在其所有会话中使用，包括触发器。参阅 [Who can use a secret](/docs/zh/project/secrets#who-can-use-a-secret)。 |
| `beeuni secrets request NAME ... [--scope runtime\|connector] [--expires <min>]` | 创建链接，让其他人输入你没有的值。 |
| `beeuni secrets unset NAME ...` | 删除密钥。 |
| `beeuni secrets grant IDENTIFIER --agent <name>` | 允许一个智能体接收此密钥：将标识符合并到该智能体在 `beeuni.yaml` 中的 `secrets` 列表；如果清单中没有该智能体条目，则添加它。 |

如果某一行被 `ls` 报告为无法交付，使用 `grant` 修复。它只会扩大一个智能体的列表；要缩小或替换列表，请使用 `beeuni
agents scope`. There is no `secrets revoke` 重写整个集合——API 没有只从授权中删除单个标识符的路由。项目尚无智能体时的首次授权会启动治理：此后，清单中未列出的智能体将无法收到项目密钥，发生这种情况时，命令会予以提示。

### Env

| 命令 | 作用 |
| --- | --- |
| `beeuni env pull [--out <path>] [--force]` | 写入 `.env` 框架，仅包含名称。值绝不会离开云端。 |
| `beeuni env push --from <path>` | 将 dotenv 文件中的所有 `NAME=VALUE` 上传为密钥。 |

### Agents

链接项目中每个智能体的模型设置。

| 命令 | 作用 |
| --- | --- |
| `beeuni agents ls [--json]` | 显示每个智能体固定使用的模型和备用默认模型。别名：`models`。 |
| `beeuni agents model <agent> <provider/model>` | 将智能体固定到某个模型。 |
| `beeuni agents model <agent> --clear` | 清除固定设置——智能体将再次跟随默认模型。 |
| `beeuni agents default <agent>` | 将其设为项目默认智能体。 |
| `beeuni agents default --show [--json]` | 打印当前默认智能体。 |
| `beeuni agents scope <agent> [--secrets all\|none\|A,B] [--connectors all\|none\|a,b] [--apps all\|none\|a,b] [--require-connector <slug>]` | 替换智能体可使用的密钥、连接器和 Beeuni Apps。`--apps` 接受 App slug，且需要 v2 `beeuni.yaml`；智能体还需要 `project.app.read`。`--require-connector` 可重复指定，并且必须在会话开始前解析完成。 |
| `beeuni agents scope <agent> --show [--json]` | 打印智能体当前的作用范围。 |
| `beeuni agents config <agent> [--json]` | 打印完整的智能体配置块。 |
| `beeuni agents config <agent> --file <path>` | 用 JSON 文件的内容替换配置块。`-` 从标准输入读取。 |
| `beeuni agents config <agent> --set <key>=<value> ...` | 更改单个点分隔键，并合并更改。可重复指定，例如 `behavior.model=glm-5.3-flash`、`enabled=false`、`connectors=["slack"]`。 |

每个作用范围选项都会替换现有内容，不会合并。`--set` 值若能解析为 JSON，就按 JSON 解析；否则保留为字符串。模型固定设置和 `scope` 会立即生效，无需 `beeuni.yaml` 提交；`default` 和 `config` 会提交到项目默认分支上的 `beeuni.yaml`。`scope` 需要 `project.agent.write`，`default` 和 `config` 也需要。

### Tools

项目会话可用的工具，从本地 `beeuni.yaml` 及其[导入项](/docs/zh/project/manifest#imports)读取。在项目根目录运行。参阅
[Tools](/docs/zh/project/tools)。

| 命令 | 作用 |
| --- | --- |
| `beeuni tools ls [--json]` | 列出会话可用的每个工具：名称、类型（`beeuni`、`beeuni (overridden)`、`project`）和来源（`beeuni:<name>` 或模块路径）。也会列出项目移除的 Beeuni 工具。`--json` 会打印 `{ manifest, tools_key, tools, removed }`。 |
| `beeuni tools eject <name> [--force]` | 将 Beeuni 工具 `<name>` 复制到 `tools/<name>.ts`，并在声明该工具的 `beeuni.yaml` 中设置 `tools.<name>: tools/<name>.ts`。更改行以 `# ejected from beeuni:<name>` 结尾；其他注释均保留。若没有 `tools:` 键，也会列出其他四个 Beeuni 工具，因此不会移除任何工具。如果 `tools/<name>.ts` 已存在，或该工具已指向其他模块，则拒绝操作，除非指定 `--force`。如果名称不是 Beeuni 工具，也会拒绝操作。 |

没有 `tools:` 键时，每个会话都会获得全部五个 Beeuni 工具（`web_search`、
`image_search`、`scrape_webpage`、`memory`、`show`）。有 `tools:` 键时，
会话只能获得其中列出的 Beeuni 工具。要移除 Beeuni 工具，请删除它在 `tools:` 下的行，然后运行 `beeuni validate`。若要限制单个智能体可用的工具，请使用 `agents.<name>.tools`。退出码：`0` 成功；`1` 操作被拒绝（文件已存在，或清单、导入项无法解析）；`2` 清单不存在、选项未知，或名称不是 Beeuni 工具。

### Models

项目提供哪些模型，以及默认使用哪个模型。与控制面板中的 Customize → Models 页面相同。项目只存储对目录默认值（每个系列的最新模型）的例外设置。启用状态仅影响显示：它决定选择器提供哪些选项，而不会限制网关提供哪些模型。

| 命令 | 作用 |
| --- | --- |
| `beeuni models ls [--json]` | 列出所有可运行的模型：状态、来源、付费方式（`VIA`：Beeuni、API 密钥或 ChatGPT——属于你本人、与你共享或与项目共享）、提供方。 |
| `beeuni models enable <model-id>...` | 提供这些模型。 |
| `beeuni models disable <model-id>...` | 停止提供这些模型。若其中包含项目默认模型，则会以 `409` 拒绝操作——请先更改默认模型。 |
| `beeuni models reset` | 清除所有例外设置，恢复为目录默认值。 |
| `beeuni models default [--json]` | 打印默认链（项目 → 账户 → 平台）及其解析结果。 |
| `beeuni models default <model-id> [--account]` | 设置项目默认值；指定 `--account` 时，设置账户级默认值。 |
| `beeuni models default --clear [--account]` | 清除项目或账户默认值。 |

模型 ID 是网关线路 ID——可以是未加前缀的托管模型 ID（`glm-5.3-flash`），也可以是 BYOK `provider/model`。从 `beeuni models ls --json` 复制。每个智能体的固定设置位于 `beeuni agents model <agent> <model-id>`。写入需要 `project.model.write`。

### Channels

管理项目与聊天平台的连接。令牌会加密存储在项目密钥中，并在服务端解析——绝不会注入沙箱。

| 命令 | 作用 |
| --- | --- |
| `beeuni channels status [--json]` | 显示当前连接。 |
| `beeuni channels connect [--wait] [--timeout <sec>]` | 一步完成连接：打印安装链接。`--wait` 会轮询，直到安装完成。 |
| `beeuni channels connect --manual [--bot-token <token>] [--signing-secret <secret>]` | 使用自带应用模式：直接保存机器人令牌和签名密钥。 |
| `beeuni channels disconnect [--platform slack\|teams]` | 断开项目连接——默认断开 Slack 连接；指定 `--platform teams` 则断开 Teams 连接。 |
| `beeuni channels manifest` | 打印自带应用流程所需的应用清单 JSON。 |
| `beeuni channels email status [--json]` | 设置单个电子邮件连接器的收件箱和投递模式。 |
| `beeuni channels email connect [options]` | 创建托管收件箱，或关联现有的 AgentMail 收件箱。 |
| `beeuni channels email disconnect` | 断开收件箱连接。 |
| `beeuni channels email policy [--allow <email\|@domain>] [--allow-regex <re>] [--allow-all]` | 替换允许给智能体发送电子邮件的人。 |
| `beeuni channels bindings [ls] [--json]` | 列出所有已绑定的渠道，以及其对应的智能体、模型和加入策略。 |
| `beeuni channels bind <bindingId> [--agent <name>\|--no-agent] [--model <id>\|--no-model] [--policy <p>]` | 更改单个绑定。`--policy` 接受 `owner_approval`、`owner_only` 或 `project_open`。 |

`--platform slack|teams` 选择平台；默认值为 `slack`。Teams
`connect` 输出 Microsoft 管理员同意 URL；授予整个租户的同意后，
应用会自动发布到 Teams 目录。请参阅 [Connectors](/docs/zh/connect/connectors)。

电子邮件渠道由 AgentMail 提供支持，需要启用 `agentmail_email` 功能
标志。`email connect` 选项：`--connector <slug>`（默认值 `beeuni_email`）、
`--api-key <k>`（使用你自己的 AgentMail 密钥；`-` 从 stdin 读取）、
`--display-name <n>`（外发邮件的发件人名称；默认为项目名称）、
`--username <u>` 和 `--domain <d>`（新建托管收件箱），以及
`--inbox-id <id>` 和 `--email <addr>`（关联现有收件箱——两者必须同时提供）。
`--allow` 可重复使用，并会启用受限模式；不带 `@` 的裸值，或以 `@` 开头的值，均会被视为域名。
`--allow-all` 会清空列表，重新接受所有发件人的邮件。

电子邮件和 `bind` 写入操作需要 `project.connector.write`。

### Connectors

供智能体作为工具调用的连接器。`add`、`rm` 和 `policy set` 会编辑本地 `beeuni.yaml`；运行 `beeuni ship` 以应用更改，除非传入 `--apply`，立即更改云项目。

| 命令 | 作用 |
| --- | --- |
| `beeuni connectors ls [--json]` | 列出连接器及其状态。 |
| `beeuni connectors show <slug> [--json]` | 显示某个连接器的工具。 |
| `beeuni connectors add <slug> --provider <p> [options] [--apply]` | 添加连接器。 |
| `beeuni connectors rm <slug> [--apply]` | 移除连接器。 |
| `beeuni connectors rename <slug> <name>` | 设置连接器的显示名称。 |
| `beeuni connectors sync` | 根据随附的 `beeuni.yaml` 同步目录。 |
| `beeuni connectors credential <slug> [value]` | 设置连接器的凭据。 |
| `beeuni connectors connect <slug>` | 启动一键连接流程。 |
| `beeuni connectors link <slug> [--expires <min>]` | 为用户创建可分享的连接链接。 |
| `beeuni connectors types [--connector <a,b>] [--out <file>]` | 为每个可调用操作编写 TypeScript 类型：一个 `declare module '@beeuni/sdk'` 文件，为 `connectors.callAction(slug, action, args)` 参数和 `output` 提供类型。托管连接器不会发布输出架构，因此其结果类型为 `unknown`。若不指定 `--out`，则输出到 stdout。 |
| `beeuni connectors accounts <slug> [--default <label\|id>] [--json]` | 列出调用可使用的账户，以及各账户所连接的身份。`--default` 可固定一个账户。 |
| `beeuni connectors connections ls [--all] [--json]` | 列出连接及其标签、`CONNECTED AS`、所有者、`WHO CAN USE`（`owner only`、`everyone` 或授权标签；若仅为管理而列出，则包含 `(not you)`）、状态和默认设置。 |
| `beeuni connectors connections rename <id> <label…>` | 重命名连接。仅更改标签，不会重新授权。 |
| `beeuni connectors connections share <id> [--group <id>]… [--user <email\|id>]… [--everyone]` | 分享你自己的私人账户：该账户会变为仅对指定用户可用的共享账户（`--everyone`：整个项目）。需要拥有管理项目连接的权限。 |
| `beeuni connectors apps [<query>] [--category <c>] [--cursor <c>] [--limit <n>] [--json]` | 搜索 托管工具包目录——`add --provider composio --app <slug>` 接受的 slug。别名：`beeuni connectors toolkits`。添加 `--pipedream` 可搜索旧版目录。 |
| `beeuni connectors catalog [<query>] [--cursor <c>] [--json]` | 浏览直接连接器目录。需要启用 `connectors_api_discover` 标志。 |
| `beeuni connectors catalog show <id> [--json]` | 显示某条目录记录的接口。 |
| `beeuni connectors sensitive <slug> on\|off` | 同时限制此连接器的读取操作——此后每次调用都需要审批。立即生效。 |
| `beeuni connectors owner <slug> project\|user` | 授权方式：使用一个项目连接，或由每位成员使用自己的连接。立即生效。 |
| `beeuni connectors authorize <slug> [--status] [--scope "<a b>"] [--client-id <id>] [--client-secret <s>] [--success-redirect <url>] [--error-redirect <url>] [--json]` | 对连接器执行完整的 OAuth 2.1 授权流程：发现服务器的授权元数据，在服务器支持时将 Beeuni 注册为客户端（RFC 7591），并输出审批 URL。使用 `--status` 可改为报告结果。 |
| `beeuni connectors authorize <slug> --device` | 同上，但使用 OAuth 2.0 设备流程（RFC 8628）：输出代码和 URL，然后轮询，直到获批、被拒或过期。 |
| `beeuni connectors policy ls [--json]` | 显示项目范围的执行策略。别名：`show`。 |
| `beeuni connectors policy set --default <risk\|allow_all> [--apply]` | 在 `beeuni.yaml` 中设置默认执行模式。`--apply` 可直接设置并立即生效。 |
| `beeuni connectors policy add <match> <allow\|ask\|block> [--condition <k=v>]` | 添加项目范围的规则。立即生效。`--condition` 可将规则限定为匹配的参数，且可重复使用；`k!=v` 表示取反，`k` 是指向调用参数的点分路径。 |
| `beeuni connectors policy rm <match>` | 移除项目范围的规则。立即生效。 |
| `beeuni connectors policy <slug> ls\|set <match> <allow\|ask\|block>\|rm <match>\|clear` | 管理某个连接器的工具调用规则。 |

`policy ls`、`show`、`set`、`add` 和 `rm` 属于项目范围的命令，因此，若连接器名称与其中一个动词相同，必须使用 `policy <slug> ls` 指定该连接器。`<match>` 可以是工具名称、通配模式（`send_*`）或 `/regex/`。

`add` 选项：`--name <label>`、`--provider <pipedream\|mcp\|openapi\|postman\|graphql\|http>`、`--app <slug>`、`--url <url>`、`--transport <http\|sse>`、`--endpoint <url>`、`--base-url <url>`、`--spec <url\|path>`、`--auth-type <none\|bearer\|basic\|custom>`、`--credential shared`。

### Sandboxes

管理项目的沙盒镜像。模板定义镜像或 Dockerfile 及资源；构建会生成会话启动时使用的快照。

| 命令 | 作用 |
| --- | --- |
| `beeuni sandboxes ls [--json]` | 列出模板和实时提供商状态。 |
| `beeuni sandboxes builds [--json]` | 查看最近的构建日志。 |
| `beeuni sandboxes health [--json]` | 查看主模板的就绪状态。 |
| `beeuni sandboxes add <slug> (--image <i>\|--dockerfile <p>) [options]` | 创建自定义模板并开始构建。 |
| `beeuni sandboxes update <slug> [options]` | 更新模板。 |
| `beeuni sandboxes build <slug>` | 触发重新构建。 |
| `beeuni sandboxes rebuild <slug>` | 强制重新构建：先删除现有快照。 |
| `beeuni sandboxes rm <slug>` | 删除模板。 |
| `beeuni sandboxes fix` | 启动一个以最近一次失败构建日志为种子的会话，用于修复问题。 |
| `beeuni sandboxes provider [--json]` | 显示项目固定的沙盒提供商，以及此主机支持的提供商。 |
| `beeuni sandboxes provider <name> [--timeout <sec>]` | 将所有新会话固定到一个提供商。如果目标需要先构建快照，API 会返回准备任务，命令会跟进执行直至完成。默认 `--timeout`：600s。 |
| `beeuni sandboxes provider --clear` | 取消固定并使用平台默认设置。别名：`--unpin`。 |
| `beeuni sandboxes provider status [--json]` | 显示最新的提供商切换及其历史记录。别名：`transition`。 |

固定提供商需要 `project.settings.write`。

`add`/`update` 选项：`--name <label>`、`--cpu <n>`、`--memory <n>`（GiB）、`--disk <n>`（GiB）。

### Backends

数据库是带有持久卷的 App。通过 Apps 管理和连接。

[Apps](/docs/feature-flags/apps)

### Marketplace

浏览 Beeuni Marketplace，并将项目安装到项目中。

| 命令 | 作用 |
| --- | --- |
| `beeuni marketplace search [query]` | 搜索 Marketplace 项目。 |
| `beeuni marketplace list` | 列出 Marketplace 项目。 |
| `beeuni marketplace show <id-or-name>` | 显示单个 Marketplace 项目。 |
| `beeuni marketplace install <id-or-name>` | 启动 agent 会话以导入项目。 |

选项：`--query <text>`、`--type <type>`、`--source <source>`、`--host <name>`、`--project <id>`、`--json`。

安装由 agent 驱动：它会启动项目会话，克隆项目、读取内容、合并适用的部分，并发起更改请求。没有确定性的安装、更新或移除机制。

<a id="system-skills"></a>

### 系统技能

Beeuni 系统技能是供用户和 agent 参考的平台运维指南，涵盖会话、沙盒、默认运行时、连接器、记忆和频道。此公开页面是入口；经过身份验证的 CLI 会从运行中的主机读取技能。使用 `beeuni system-skills list` 查找可用技能，然后使用 `get` 查阅所需技能。API 会实时提供技能，因此内容与已部署的主机版本一致。不要将本地副本视为最新版本。

| 命令 | 作用 |
| --- | --- |
| `beeuni system-skills list` | 列出 Beeuni 系统技能。默认子命令。 |
| `beeuni system-skills get <name> [--full]` | 打印某项技能当前的 `SKILL.md`。`--full` 会添加该技能引用的文件。 |
| `beeuni system-skills path [name]` | 打印此项目中某项技能的磁盘目录。 |

选项：`--host <name>`、`--json`。

`beeuni skills` 是同一命令的永久别名。先使用 `beeuni login` 登录主机；技能 API 需要身份验证。使用 `--host <name>` 可操作其他主机。公开文档页面无法替代这些实时且针对特定主机的说明。

此列表始终只包含系统技能，不会混入其他技能。可选技能位于 Marketplace：`beeuni marketplace list --type skill`。命令语法请参阅 `beeuni <command> --help`；完整的平台参考请阅读 `beeuni system-skills get beeuni-system --full`。

### Connector

沙盒内 agent 连接所有连接器的接口。每次调用都会在服务器端经过检查、解析和审计；CLI 不会保存任何第三方凭据。身份验证：`BEEUNI_TOKEN`。输出为 JSON。

| 命令 | 作用 |
| --- | --- |
| `beeuni connectors discover "<intent>"` | 根据自然语言意图搜索工具。 |
| `beeuni connectors show <connector>.<action>` | 显示某个操作的输入架构。 |
| `beeuni connectors call <connector>.<action> '<json-args>'` | 运行工具。受管控的调用会立即返回经过身份验证的 `approval_url`。服务器会在用户作出批准或拒绝决定后恢复会话。大型参数请通过 `@file.json` 或 `-`（标准输入）传递。 |
| `beeuni connectors call <connector>.<action> '<json-args>' --reason "<text>"` | 当策略暂停调用时，说明该调用的作用，供人工审批者查看。审批卡片会将其作为 agent 对该调用的说明，显示在参数旁边。 |
| `beeuni connectors call <connector>.<action> @args.json --attach <file>` | 暂存文件，并将其引用追加到操作的附件数组中。网关会将文件内容写入提供方的附件项。可重复使用 `--attach`；使用 `--attach-path <a.b.c>` 指定数组名称。请参阅[附加文件](/docs/zh/connect/connectors#attach-files)。 |
| `beeuni connectors call <connector>.<action> '<json-args>' --out <file>` | 将完整 JSON 结果写入 `<file>`，并仅打印摘要：`saved_to`、`bytes` 和 `shape`（键、数组长度、`pageInfo`）。请参阅[大型结果](/docs/zh/connect/connectors#large-results)。 |
| `beeuni connectors upload <file> --connector <slug>` | 暂存单个文件。打印 `ref`、`{"$beeuni_attachment":"<id>"}`，供你填入调用参数。 |
| `beeuni connectors add <slug> --provider pipedream --app <app>` | 立即添加连接器，然后连接它。 |
| `beeuni connectors rm <slug>` | 从项目中移除连接器。 |
| `beeuni connectors connect <slug> [--owner me\|project] [--label <name>]` | 为用户生成连接链接。`--label` 会为新账户建议名称，例如第二个 Gmail 账户。 |

<a id="files"></a>

### 文件

只读查看项目的 git 仓库。除非 `--ref` 指定其他分支、标签或提交，否则使用默认分支。

| 命令 | 作用 |
| --- | --- |
| `beeuni files ls [<path>]` | 递归列出路径下的文件。列表最多显示 1,000 个文件，并会说明这一点；请使用路径缩小范围，或使用 `files search`。 |
| `beeuni files cat <path>` | 输出文件内容。 |
| `beeuni files search <query> [--content]` | 搜索文件名，或使用 `--content` 搜索文件内容。 |
| `beeuni files history <path>` | 查看一个文件的提交历史。 |
| `beeuni files branches` | 列出分支。 |
| `beeuni files commits [--path <p>]` | 列出 `--ref` 上的提交。 |
| `beeuni files show <sha>` | 显示一次提交及其更改的文件。 |
| `beeuni files diff <sha> [--path <p>]` | 输出一次提交的统一补丁。 |
| `beeuni files compare <from> <into>` | 汇总两个引用之间的差异。 |
| `beeuni files download -o <out.zip>` | 将 `--ref` 时的仓库或 `--path` 子树下载为 zip 文件。别名：`archive`。 |

每个子命令都支持这些选项：`--ref <ref>`、`--path <p>`、`--limit <n>`、`--json`。
`download` 还接受 `-o, --out <file>`，此选项为必填项。

每个子命令都需要 `project.file.read`。此外，`download` 会拒绝任何包含你无权访问的代理或技能的子树——zip 文件无法在流式传输过程中进行筛选——因此在这种情况下，请归档范围更窄的 `--path`。

<a id="triggers"></a>

### 触发器

触发器可根据计划、webhook、应用事件或监视器（实验性）启动会话。`add`、`rm`、`enable`、`disable` 会编辑本地清单——运行 `beeuni ship` 以应用更改。`pause`/`resume` 会切换单独的服务器端开关。请参阅 [Triggers](/docs/zh/connect/triggers)。

| 命令 | 作用 |
| --- | --- |
| `beeuni triggers ls [--json]` | 列出触发器及其运行时状态。 |
| `beeuni triggers add <slug> [options] [--apply]` | 将触发器追加到清单中。`--apply` 会改为立即在云项目中创建触发器：它会在 `main` 上提交到 `beeuni.yaml`，然后进行协调。 |
| `beeuni triggers set <slug> [options]` | 修改正在运行的触发器。只会写入你传入的标志。始终立即应用——没有本地形式。别名：`update`。 |
| `beeuni triggers rm <slug> [--apply]` | 从 `beeuni.yaml` 中移除触发器，或使用 `--apply` 立即从云项目中移除。 |
| `beeuni triggers info <slug> [--json]` | 显示一个触发器。 |
| `beeuni triggers events --connector <slug> [--json]` | 列出连接器提供的事件及每个事件的设置。 |
| `beeuni triggers fire <slug>` | 手动触发触发器并等待运行结果：失败的运行会以非零退出码及错误信息退出；触发运行所创建的新会话会被清理（排入现有会话的运行会保留）。`--wait <dur>` 会限制等待时间（默认为 `90s`；`0` 会在触发请求被接受后立即返回）。 |
| `beeuni triggers enable <slug> [--apply]` / `disable <slug> [--apply]` | 启用或停用一个触发器。 |
| `beeuni triggers pause` / `resume` | 在服务器端停用或重新启用项目中的所有触发器。 |

`add` 选项：`--type <cron\|webhook\|event\|monitor>`（默认为 `cron`）、`--prompt <text>`（必填）、`--agent <name>`、`--cron <expr>`（6 个字段，例如 `"0 0 9 * * 1-5"`）、`--run-at <iso>`（在此时刻运行一次，而不是按 cron 运行）、`--timezone <tz>`（默认为 UTC）、`--secret-env <NAME>`、`--name <label>`、`--disabled`。

仅实时选项——适用于 `add --apply`，以及每个 `set`：`--model <provider/model>`、`--session-mode <fresh\|keyed\|pinned\|reuse>`、`--session-key <tmpl>`（按键为每个会话分桶，例如 `"{{ body.data.chat_jid }}"`；隐含 `keyed`）、`--session-id <id>`（`pinned` 触发器循环使用的会话；必须是此项目的会话）、`--session-access <private\|project\|members>`（默认为 `private`）、`--member <uuid>` 和 `--group <uuid>`（可重复；每个都隐含 `members`），以及 `--filter <path=value>`（可重复；每一个都必须匹配，例如 `--filter body.type=push`）。

`set` 接受所有仅实时选项，以及 `--name`、`--prompt`、`--cron`、`--run-at`、`--timezone`、`--secret-env`、`--agent` 和 `--enabled true|false`。`--cron` 和 `--run-at` 互斥：设置其中一个会清除另一个。监视器字段仅支持添加。

<a id="reminders"></a>

### 提醒

提醒会在之后的一个会话中再次提示一次或按重复计划提示。它存储在数据库中，而不是 `beeuni.yaml` 中。在会话内，`--session` 默认为 `$BEEUNI_SESSION_ID`。请参阅 [Reminders](/docs/zh/connect/reminders)。

| 命令 | 作用 |
| --- | --- |
| `beeuni remind "<text>" [schedule]` | 创建提醒。与 `beeuni reminders add` 相同。 |
| `beeuni reminders add "<text>" [schedule]` | 创建提醒。输出其 ID 和下一次触发时间。 |
| `beeuni reminders ls [--json]` | 列出会话的提醒。 |
| `beeuni reminders pause <id>` / `resume <id>` | 停用或启用一个提醒。`resume` 会从现在起重新启用。 |
| `beeuni reminders rm <id>` | 删除提醒。别名：`stop`、`delete`。 |

计划选项：`--in <duration>` 或 `--at <iso>`（首次触发；单独使用时仅触发一次）、`--every <duration>`（重复，最短间隔为 `5m`）、`--cron "<expr>"` 与 `--timezone <tz>`。其他选项：`--name <label>`、`--session <id>`（可使用唯一前缀）、`--project <id>`、`--host <name>`、`--json`。

事件选项（`--type event`）：`--connector <slug>` 和 `--event <TYPE>`（均为必填）、`--config key=value`（可重复，字符串值），以及 `--config-json '{...}'`（类型化值）。`set` 接受相同的标志。事件触发器拒绝 `--cron`、`--run-at`、`--timezone`、`--secret-env` 以及监视器选项。提示内容读取 `{{ event.data.<field> }}`；请参阅 [App event triggers](/docs/zh/connect/triggers#app-event-triggers)。

监视器选项（`--type monitor`）：`--run <cmd>`（要监视的相对于仓库的命令；必填）、`--mode <poll\|stream>`（必填；`poll` 会在 `--interval` 上重新运行，`stream` 会使命令保持运行）、`--interval <dur>`（仅限 `mode=poll`，最短 30 秒，例如 `60s`、`5m`），以及 `--expect-event-within <dur>`（静默看门狗；在时间窗口内没有事件时改为触发生命周期事件，最短 5 分钟，例如 `24h`）。监视器是平台全天候运行的仓库命令，每一行 stdout 都会触发该触发器。它是实验性功能：平台仅在启用 `monitors` 功能标志的位置运行监视器。

<a id="access"></a>

### 访问权限

唯一授权表的 CLI 界面。每一行都是一项**分配**：一个主体、一个角色、一个范围，可选择进一步限定到一个对象。有关模型，请参阅 [Accounts & access](/docs/zh/accounts#one-access-model)。账户角色：`owner`、`admin`、`member`。项目角色：`manager`、`member`。

| 命令 | 作用 |
| --- | --- |
| `beeuni access assignments [--project <id>\|--account\|--all] [--json]` | 列出一个项目、账户或所有位置的分配。 |
| `beeuni access grant --user <id\|email>\|--group <id>\|--service-account <id> --role <key\|id> [opts]` | 创建一项分配。输出分配 ID。 |
| `beeuni access revoke <assignment-id>` | 撤销一项分配。 |

授权选项：`--project <id>`（默认为关联项目）、`--account`（整个账户）、`--agent <name>`（将授权限定到一个代理——对象分配）、`--connection <id>`（限定一个共享连接器账户的使用范围；第一项授权会将该账户限制为其被授权者，撤销最后一项授权后则再次对整个项目开放）、`--everyone`（授予所有有权访问项目的人员；它包含一个 `--agent` 或 `--connection`，而不是角色），以及 `--expires <iso>`（自动撤销时间戳）。`--principal` 会筛选列表，并接受 `user:<id>`、`group:<id>`、`service_account:<id>`、`project:<id>` 或 `pending:<email>`；单独的 ID 会被视为用户。授予所有人的授权会列为 `everyone`。代理的身份是一个 `service_account`，因此 `--service-account <id>` 是向代理分配角色的方式。`--user` 接受电子邮件地址，并在账户成员目录中解析该地址。

```bash
beeuni access grant --user alice@corp.com --role manager
beeuni access grant --user alice@corp.com --role admin --account
beeuni access grant --group 8f3c… --role member --project 1a2b…
beeuni access grant --user alice@corp.com --agent support-bot
beeuni access grant --everyone --agent support-bot
beeuni access grant --group 8f3c… --connection 2b7e…
beeuni access revoke 4d5e…
```

项目成员动词是对相同分配的读取模型：

| 命令 | 作用 |
| --- | --- |
| `beeuni access ls [--json]` | 列出可访问项目的人员、其账户角色和有效项目角色。 |
| `beeuni access invite <email> --role <r>` | 邀请某人加入项目。创建一个 `pending` 分配。 |
| `beeuni access grant <user-id> --role <r>` | 设置用户的项目角色。 |
| `beeuni access revoke <user-id>` | 移除用户对项目的访问权限。 |
| `beeuni access pending [--json]` | 列出待处理的邀请。 |
| `beeuni access resend <invite-id>` | 重新发送邀请邮件并重置其 14 天有效期。也会打印链接。 |
| `beeuni access cancel <invite-id>` | 取消待处理的邀请。 |
| `beeuni access requests ls [--json]` | 列出请求加入此项目的待处理申请。 |
| `beeuni access requests approve <req-id> [--role <r>]` | 批准一项申请并授予项目角色。默认角色：`member`。 |
| `beeuni access requests reject <req-id>` | 拒绝一项申请。别名：`deny`。 |

以上两个表格中的每个动词都需要 `project.members.manage`。

人员、群组或代理会从 Beeuni 获得角色；代理还会在 `beeuni.yaml` 中携带 Beeuni 权限，而会话只能执行两者都允许的操作。参见[一种词汇，两种绑定](/docs/zh/accounts#one-vocabulary-two-bindings)。

<a id="audit"></a>

### 审计

审计命令读取集中式重建日志。账户和项目列表按时间倒序排列。会话时间线按创建时间排序（`session_sequence` 仅在 2026-10 之前写入的行上设置，这些行排在最前）。`--all` 会跟随每个续传游标。`ls` 列出最近 90 天的记录；`export` 可追溯 365 天，超过 90 天的事件来自归档（参见[审计保留期](/docs/zh/accounts#retention)）。表格在每行标题（例如 `EVENT`「已撤销 LLM 网关密钥」）旁显示其 `ACTION`（`gateway.key.revoke`）；`--action` 按操作前缀筛选。所有操作和标题见：[审计日志操作](/docs/zh/audit-actions)。

| 命令 | 作用 |
| --- | --- |
| `beeuni audit ls [filters] [--all] [--json]` | 列出账户事件。 |
| `beeuni audit project <project-id> [filters] [--all] [--json]` | 列出一个项目的事件。 |
| `beeuni audit session <session-id> --project <project-id> [--all] [--json]` | 按顺序重建一个会话。 |
| `beeuni audit export [filters] --format csv\|jsonl --out <file>` | 将导出的所有分页续传到一个文件。 |
| `beeuni audit webhooks ls [--json]` | 列出账户的审计 Webhook。 |
| `beeuni audit webhooks add --name <n> --url <u> [--action-prefix <p>]` | 创建一个 Webhook。签名密钥仅显示一次，并立即触发一次测试投递。`--action-prefix` 仅投递具有该前缀的操作。 |
| `beeuni audit webhooks enable <webhook-id>` | 恢复投递。 |
| `beeuni audit webhooks disable <webhook-id>` | 暂停投递，但保留端点。 |
| `beeuni audit webhooks rm <webhook-id>` | 永久删除 Webhook。 |

审计 Webhook 会将记录流式传输到 SIEM。每个动词都需要 `account.write`；`add` 和 `enable` 还需要企业版权益。`disable` 和 `rm` 则始终不需要。

筛选条件：`--actor`、`--actor-type`、`--project`、`--session`、`--source`、`--phase`、`--outcome`、`--action`、`--resource-type`、`--request-id`、`--correlation-id`、`--query`、`--since`、`--until`、`--cursor` 和 `--limit`。
账户列表和导出需要 `audit.read` 以及账户的 `auditAccess` 权益。项目范围的列表需要 `project.members.manage`，因为其中可能包含私有会话元数据。重建会话需要 `project.session.read`，且必须能查看该会话。

<a id="roles"></a>

### 角色

角色是具名的权限集合。系统角色（账户范围的 `owner`、`admin`、`member`；项目范围的 `manager`、`member`；以及对象分配携带的标记 `agent-user`）均为只读引用。自定义角色可由你创建和编辑，并且需要企业版 `rbac` 权益。

| 命令 | 作用 |
| --- | --- |
| `beeuni roles ls [--json]` | 列出系统角色和自定义角色。 |
| `beeuni roles show <role> [--json]` | 显示一个角色的权限和使用情况。 |
| `beeuni roles permissions <role> [--json]` | 列出一个角色的权限。 |
| `beeuni roles create <key> --name <n> [options]` | 创建自定义角色。 |
| `beeuni roles edit <role> [--name <n>] [--desc <t>\|--no-desc]` | 重命名或重新描述自定义角色。其键不会改变。需要 `role.update`，且不能用于系统角色。 |
| `beeuni roles set-actions <role> --actions a,b` | 替换自定义角色的权限。 |
| `beeuni roles rm <role>` | 删除自定义角色。 |
| `beeuni roles export [--project <id>] [--out <file>] [--format toml\|json]` | 将角色和分配导出到文件。 |
| `beeuni roles import <file>` | 应用角色和分配文件。 |

使用 `beeuni access grant` 将角色绑定到主体。旧版的 `beeuni roles
assign` / `unassign` / `assignments` 动词仍可使用，并写入同一张表，但 `beeuni access` 是文档所述的操作方式。`beeuni roles actions` 已由 `beeuni permissions ls` 取代。

自定义角色只能添加权限。Beeuni 没有拒绝规则，因此角色无法阻止管理员拥有某项权限。

<a id="permissions"></a>

### 权限

权限目录以数据形式呈现。每个叶级操作占一行，列出其判定范围、是否可委派以及会隐含哪些权限。角色由这些键构成——`beeuni roles create --actions` 和 `beeuni roles set-actions` 使用的正是这些键。别名：`beeuni perms`。

| 命令 | 作用 |
| --- | --- |
| `beeuni permissions ls [--scope account\|project] [--area <a>] [--json]` | 列出权限目录。 |
| `beeuni permissions show <action> [--json]` | 完整显示一项操作。 |

<a id="grants"></a>

### 授权

将一个项目对象分配给主体，即创建一个**对象分配**。密钥和连接器属于代理，因此将代理分配给某人会授予该代理声明的所有内容。代理默认是封闭的：只有在分配中指定某个成员或其所属群组时，该成员才能访问代理。`beeuni access grant --agent
<name>` 会写入同一行记录。

| 命令 | 作用 |
| --- | --- |
| `beeuni grants ls [--json]` | 列出对象分配，以及可分配的代理。 |
| `beeuni grants assign <agent-name> --to <who> [--group]` | 将代理分配给用户，或使用 `--group` 分配给群组。 |
| `beeuni grants revoke <grant-id>` | 撤销一个对象分配。 |

<a id="manifest-validation"></a>

### 清单验证

| 命令 | 作用 |
| --- | --- |
| `beeuni validate [--file <path>] [--json] [--scopes] [--no-dockerfile-lint]` | 根据规范架构验证清单，检查每个沙盒 Dockerfile 和代理配置，并检查仓库大小。先解析 `beeuni.yaml`，再解析 `beeuni.toml`。退出代码：`0` 表示有效（可能存在警告），`1` 表示有错误，`2` 表示文件缺失。`beeuni ship` 执行相同的检查。 |
| `beeuni schema [--version 1\|2] [--url]` | 打印清单的 JSON Schema。`--url` 则打印架构 URL。 |

参见[清单参考](/docs/zh/project/manifest)。

<a id="repository-size"></a>

#### 仓库大小

会话会根据基础提交中 Git 跟踪的所有文件构建其[代理配置](/docs/zh/work/runtime#where-a-box-gets-the-release)。新会话会从自己的检出中获取这些文件，不受大小限制。运行中的会话通过项目快照获取基础分支的更改；Beeuni 云构建的快照压缩后最多为 512 MiB。超过此限制时，会话会继续使用当前运行的配置，直到启动新会话。每个会话也会下载所有文件。`beeuni validate` 会统计 Git 存储的文件以及下次由 `beeuni ship` 提交的未跟踪文件；当单个文件达到或超过 10 MiB，或总大小超过 512 MiB 时，会打印警告。Git LFS 文件按其指针计数，因为发布内容仅包含指针。警告会列出最大的文件。此项检查绝不会导致命令失败。

要消除警告：
- 将大型静态资源（视频、图像、数据集、模型权重）移至 S3、R2 或 GCS 等对象存储，或移至 CDN，并在运行时下载。
- 将构建输出（`dist/`、`out/`）添加到 `.gitignore`。
- 对于必须保留在 Git 中但没有代理会读取的路径，将 `<path> export-ignore` 添加到 `.gitattributes`。发布内容和检查都会忽略该路径；目录规则会涵盖其下的所有内容。代理配置目录和 `beeuni.yaml` 始终会完整发布。

<a id="token-scope"></a>

### 令牌范围

每个令牌都以 `beeuni_pat_` 开头。用户令牌的作用域涵盖你账户中的所有项目。项目令牌的作用域仅限于一个项目，并会自动注入该项目的沙箱中。请参阅完整的令牌系列参考：[Session runtime](/docs/zh/work/runtime)。

<a id="exit-codes"></a>

### 退出代码

| 代码 | 含义 |
| --- | --- |
| `0` | 成功。 |
| `1` | 操作失败。诊断信息会输出到 stderr。 |
| `2` | 标志无效、子命令未知或缺少必需参数。 |