> ## Documentation Index > Fetch the complete documentation index at: https://glassray.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Every glassray command and global flag — the one CLI for cloud setup and local Coach. `glassray` is the single command-line surface for the product: cloud setup + account operations, and the local [Coach](/coach/overview) loop. Install-free via `npx @glassray/cli`, or globally: ```bash theme={null} npm i -g @glassray/cli # Node ≥ 20.6 npm i -g @glassray/cli@latest # upgrade — the CLI's ▲ notice tells you when ``` Without `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 ` 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](/cli/setup). | | `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 ` 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 ` | 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 ` · `tail`. | | `glassray flows` | `list` · `get` · `create` · `update` · `delete` · `audit` · `discover`. | | `glassray evals` | `list` · `get` · `create` · `update` · `delete` · `run`. | | `glassray deviations` | `list` · `get ` · `discover` · `resolve `. | | `glassray deviations discover` | Cluster recurring failures across recent traces (`--sample` · `--flow`). Canonical; `discovery run` is a kept alias. | | `glassray experiments` | `list [--flow ]` · `get ` — read-only inspect of A/B experiments. | | `glassray fix ` | 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 drives **`glassray.yaml`** — your flows, run recipes, and code root as code. | Command | What it does | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `glassray pull` | Round-trip `glassray.yaml`; `--as-fixtures` / `--traces ` freeze corpora and inputs. | | `glassray push` | Reconcile the file into the store — terraform-style plan/apply (`--dry-run`, `--prune`). | | `glassray run --label ` | Execute the flow's run recipe; traces land tagged with that **run label**. | | `glassray compare ` | 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 ` | 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 ` | 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 ` | 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 ` | 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.