glassray is the single command-line surface for the product: cloud setup + account
operations, and the local Coach loop. Install-free via npx @glassray/cli, or
globally:
npm i -g @glassray/cli # Node ≥ 20.6
npm i -g @glassray/cli@latest # upgrade — the CLI's ▲ notice tells you when
glassray login, the CLI is purely local — no cloud code loads and nothing is
uploaded. Cloud commands activate only after you pair.
Set up (cloud)
| Command | What it does |
|---|---|
glassray setup | The launcher: sign in (org picker on multi-org accounts — choose or create) → pick or create the project this setup is for → hand off to the browser onboarding wizard scoped to it (GitHub · traces · Slack) → mirror its status back → wire the SDK locally (only if you chose the SDK or skipped traces) → confirm a trace lands. Browser-only for first-time onboarding; re-runs skip the wizard if it’s already done. --org <name|id> picks an org non-interactively; --skip-instrument provisions the key without editing code. It shows your ingest key and asks before writing it to your env file. See Set up. |
glassray login | Sign this machine in to your org (opens the browser). Multi-org accounts get a picker — choose one or create a new org; --org <name|id> picks non-interactively; --api-key skips the browser (CI). |
glassray logout | Clear the stored credential for the current endpoint. |
glassray whoami | Show which org and user the current key resolves to. |
glassray detect | Look at the repo — package manager, framework, existing tracing, provider env keys — and print the recommended way to get traces flowing. --json for machines. |
glassray connect <target> | Open the dashboard page to connect a target in the browser (advanced/one-off — setup runs the full guided flow). Six targets: otlp / langsmith / langfuse / posthog land on the sources page (pick the provider there), slack opens notifications, github opens integrations. --no-open prints the URL instead of launching. |
glassray instrument | Add the tracing SDK and the four convention tags to your code. By default it shows the prompt (copied to your clipboard) so you can run it in any coding agent, and — when Claude Code is installed — offers to run it for you. When it runs Claude Code the run is headless — it applies the change and exits back to your terminal, streaming its progress — and can never git commit/git push (hard-blocked), so the change always lands uncommitted for you to review. --run runs Claude Code without asking; --prompt-only always just prints. |
glassray verify | The exit gate: watch until a real, tagged trace has landed. --wait with a timeout; names the likely cause on failure. |
glassray status | Account overview: sources with health, trace counts, GitHub/Slack state. --json. |
Local Coach
glassray start runs the local server; the data verbs talk to it on 127.0.0.1:5899 and
print API JSON verbatim (never decorated).
| Command | What it does |
|---|---|
glassray start | Run the local Coach server + dashboard. Installs @glassray/coach on demand the first time. --port (default 5899). |
glassray traces | list · get <id> · tail. |
glassray flows | list · get · create · update · delete · audit · discover. |
glassray evals | list · get · create · update · delete · run. |
glassray deviations | list · get <id> · discover · resolve <id>. |
glassray deviations discover | Cluster recurring failures across recent traces (--sample · --flow). Canonical; discovery run is a kept alias. |
glassray experiments | list [--flow <id>] · get <id> — read-only inspect of A/B experiments. |
glassray fix <deviationId> | Generate a fix doc for your coding agent. |
glassray runs · stats · usage | Background runs · store rollups · LLM spend. |
Loop verbs
The repo-side harness that drivesglassray.yaml — your flows, run recipes, and code root as code.
| Command | What it does |
|---|---|
glassray pull | Round-trip glassray.yaml; --as-fixtures / --traces <flow> freeze corpora and inputs. |
glassray push | Reconcile the file into the store — terraform-style plan/apply (--dry-run, --prune). |
glassray run <flow> --label <name> | Execute the flow’s run recipe; traces land tagged with that run label. |
glassray compare <baseline> <candidate> | A/B two corpora over the rule suite (tokens: a run label, or label: / agent: / flow: / fixtures:). |
glassray check | The CI gate: run every rule, exit non-zero if any pass-rate is below its threshold. |
glassray link <project> | Record a cloud project ref (--show prints it) so local work can be pushed up. |
Manage
| Command | What it does |
|---|---|
glassray init | Install the agent skill into ./.claude/skills/ (Claude Code) and ./.agents/skills/ (the open Agent Skills standard). --force overwrites a modified copy. |
glassray mcp add / mcp remove | Register (or remove) the cloud MCP server in .mcp.json (and report which AI clients — Claude Code, Cursor — are present in the repo). The bearer is written as ${GLASSRAY_TOKEN} (env expansion) — never a literal key. |
glassray token | Print the stored org key raw on stdout (the gh auth token pattern) — export GLASSRAY_TOKEN="$(glassray token)". |
glassray doctor | Local + cloud health: Node version, endpoint reachability, key validity, local server. |
glassray upgrade | How to self-update. |
Global flags
| Flag | Meaning |
|---|---|
--json | Machine output on stdout (status stays on stderr). |
--endpoint <url> | Target deployment (or GLASSRAY_APP_URL; default https://app.glassray.ai). GLASSRAY_ENDPOINT still works but is deprecated for the CLI — it’s being reserved for the SDK’s trace-ingest endpoint. |
--api-key <key> | Org key for CI/headless. Precedence: --api-key > GLASSRAY_TOKEN env > stored credential. |
--debug | Verbose output and stack traces. |
--no-telemetry | Disable run telemetry (or GLASSRAY_NO_TELEMETRY). |
--port <n> | Local Coach port (default 5899). |
GLASSRAY_TOKEN (the CLI’s org key for CI) is distinct from GLASSRAY_API_KEY (the SDK’s
per-source ingest key written into a repo’s .env.local) on purpose — so exporting one in
your shell can never be mistaken for the other.