CLI Reference

Search, inspect and run paid API endpoints with one Key — the same three calls as the API, from the terminal.

Install

Requires Node.js 22 or newer; npm is optional. Re-run either command to upgrade.

bash

curl -fsSL https://glasser.ai/install.sh | sh
# or, with npm:
npm install -g @glasser-ai/cli

Authentication

glasser login opens the console, you approve with one click when the match code on the page equals the one in the terminal, and a Workspace-scoped Key lands in the local store. For CI and scripts, mint a Key in the console and set GLASSER_API_KEY or use glasser keys add.

bash

glasser login

Commands

bash

glasser login [--no-browser]

Log in through the browser and store a Key. The terminal prints an 8-character match code and opens the console's authorize page; approve only when the code on the page matches the terminal. The CLI then prints which Workspace it logged into.

--no-browserPrint the URL instead of opening a browser

bash

glasser search [-q <query>] [--limit N]

Search runnable endpoints. Omit the query to list the catalog.

--query, -qKeyword query; omit to list the catalog

--limitMaximum items to return (1-100)

bash

glasser inspect -p <provider> -e <endpoint>

Inspect one endpoint: the provider-native input schema, the price with every charge clause, and the current version. Read this before you run anything.

--provider, -pProvider slug (e.g. pdl)

--endpoint, -eEndpoint key (e.g. /v5/person/enrich)

--endpoint-versionPin the endpoint version you inspected (409 if it is no longer current)

bash

glasser run -p <provider> -e <endpoint> [-i '<json>' | -f <file>]

Run an endpoint and pay for that one call. The idempotency key is generated and shown when omitted — retry an ambiguous failure with the same key and you get the original Run back instead of a second charge.

--provider, -pProvider slug (e.g. pdl)

--endpoint, -eEndpoint key (e.g. /v5/person/enrich)

--input, -iProvider-native input: inline JSON or @path/to/file.json

--input-file, -fRead input from a JSON file (alternative to -i @file)

--endpoint-versionPin the endpoint version you inspected (409 if it is no longer current)

--idempotency-keyReuse a key to retry safely; generated (and shown) when omitted

--wait, -wPoll until the Run is terminal

--wait-timeoutSeconds to wait before giving up (default 300; requires --wait)

--output, -oWrite the Run's output field to a file (COMPLETED with output only)

bash

glasser runs list

List runs, newest first.

--limitMaximum items to return (1-100)

--cursorPagination cursor from a previous response

--statusFilter by status: QUEUED, RUNNING, COMPLETED, FAILED, STOPPED

--provider, -pFilter by provider

--endpoint, -eFilter by endpoint

bash

glasser runs get -r <runId>

Get run status and output.

--run-id, -rThe Run id

--wait, -wPoll until the Run is terminal

--wait-timeoutSeconds to wait before giving up (default 300; requires --wait)

--output, -oWrite the Run's output field to a file (COMPLETED with output only)

bash

glasser runs stop -r <runId>

Stop a run — dispatch wins the race: a Run already sent to the provider completes and is charged.

--run-id, -rThe Run id

bash

glasser balance

Balance, held and available. Exit 0 means the Key works — this doubles as the auth probe.

bash

glasser balance history

List every balance movement, newest first. Amounts are exact decimal strings.

--limitMaximum items to return (1-100)

--cursorPagination cursor from a previous response

--kindFilter by kind: charge, refund, topup, grant, adjustment

bash

glasser keys add -l <label> -k <key>

Store a Key locally.

--label, -lUnique label for the Key

--key, -kThe Key to store

bash

glasser keys list

List stored Keys, masked.

bash

glasser keys activate -l <label>

Switch the active Key.

--label, -lUnique label for the Key

bash

glasser keys remove -l <label>

Remove a Key from this machine. This does not revoke it — revoke in the console.

--label, -lUnique label for the Key

--forceSkip the confirmation prompt

Global flags on every command: -j/--json, --help, --version.

JSON mode

With -j/--json, stdout carries raw JSON data only and stderr carries errors as a single JSON object — pipe stdout, parse stderr. run --json requires an explicit --idempotency-key (a generated-and-lost key would make retries unsafe), and login --json is a usage error — the login flow is interactive. Money is always an exact decimal string, never a float.

Exit codes

0Success

1Runtime failure — the API refused, the Run failed, the network broke

2Usage error — bad flags or bad input; the command never reached the API

130Interrupted (Ctrl-C)

Environment variables

GLASSER_API_KEYA Key for this invocation; overrides the local key store

GLASSER_API_BASE_URLAPI origin (default https://api.glasser.ai)

NO_COLORDisable colored output

For agents

The agent-facing Skill at glasser.ai/SKILL.md packages this CLI — when to use it, how to authenticate through glasser login, and the rules that keep spending deliberate. Point your agent at that file.