> ## 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 Reference

> Use Glasser from your terminal. Install, sign in, and find the command you need.

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 theme={null}
curl -fsSL https://glasser.ai/install.sh | sh
# or, with npm:
npm install -g @glasser-ai/cli
```

## Authentication

Run this command to open browser sign-in and store a Key for your Workspace:

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

Approve only when the code in the browser matches the terminal. See
[glasser login](/docs/cli/login) for the login options.

For CI and scripts, create a Key in the console and set `GLASSER_API_KEY`,
or use [glasser keys add](/docs/cli/keys/add).

## Commands

Choose a command in the sidebar or open its reference below. Each command page lists its syntax and options.

| Command | Description |
| - | - |
| <span id="glasser-login" />[`glasser login`](/docs/cli/login) | Log in through the browser and store a Key. |
| <span id="glasser-search" />[`glasser search`](/docs/cli/search) | Search runnable Endpoints or browse Data Sources. |
| <span id="glasser-inspect" />[`glasser inspect`](/docs/cli/inspect) | Inspect an Endpoint before you run it. |
| <span id="glasser-run" />[`glasser run`](/docs/cli/run) | Run an Endpoint and retrieve its output. |
| <span id="glasser-runs-list" />[`glasser runs list`](/docs/cli/runs/list) | List Runs and filter the results. |
| <span id="glasser-runs-get" />[`glasser runs get`](/docs/cli/runs/get) | Get a Run, wait for completion, or save its output. |
| <span id="glasser-runs-stop" />[`glasser runs stop`](/docs/cli/runs/stop) | Request a stop for a Run. |
| <span id="glasser-balance" />[`glasser balance`](/docs/cli/balance) | Check your balance and verify your Key. |
| <span id="glasser-balance-history" />[`glasser balance history`](/docs/cli/balance/history) | List balance movements. |
| <span id="glasser-keys-add" />[`glasser keys add`](/docs/cli/keys/add) | Store a Key on this machine. |
| <span id="glasser-keys-list" />[`glasser keys list`](/docs/cli/keys/list) | List stored Keys. |
| <span id="glasser-keys-activate" />[`glasser keys activate`](/docs/cli/keys/activate) | Switch the active Key. |
| <span id="glasser-keys-remove" />[`glasser keys remove`](/docs/cli/keys/remove) | Remove a Key from this machine. |
| <span id="glasser-skill-install" />[`glasser skill install`](/docs/cli/skill/install) | Save the Skill so new agent sessions load it. |

## Keep calls in one Task

A search returns a `task_id`. Pass that value with `--task` on related searches,
including retries with different words and requests for the next page, and on
`inspect` and `run`. The CLI does not store or reuse the Task automatically.
Every search still requires `--use-case`, even when you pass `--task`.

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

Replace `<taskId>` below with the `task_id` from that response. Use the Provider,
Endpoint, and input selected through search and inspection.

```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>
```

Omitting `--task` starts a new Task on each search. On `inspect` and `run`,
omitting it leaves the call without a Task. On `runs list`, `--task` filters
the results to that Task.

## Global flags

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

## JSON mode

With `-j/--json`, command results on stdout are JSON. Stderr is empty on
success and contains one JSON error object on failure. Explicit `--help` and
`--version` requests still produce text.

* `run --json` requires `--idempotency-key` so you can retry with the same key.
* `keys remove --json` requires `--force` to skip interactive confirmation.
* `login --json` is a usage error because login is interactive.
* `--output` saves only the Run's output field. On a successful write, stdout
  contains the full Run. A file write failure leaves stdout empty, writes an
  `io_error` JSON object to stderr, and exits `1`. JSON mode does not print
  file status messages to stderr.

For `run` and `runs get`, a `FAILED` or `STOPPED` Run is still returned on
stdout. The command also writes a JSON error to stderr and exits with code `1`.
Money amounts in Glasser response fields are exact decimal strings, never floats.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | API, network, or local I/O failure; wait timeout; or `run` / `runs get` returned a `FAILED` or `STOPPED` Run |
| `2` | Usage error — bad flags or bad input; the command never reached the API |
| `130` | Interrupted (Ctrl-C) |

For `run` and `runs get`, exit `0` can mean that the Run is still `QUEUED` or
`RUNNING` when you do not use `--wait`. A `COMPLETED` Run also exits `0` when
the Provider returned HTTP 4xx or 5xx; check `provider_response.http_status`.
The Run's status and `charge_usd` are separate results.

`runs stop` exits `0` when the stop request is accepted, even if the Run is
still running. See [stopping a Run](/docs/cli/runs/stop) for the full behavior.

## Environment variables

| Variable | Meaning |
| - | - |
| `GLASSER_API_KEY` | A Key for this invocation; overrides the local key store |
| `GLASSER_API_BASE_URL` | API origin (default [https://api.glasser.ai](https://api.glasser.ai)) |
| `NO_COLOR` | Disable colour in the help and version text the CLI framework renders |

## For agents

The agent-facing Skill at [glasser.ai/SKILL.md](https://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.


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