# CLI 参考

rungent 的每个命令和参数，即 rungent 中的命令。它从哪里找宿主和令牌、编写类命令、rungent serve、它保存的文件和退出码。

`rungent` 是每个 rungent 宿主的命令行；也是检查目录、生成宿主的文档、密钥和品牌 CLI 的工具；还是给其他语言的宿主用的服务器。它需要 Node 22 或更高版本（`serve` 需要 24）。

```bash
npm install -g rungent
rungent login https://console.example.com      # 粘贴令牌
rungent vm stop gpu-train-01                   # 宿主提供的一个命令
```

```text
Usage: rungent [--host <url>] [--yes] <command> [args]
```

输出是 stdout 上的 JSON：在终端里带缩进，否则为单行。消息和提示写到 stderr。CLI 是做什么用的，见[入口](surfaces.md#a-cli-with-your-name)。

## 全局参数

它们写在命令之前。

| 参数 | 含义 |
|---|---|
| `--host <url>` | 宿主。一个 `http` 或 `https` URL；末尾的斜杠会被去掉。 |
| `--yes`, `-y` | 不询问，直接确认写操作。 |
| `--help`, `-h` | 打印用法；写在命令之后时，打印该命令的帮助。 |

## 宿主与令牌

| 变量 | 含义 |
|---|---|
| `RUNGENT_HOST` | 没有 `--host` 时使用的宿主。 |
| `RUNGENT_TOKEN` | 令牌。设置了 `RUNGENT_HOST` 时，它只发给那个宿主。它从不被保存或打印。 |

宿主依次取 `--host`、`RUNGENT_HOST`、`rungent login` 为这个程序最后保存的宿主、品牌 CLI 的预设宿主。令牌依次取 `RUNGENT_TOKEN`、`login` 为该宿主保存的令牌。品牌 CLI 默认读取 `<NAME>_HOST` 和 `<NAME>_TOKEN`（见 [`brand`](#brand)）。在 CI 里，设置这些变量、跳过 `login` 即可，不会往磁盘写任何东西。

## 宿主命令

宿主命令用 `Authorization: Bearer <token>` 连接 `<host>/mcp`。内置命令有 `login`、`logout`、`status`、`tools` 和 `search`。宿主提供的命令首个单词与其中之一相同时，以宿主的命令为准；`rungent:<name>` 总是运行内置命令（`rungent rungent:login`）。

| 命令 | 作用 |
|---|---|
| `login [host-url] [--token-stdin]` | 不回显地询问令牌（或从 stdin 读取），通过列出工具来验证它，为该宿主保存令牌，并把该宿主设为这个程序的默认宿主。从不读取 `RUNGENT_TOKEN`。 |
| `logout [host-url]` | 忘掉该宿主的令牌和缓存的工具列表。 |
| `status` | 宿主、所用的凭据（`login` 或变量名）、MCP 服务的名称和版本，以及工具数量。 |
| `tools [--json]` | 宿主向你提供的每个命令，及其用法和简介。 |
| `search <query>` | 搜索产品：宿主在其搜索操作和文档上的搜索。 |

### 宿主提供的命令

```bash
rungent <command words> [positional args] [--flags]
rungent <command words> --help
```

`rungent` 列出宿主的 MCP 工具，把每个工具拼写成其 `_meta.rungent` 中的单词，这些单词来自 [`x-rungent.cli`](x-rungent.md#every-key)。没有这些单词的工具成为一个命令，即把名字中的 `_` 换成 `-`。有多个命令匹配时，最长的那个胜出。

| 输入 | 写法 |
|---|---|
| 位置参数 | 工具的 `args`，按顺序。 |
| 其他输入 | `--page-size 20` 或 `--page-size=20`；名字中的 `_` 变成 `-`。 |
| 布尔值 | `--forced`、`--no-forced`、`--forced=true`。 |
| 数组 | 重复参数：`--tag a --tag b`。 |
| 对象 | 一个 JSON 对象：`--labels '{"team":"ml"}'`。 |
| 整个输入 | `--input-json <file\|->`：来自文件或 stdin 的 JSON 对象。参数会覆盖其中的键。 |
| 参数结束 | `--`：其后的一切都是位置参数。 |

缺少必填输入时，什么都不发送，直接以退出码 2 失败。写操作会在终端上请求确认；`--yes` 表示接受，没有终端时除非给了 `--yes`，否则一律拒绝。结果是工具的结构化内容，没有则把其文本按 JSON 解析；工具错误以 `error: …` 写到 stderr，退出码 1。

## 编写类命令

它们作用于一份 OpenAPI 文档，从不连接宿主。`--openapi` 接收 JSON 文件或 `http(s)` URL；`-o`（`--out`）写入文件而不是 stdout。

### `check`

```bash
rungent check --openapi <file|url> [--routes routes.txt]
```

以 `<where>: <message>` 打印目录的每个问题，有问题时退出码为 1；否则在 stderr 打印 `ok: N operations`。规则见 [x-rungent](x-rungent.md#validation-rules)。`--routes` 列出你的 UI 发出的请求，每行一个 `METHOD /path`，没有操作提供的路由都算失败；只有浏览器需要的路由用 `# browser-only: <reason>` 标注。

### `skill`, `llms`, `reference`, `docs`

```bash
rungent skill --openapi <file|url> --product <name> --url <url> [--guide guide.md] [--cli-command acme] [-o SKILL.md]
rungent llms --openapi <file|url> --product <name> --url <url> --summary <text> [-o llms.txt]
rungent reference --openapi <file|url> [-o reference.md]
rungent docs --openapi <file|url> --product <name> --url <url> --summary <text> [--guide f] [--cli-command c] -o <dir>
```

`skill` 生成 rungent 在 `/skill.md` 提供的 Agent skill：frontmatter、你的使用指南、连接方法、安全规则和操作索引。`llms` 生成 `llms.txt`；`reference` 生成涵盖每个操作的 Markdown 参考；`docs` 把这三样都写进一个目录。

### `keys generate`

```bash
rungent keys generate --kid rungent-2026-11 [-o rungent-2026-11.private.jwk]
```

在 stdout 打印公钥 JWK，由你的 API 固定；把私钥 JWK，即 rungent 的签名密钥，写入一个权限为 0600 的新文件（默认 `<kid>.private.jwk`）。它从不覆盖已有文件，也从不打印私钥。两者都是可移植的 Ed25519 JWK，Node、Bun、Deno 和 workerd 都能同样导入。

### `brand`

```bash
rungent brand --name acme [--host https://console.example.com] [--env-host VAR] [--env-token VAR] -o acme-cli [--npm-name @acme/cli]
```

生成一个 npm 包（`package.json`、`bin/acme.js`、`README.md`），其 bin `acme` 以这个名字运行本 CLI。

| 参数 | 含义 |
|---|---|
| `--name` | 必填：命令名，由小写字母、数字和 `-` 组成。 |
| `-o`, `--out` | 必填：包所在的目录。 |
| `--host <url>` | 预设宿主。客户自行部署的产品不要设。 |
| `--env-host`, `--env-token` | 它读取的变量。默认 `<NAME>_HOST` 和 `<NAME>_TOKEN`，即名字转大写、`-` 换成 `_`。 |
| `--npm-name` | 包名。默认 `<name>-cli`。 |

要把 CLI 嵌进你自己的程序，调用 `rungent/cli` 中的 `run(argv, {program?, host?, env?})`；它返回退出码。`brand` 生成的正是这个。

## `serve`

```bash
rungent serve
```

把 rungent 作为 HTTP 服务运行在宿主旁边，由 `RUNGENT_*` 环境变量配置，直到收到 `SIGTERM` 或 `SIGINT`。变量缺失或无效时以退出码 2 退出，并给出变量名。全部变量见[部署](deploy.md#configure-it)。

## 文件

| 路径 | 内容 |
|---|---|
| `~/.config/rungent/hosts.json` | `login` 按宿主保存的令牌，以及每个程序的默认宿主。文件权限 0600，所在目录 0700。 |
| `~/.cache/rungent/tools/<hash>.json` | 工具列表，按宿主和令牌各缓存五分钟。 |

`XDG_CONFIG_HOME` 和 `XDG_CACHE_HOME` 可以改变这些目录。品牌 CLI 共用它们，但有自己的默认宿主。

## 退出码

| 退出码 | 含义 |
|---|---|
| `0` | 成功。 |
| `1` | 工具错误、JSON-RPC 错误，或 `check` 发现了问题。 |
| `2` | 用法错误：未知的命令或参数，值缺失或无效。 |
| `3` | 认证：没有宿主、未登录，或宿主返回 401 或 403。 |
| `4` | 网络：无法连接宿主，或宿主返回了其他 HTTP 错误。 |
