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

# 命令行工具

> 安装 orriven CLI，用控制台账号登录，在终端里管理 API 密钥、Webhook、请求日志与指标。

**orriven CLI** 是控制台「开发工具」抽屉的终端形态。它以**你本人**的身份登录——而不是用 API 密钥——因此能做的正是所有者（Owner）或管理员（Admin）在抽屉里能做的事：生成与吊销密钥、登记 Webhook 端点、查看请求日志与指标。macOS、Linux、Windows 各一个单文件。

<Info>
  CLI 管理的是业务单元的**开发者面**。它不创建活动、票种或报名——那是[开放 API](/zh/developers/overview) 的职责，用 CLI 签发的密钥调用。
</Info>

## 安装

<Tabs>
  <Tab title="Homebrew（macOS / Linux）">
    ```bash theme={null}
    brew install orriven/tap/orriven
    ```
  </Tab>

  <Tab title="apt（Debian / Ubuntu）">
    ```bash theme={null}
    curl -fsSL https://orriven.github.io/apt/orriven.gpg | sudo tee /usr/share/keyrings/orriven.gpg >/dev/null
    echo "deb [signed-by=/usr/share/keyrings/orriven.gpg] https://orriven.github.io/apt stable main" | sudo tee /etc/apt/sources.list.d/orriven.list
    sudo apt-get update && sudo apt-get install orriven
    ```
  </Tab>

  <Tab title="Windows（scoop）">
    ```powershell theme={null}
    scoop bucket add orriven https://github.com/orriven/scoop-bucket
    scoop install orriven
    ```

    或从 [GitHub Releases](https://github.com/orriven/cli/releases) 下载对应架构的 `.zip`，把 `orriven.exe` 放到 `PATH` 中。
  </Tab>

  <Tab title="脚本 / 二进制">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/orriven/cli/main/install.sh | sh
    ```

    也可从 [GitHub Releases](https://github.com/orriven/cli/releases) 下载压缩包、`.deb`、`.rpm` 或 `.apk`。每个版本附带 `checksums.txt`。
  </Tab>
</Tabs>

运行 `orriven --version` 确认安装成功。

## 登录

```bash theme={null}
orriven login
```

终端会显示一个一次性授权码并打开控制台。**核对页面上的授权码与终端中的一致**后，选择「批准」。终端即以你的账号登录，权限与你的角色相同。终端里不会输入密码，因此通过[企业 SSO](/zh/organization/members-roles) 登录的账号也用同样方式登录。

* 会话有效期与控制台会话相同，并显示在你的账号页面中，可在那里吊销。
* `orriven logout` 吊销会话并删除本机上的凭证。
* `orriven whoami` 显示当前账号以及当前目录解析到的业务单元。

<Warning>
  只批准与**你自己**终端中一致的授权码。批准别人发来的授权码，等于让对方的终端以你的身份登录。
</Warning>

## 将项目指向一个业务单元

```bash theme={null}
cd your-project
orriven init
```

`init` 会在需要时先登录，然后询问组织与业务单元，并在当前目录写入 `orriven.toml`。在该目录——以及其任意子目录——运行的每条命令都作用于该业务单元。

```toml theme={null}
organization = "…"
workspace = "…"
```

这个文件**只记录范围**，从不包含凭证，可以安全提交到代码仓库。凭证保存在你的用户目录中。要改指别处，运行 `orriven init --force`，或在单条命令上用 `--workspace <id>`（与 `--org <id>`）覆盖。

每个交互提示都有非交互的等价方式。`orriven orgs list` 与 `orriven workspaces list --org <组织>` 打印候选项，两个答案都给出时不会有任何提问：

```bash theme={null}
orriven init --org acme --workspace "Field Marketing"     # id、slug 或名称均可
```

加 `--non-interactive`（设置了 `CI` 环境变量或不在终端中时自动生效）后，CLI 从不提问；缺少信息时报用法错误。

## API 密钥

| 命令                                                        | 作用                                                            |
| --------------------------------------------------------- | ------------------------------------------------------------- |
| `orriven keys list`                                       | 有效密钥。`--all` 包含已吊销的。                                          |
| `orriven keys create <名称>`                                | 生成 Secret 密钥。Secret **仅显示一次**，请立即保存。`--expires-in 30d` 设置有效期。 |
| `orriven keys create-publishable <名称> --origin https://…` | 生成绑定到指定 Origin 的 Publishable 公开密钥（`--origin` 可重复）。            |
| `orriven keys set-origins <密钥> --origin https://…`        | 替换公开密钥允许的 Origin。                                             |
| `orriven keys revoke <密钥>`                                | 立即吊销。会要求确认；`--yes` 跳过确认。                                      |

密钥参数接受 `list` 中的行 ID 或公开的 Key ID（`ok_…` / `opk_…`）。[API 密钥](/zh/developers/api-keys)页面的规则在此同样适用：Secret 只出现一次，一把密钥只服务一个业务单元，每个操作都进入审计日志。

## Webhook

| 命令                                                                    | 作用                                 |
| --------------------------------------------------------------------- | ---------------------------------- |
| `orriven webhooks events`                                             | 端点可订阅的事件类型。                        |
| `orriven webhooks create <url> --event registration.confirmed`        | 登记端点并打印签名密钥。`--all-events` 订阅全部事件。 |
| `orriven webhooks list`、`orriven webhooks get <id>`                   | 端点列表；单个端点及其签名密钥。                   |
| `orriven webhooks update <id> --url … --event … --enable / --disable` | 修改端点。                              |
| `orriven webhooks ping <id>`                                          | 通过真实的签名投递管道发送一条测试事件。               |
| `orriven webhooks deliveries <id>`                                    | 投递记录，最新在前。`--status failed` 过滤。    |
| `orriven webhooks resend <投递 id>`                                     | 重新发送一条投递。                          |

端点地址必须是 `https`（`localhost` 允许 `http`）。停用只是停止投递，不会删除任何记录。

## 请求日志与指标

```bash theme={null}
orriven logs                      # 用本业务单元密钥发起的最新请求
orriven logs --status 5xx --path /v1/orders
orriven logs --follow             # 持续跟随
orriven logs --since 1h           # 只看最近一小时
orriven logs get <id>             # 单条请求，含采集到的请求/响应主体
orriven logs get --latest --status 5xx   # 最近一次失败的完整详情，无需先查 id
orriven metrics --days 7          # 请求量、错误率、耗时；1、7 或 30 天
```

## 脚本化

* 任何命令加 `--json` 都原样输出 API 的应答，字段含义见 [API 参考](/zh/developers/api-reference)。
* 在 CI 中用 `ORRIVEN_TOKEN`、`ORRIVEN_ORGANIZATION`、`ORRIVEN_WORKSPACE`、`ORRIVEN_API_URL` 替代登录与项目文件。`ORRIVEN_TOKEN` 应放在密钥管理中，不要写进 shell 配置文件。
* 非终端环境下或加 `--non-interactive` 时命令从不弹出交互：`revoke` 需要 `--yes`，`init` 需要 `--org` 与 `--workspace`。
* 命令组接受单数别名：`org`、`workspace`（`ws`）、`key`、`webhook`、`log`。
* 退出码：`1` 一般错误，`2` 用法错误，`3` 需要登录，`4` 未指定业务单元。

## 相关

* [Agent](/zh/agent/overview) —— 面向 AI 代理集成的 Model Context Protocol (MCP) 服务
* [API 密钥](/zh/developers/api-keys)
* [开放 API 概览](/zh/developers/overview)
* [Storefront API](/zh/developers/storefront)