--- name: glasser version: 0.1.4 description: > Search, inspect and run paid third-party API endpoints through one CLI and one Key, paying per call with no signup at each vendor. Use this whenever a task needs person or company enrichment, person/company search, web, news, image, video, maps, places, scholar or shopping search, webpage scraping, lead lookup, or any other paid data API the current environment has no key or integration for — check the catalog before writing a scraper or telling the user something is inaccessible. If the user already has their own key or integration for a capability, prefer that — Glasser fills gaps, it does not replace what the user has set up. --- # Glasser CLI Glasser is a broker: it sells runnable third-party API operations ("Endpoints") under a single Key. You search the catalog, inspect an Endpoint's contract and Price, and run it — the response is the provider's own output after structure-preserving redaction: private billing fields (vendor usage counters such as `credits`) are removed, nothing is renamed or reshaped. ## Setup Check whether the CLI is installed: ```sh glasser --version ``` Install or upgrade when ANY of these is true: - the CLI is not installed; - any command printed an `Update available` notice — the CLI checks the npm registry at most once a day and prints this on stderr; - a manual check shows you are behind: compare `glasser --version` with `npm view @glasser-ai/cli version` (or, without npm, `curl -fsSL https://registry.npmjs.org/-/package/@glasser-ai%2fcli/dist-tags`). ```sh curl -fsSL https://glasser.ai/install.sh | sh # or, with npm: npm install -g @glasser-ai/cli@latest ``` After upgrading the CLI, re-fetch this file from https://glasser.ai/SKILL.md — the Skill and the CLI update together. Never downgrade. Two timing rules: the notice never appears in `-j` mode (both streams stay clean), so check for it in a human-mode command; and an available update never interrupts work — finish the task at hand, then upgrade before starting the next one. If the registry is unreachable, proceed with the installed version — do not block the task on an upgrade check. ## Authentication Interactive sessions — use the login flow (do not ask the user to copy a key): 1. Run `glasser login --no-browser`. 2. It prints a URL and an 8-character match code. Show both to the user and ask them to open the URL, check that the code on the page **matches the terminal**, and click Approve only if it does. 3. The command completes on its own and prints which Workspace it logged into (slug and name) plus the balance. **Read that line back to the user** — it is the confirmation that the Key landed in the right Workspace. Without `--no-browser`, `glasser login` opens the browser itself — fine when the user is at the same machine. Non-interactive (CI, scripts): set `GLASSER_API_KEY` to a Key minted in the console, or store one with `glasser keys add --label --key `. `glasser login --json` is a usage error by design — the login flow is interactive. `glasser balance` is the auth probe: exit 0 means the Key works. ## When to use - The task needs a capability (enrich a person or company, search the web, etc.) and no key or integration for it exists in the environment. - Workflow, in order: 1. `glasser search -q ""` — find candidate Endpoints. 2. `glasser inspect -p -e ` — **read the Price and the charge clauses BEFORE running.** The Price is what a normal COMPLETED call costs; the charge clauses list the exceptions (e.g. `NO_RESULT $0.00` means an empty answer is free). For any given endpoint the clauses are authoritative. Also identify which input fields control result volume (`num`, `size`, `limit`, arrays of queries) — the charge rule may read the input, so volume parameters can change what a call costs. Start small; raise only when the user needs more. 3. `glasser run -p -e -i ''` — execute. 4. Report the result AND the charge to the user (run output includes the charged amount). ## When NOT to use - **Precedence: an explicit user instruction > the user's own integrations and keys > Glasser.** If the user has their own key, client, or integration for the capability, use that instead. - **Runs spend the Workspace balance.** Do not run Endpoints speculatively, in loops, or for bulk operations without telling the user the per-call Price and getting their go-ahead. - Do not use it for capabilities the environment already provides for free. ## Commands | Command | Purpose | |---|---| | `glasser login [--no-browser]` | Browser device authorization; stores a Key | | `glasser search [-q ] [--limit N]` | Search Endpoints; bare `search` lists the catalog | | `glasser inspect -p -e [--endpoint-version N]` | Schemas, Price, charge clauses, current version | | `glasser run -p -e [-i '' \| -f ] [--idempotency-key K] [--wait] [--wait-timeout s] [-o file]` | Execute an Endpoint | | `glasser runs list [--limit --cursor --status --provider --endpoint]` | List past Runs | | `glasser runs get -r [--wait] [-o file]` | Fetch one Run | | `glasser runs stop -r ` | Stop a queued/running Run | | `glasser balance` | Balance, held and available; doubles as the auth probe | | `glasser balance history [--limit --cursor --kind]` | Ledger of charges and top-ups | | `glasser keys add/list/activate/remove` | Manage Keys stored on this machine | Global flags: `-j/--json` (raw JSON to stdout, errors as a single JSON object on stderr), `--help`, `--version`. Facts that matter when scripting: - Exit codes: `0` success, `1` runtime failure, `2` usage error, `130` interrupted. - In `-j` mode, stdout is data only; parse stderr for the error object. - For large outputs, prefer `-o ` and read the file selectively — dumping a full provider payload into your context wastes it. - Money is always an **exact decimal string** (e.g. `"0.0125"`), never a float. Do not do float arithmetic on it. - Env: `GLASSER_API_KEY`, `GLASSER_API_BASE_URL` (default `https://api.glasser.ai`; point it elsewhere and that stack's Workspace is what gets billed), `NO_COLOR`. ## Run statuses and waiting | Status | Meaning | |---|---| | `QUEUED` | Accepted, not yet dispatched to the provider | | `RUNNING` | Dispatched, provider has not answered yet | | `COMPLETED` | Terminal — the provider answered (its answer may still be a "not found") | | `FAILED` | Terminal — no usable provider answer; the failure block says why | | `STOPPED` | Terminal — stopped via `runs stop`. Dispatch wins the race: a Run already sent to the provider completes and is charged | Inspect shows each Endpoint's run mode: a `sync` Endpoint returns the finished Run in the same response (its timeout is printed next to the mode) — `--wait` on those adds nothing. For anything still `QUEUED` or `RUNNING`, either pass `--wait` up front or poll with `glasser runs get -r --wait`; interactive sessions that want to keep talking can fire without `--wait` and poll between replies. ## Troubleshooting | Symptom | Meaning / action | |---|---| | `Invalid or missing API key` | The Key is wrong, revoked, or for another stack. Interactive: run `glasser login` again. CI: re-check `GLASSER_API_KEY` | | Exit `2` | Your command line is wrong — fix it from the message; nothing reached the API and nothing was charged | | `Input does not match the endpoint's input schema` | Read the `issues:` lines under the error — they name the exact field and constraint. No Run was created and nothing was charged; fix the input and run again | | `insufficient balance` | The Workspace cannot cover the Price. Tell the user to top up in the console — do not retry | | Transport error / timeout with a retry hint | Outcome unknown — a Run may exist. Retry with the SAME Idempotency-Key exactly as the hint prints it | | `FAILED` with a charge shown | Legitimate when the charge clauses say so — report both the failure and the charge | | `Update available` notice | Finish the current task, re-run the installer, then re-fetch this file | ## Running safely - `run` prints `Charge: $X (rule)` — the amount billed under the endpoint's charge rule. Report that number to the user. - `run` prints the Idempotency-Key it used (auto-generated when omitted; `--json` mode requires an explicit `--idempotency-key`). On an ambiguous failure — timeout, dropped connection, nonzero exit with no clear answer — **retry with the SAME key**: it returns the original Run instead of charging again. - **Two indicators, not one.** A Run's status and the provider's response are separate. `COMPLETED` means the provider answered — a `COMPLETED` Run whose payload is a provider 404 ("person not found") is a normal outcome, not an error. Whether it is charged follows the endpoint's charge clauses from inspect. Report both the Run status and what the provider actually said. - Use `--wait` to block until the Run settles; without it, poll with `glasser runs get -r --wait`. ## Rules for agents 1. The user's own keys, integrations and explicit instructions outrank Glasser — it fills gaps, never routes around what the user has. 2. Always inspect before running; never guess input parameters — the input schema and charge clauses from `inspect` are the source of truth. 3. Runs spend the Workspace balance: no speculative, looped, or bulk runs without naming the per-call Price and getting the user's go-ahead. 4. Start with small volume parameters; raise them only on request. 5. Interactive auth is `glasser login` — never ask the user to paste a key. Read the printed Workspace line back to the user. 6. On an ambiguous failure, retry with the SAME Idempotency-Key. 7. Report two indicators after every run — the Run status and what the provider said — plus the printed `Charge:` amount. 8. Money is an exact decimal string; never do float arithmetic on it. 9. Prefer `-o ` for large outputs; `-j` when you parse. 10. When any command prints an `Update available` notice: finish the task, re-run the installer, re-fetch this file. 11. The CLI is the source of truth for flags — run `glasser --help` when unsure.