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

# CLI 参考

> 在终端中使用 Glasser：安装、登录，并查找所需命令。

使用一个 API Key，在终端中搜索、检查和运行付费 API 接口，操作流程与 HTTP API 相同。

## 安装

需要 Node.js 22 或更高版本；npm 为可选。再次运行任一安装命令即可升级。

```bash theme={null}
curl -fsSL https://glasser.ai/install.sh | sh
# or, with npm:
npm install -g @glasser-ai/cli
```

## 身份认证

运行以下命令，通过浏览器登录，并保存工作空间的 API Key：

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

确认浏览器中的验证码与终端一致后，再批准授权。登录选项见 [glasser login](https://glasser.ai/docs/zh/cli/login.md)。

在 CI 和脚本中使用时，在控制台创建 API Key 并设置 `GLASSER_API_KEY`，或使用 [glasser keys add](https://glasser.ai/docs/zh/cli/keys/add.md)。

## 命令

在侧栏选择命令，或打开下方参考页。每个命令页都列出了语法和选项。

| 命令 | 说明 |
| - | - |
| [`glasser login`](https://glasser.ai/docs/zh/cli/login) | 通过浏览器登录并保存 API Key。 |
| [`glasser search`](https://glasser.ai/docs/zh/cli/search) | 搜索可运行的接口，或浏览数据源。 |
| [`glasser inspect`](https://glasser.ai/docs/zh/cli/inspect) | 运行前检查接口。 |
| [`glasser run`](https://glasser.ai/docs/zh/cli/run) | 运行接口并获取输出。 |
| [`glasser runs list`](https://glasser.ai/docs/zh/cli/runs/list) | 列出 Run 并筛选结果。 |
| [`glasser runs get`](https://glasser.ai/docs/zh/cli/runs/get) | 获取 Run、等待完成，或保存输出。 |
| [`glasser runs stop`](https://glasser.ai/docs/zh/cli/runs/stop) | 请求停止 Run。 |
| [`glasser balance`](https://glasser.ai/docs/zh/cli/balance) | 查看余额并验证 API Key。 |
| [`glasser balance history`](https://glasser.ai/docs/zh/cli/balance/history) | 列出余额变动。 |
| [`glasser keys add`](https://glasser.ai/docs/zh/cli/keys/add) | 在本机保存 API Key。 |
| [`glasser keys list`](https://glasser.ai/docs/zh/cli/keys/list) | 列出已保存的 API Key。 |
| [`glasser keys activate`](https://glasser.ai/docs/zh/cli/keys/activate) | 切换当前使用的 API Key。 |
| [`glasser keys remove`](https://glasser.ai/docs/zh/cli/keys/remove) | 从本机移除 API Key。 |
| [`glasser skill install`](https://glasser.ai/docs/zh/cli/skill/install) | 保存 Skill，供后续 Agent 会话加载。 |

## 将相关调用归入同一个 Task

搜索会返回 `task_id`。在相关搜索中通过 `--task` 传入该值，包括更换关键词重试、读取下一页，以及后续的 `inspect` 和 `run`。CLI 不会自动保存或复用 Task。即使传入了 `--task`，每次搜索仍必须提供 `--use-case`。

```bash theme={null}
glasser search "company enrichment" --use-case "Prepare a company profile"
```

将下方的 `<taskId>` 替换为响应中的 `task_id`。数据提供商、接口和输入应以搜索及检查结果为准。

```bash theme={null}
glasser inspect -p <provider> -e <endpoint> --task <taskId>
glasser run -p <provider> -e <endpoint> -i '<json>' --task <taskId>
glasser runs list --task <taskId>
```

搜索时省略 `--task`，每次都会创建新 Task。在 `inspect` 和 `run` 中，省略该参数表示调用不归属任何 Task。在 `runs list` 中，`--task` 用于筛选指定 Task 的结果。

## 全局选项

所有命令均支持：`-j/--json`、`--help`、`--version`。

## JSON 模式

使用 `-j/--json` 时，stdout 中的命令结果为 JSON。成功时 stderr 为空，失败时包含一个 JSON 错误对象。显式使用 `--help` 和 `--version` 时，仍输出文本。

* `run --json` 必须提供 `--idempotency-key`，以便使用同一个键重试。
* `keys remove --json` 必须提供 `--force`，以跳过交互式确认。
* `login --json` 会返回用法错误，因为登录需要交互。
* `--output` 只保存 Run 的 output 字段。写入成功后，stdout 包含完整 Run。文件写入失败时，stdout 为空，stderr 输出 `io_error` JSON 对象，并以 `1` 退出。JSON 模式不会向 stderr 打印文件状态提示。

对于 `run` 和 `runs get`，`FAILED` 或 `STOPPED` 状态的 Run 仍会输出到 stdout；同时，命令向 stderr 写入 JSON 错误，并以退出码 `1` 结束。 Glasser 响应中的金额均为精确的十进制字符串，不使用浮点数。

## 退出码

| 退出码 | 含义 |
| - | - |
| `0` | 成功 |
| `1` | API、网络或本地 I/O 失败；等待超时；或 `run` / `runs get` 返回了 `FAILED` 或 `STOPPED` 状态的 Run |
| `2` | 用法错误：选项或输入无效，请求尚未到达 API |
| `130` | 已中断，通常由 Ctrl-C 触发 |

对于 `run` 和 `runs get`，未使用 `--wait` 时，退出码 `0` 也可能表示 Run 仍处于 `QUEUED` 或 `RUNNING` 状态。即使数据提供商返回 HTTP 4xx 或 5xx，`COMPLETED` 状态的 Run 也以 `0` 退出；请检查 `provider_response.http_status`。 Run 状态与 `charge_usd` 必须分别检查。

`runs stop` 在停止请求被接受后以 `0` 退出，即使 Run 仍在运行。完整行为见[停止 Run](https://glasser.ai/docs/zh/cli/runs/stop.md)。

## 环境变量

| 变量 | 含义 |
| - | - |
| `GLASSER_API_KEY` | 本次调用使用的 API Key，优先于本地保存的 Key |
| `GLASSER_API_BASE_URL` | API 服务地址，默认为 [https://api.glasser.ai](https://api.glasser.ai) |
| `NO_COLOR` | 禁用 CLI 框架生成的帮助和版本文本中的颜色 |

## 供 Agent 使用

面向 Agent 的 [glasser.ai/SKILL.md](https://glasser.ai/SKILL.md) 包含本 CLI 的使用说明：适用场景、通过 `glasser login` 认证的方法，以及付费操作的确认规则。将该文件提供给你的 Agent 即可。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.