@glasser-ai/cli

中文文档
0.1.135发布于 2026/11/13MITES Module零依赖近 30 天下载 4249

Search, inspect and run paid API endpoints with one Key — the Glasser CLI

原始使用文档
文档目录8 节
  1. Install
  2. Commands
  3. Login
  4. Keys
  5. Run semantics
  6. Streams and exit codes
  7. Design notes
  8. Development

glasser CLI

Search, inspect and run paid API endpoints with one Key — the first-party client for the Glasser data plane (/v1).

Install

curl -fsSL https://glasser.ai/install.sh | sh    # no npm needed (Node >= 22)
# or, with npm:
npm install -g @glasser-ai/cli

Re-run either command to upgrade. Then: glasser login.

Commands

glasser search  ["<query>"] --use-case "<ask>" [--limit N] [--cursor C]  # no query lists the catalog; --use-case is always required
                 # -q/--query takes the same value; --query=<q> for a leading dash
glasser inspect -p <provider> -e <endpoint> [--endpoint-version N]
glasser run     -p <provider> -e <endpoint> [-i '<json>'|@file | -f <path>]
                 [--endpoint-version N] [--idempotency-key K]
                 [--wait] [--wait-timeout s] [-o file]
glasser runs list [--limit --cursor --status --provider --endpoint]
glasser runs get  -r <runId> [--wait] [--wait-timeout s] [-o file]
glasser runs stop -r <runId>
glasser balance
glasser balance history [--limit --cursor --kind]
glasser keys add --label <l> --key <k> | list | activate --label <l>
             | remove --label <l> [--force]
glasser skill install [--target <agent>]

Global: -j/--json, --help, --version.

Login

glasser login [--no-browser] — the browser flow: the terminal prints a match code, the console's /cli/authorize page opens, one click approves, and the Key lands in the local store (labelled after the workspace slug, activated). Approve only when the code on the page matches the terminal; the CLI then prints WHICH workspace it logged into — read that line. Denied or expired approvals exit 1 with a re-run hint. login --json is a usage error: the non-interactive path is minting a Key in the console plus glasser keys add.

Keys

Precedence: GLASSER_API_KEY (validated; a malformed value is an error, it never falls back silently) > the active stored Key > an error pointing at glasser keys add.

The local store is $XDG_CONFIG_HOME/glasser/keys.json (default ~/.config, file mode 0600). Labels are unique; the first Key auto-activates; removing the active Key deactivates it; keys remove only touches this machine — it does not revoke the Key. Only masked tokens (gl_1bba****) are ever printed.

Run semantics

  • status is the Run lifecycle; Response: HTTP n is the provider's verdict. COMPLETED + HTTP 404 is a normal outcome (charged by the NO_RESULT clause), not an error.
  • The Idempotency-Key is printed to stderr before dispatch. After an ambiguous failure (transport error, timeout, service_unavailable — the API may have admitted a Run before answering 503) retry with the SAME key: a replay is a read and is never charged twice. The error message carries the exact retry command.
  • --wait polls (0.5s → ×2 → cap 10s) until terminal; --wait-timeout (default 300s) requires --wait. Sync endpoints answer terminally in one round trip and never poll.
  • -o <file> writes the Run's output field only for a COMPLETED Run with non-null output. Human mode prints the Run summary without repeating the saved body; --json keeps the full Run on stdout. Failures and Provider errors remain visible.
  • Money fields are exact USD decimal strings, printed verbatim. Sum them with decimal arithmetic, never floats.

Streams and exit codes

Human mode: data on stdout; progress, hints, prompts and errors on stderr. JSON mode (--json): stdout carries only the raw success body; every error — usage errors included — is a single JSON object on stderr shaped like the API envelope ({"error":{"code",...},"request_id"?}). keys remove --json requires --force so a prompt can never corrupt machine output.

CodeMeaning
0Success. A COMPLETED Run (any provider status); a successful runs stop.
1API error, transport failure, --wait timeout, or run/runs get ending FAILED / STOPPED.
2Usage: bad flags or input JSON, invalid env values, no Key configured.
130Interrupted.

Design notes

  • search matches POST /v1/endpoints/search — the CLI verb is the API verb.
  • --wait and --wait-timeout <seconds> are separate flags.
  • -f/--input-file <path> exists alongside -i (mutually exclusive).
  • Every run carries an Idempotency-Key — retrying with the same key is a read, never a second charge.

Development

pnpm --filter @glasser-ai/cli dev -- search -q "web search" --use-case "find a web search API"   # tsx, no build
pnpm --filter @glasser-ai/cli build                            # esbuild → dist/glasser.js
node apps/cli/dist/glasser.js --help
cd apps/cli && pnpm link --global                  # a PATH `glasser` shim

pnpm --filter @glasser-ai/cli test:p0                          # unit
GLASSER_API_KEY=gl_… pnpm --filter @glasser-ai/cli test:integration   # needs seeded :3101

Env: GLASSER_API_BASE_URL (default https://api.glasser.ai), GLASSER_API_KEY, XDG_CONFIG_HOME, NO_COLOR (colour in framework-rendered help and version text).

版本与发布记录

@glasser-ai/cli 共发布 67 个版本,首次发布于 2026/09/01;过去 12 个月发布了 67 个版本。

版本发布日期距今
0.1.135latest2026/11/133 天前
0.1.1342026/11/115 天前
0.1.1332026/11/115 天前
0.1.1312026/11/106 天前
0.1.1302026/11/106 天前
0.1.1282026/11/106 天前

关于 @glasser-ai/cli 的常见问题

@glasser-ai/cli 是什么?

Search, inspect and run paid API endpoints with one Key — the Glasser CLI

如何安装 @glasser-ai/cli?

在项目目录运行 npm install @glasser-ai/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 glasser,可以用 npx glasser 直接运行。

@glasser-ai/cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/glasser-ai__cli 是否存在。

@glasser-ai/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@glasser-ai/cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@glasser-ai/cli 可以商用吗?

@glasser-ai/cli 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@glasser-ai/cli 的下载量有多少?

根据 npm 官方下载统计,@glasser-ai/cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,249 次,日均约 142 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@glasser-ai/cli 还在维护吗?

最新版本 0.1.135 发布于 2026/11/13(3 天前);至今共发布 67 个版本,其中过去 12 个月发布了 67 个;首次发布于 2026/09/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。