> ## 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 & coding agents

> Every glassray-coach command, how to choose an analysis model, and how to drive the whole Coach loop from your coding agent with the shipped skill.

## Install & upgrade

`npx @glassray/coach start` needs no install. For a permanent `glassray-coach` command:

```bash theme={null}
npm i -g @glassray/coach          # install (Node ≥ 20.6)
npm i -g @glassray/coach@latest   # upgrade - the CLI's ▲ notice tells you when
npm rm -g @glassray/coach         # uninstall
```

<Note>
  **nvm users:** global installs are per Node version - after `nvm use` on another version, reinstall (or install onto a system Node, e.g. Homebrew's, to keep it everywhere). **EACCES on install?** Don't `sudo` - point npm at a user prefix once: `npm config set prefix ~/.npm-global`, then add `~/.npm-global/bin` to your PATH.
</Note>

Installing is not the same as running: `glassray-coach start` runs the server in a foreground terminal - there's no background service.

## Server commands

| Command                                  | What it does                                                                                                                                                                                                                                                                                       |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `glassray-coach start`                   | Start the server + dashboard. On a fresh store, in an interactive terminal, it offers the setup menu: run Claude Code headlessly on the onboarding prompt (git writes hard-blocked), copy the prompt, or show the manual OTLP wiring. Flags: `--port` (default `5899`), `--data-dir`, `--no-open`. |
| `glassray-coach init`                    | Install the **agent skill** into the current repo - `./.agents/skills/` (the open [Agent Skills](https://agentskills.io) standard: Codex, VS Code, Copilot) + `./.claude/skills/` (Claude Code); `--force` overwrites a modified copy.                                                             |
| `glassray-coach status`                  | Show the data directory and probe whether a Coach is answering on the port.                                                                                                                                                                                                                        |
| `glassray-coach doctor`                  | Check Node version, port availability, and data-dir writability - with one-line fixes.                                                                                                                                                                                                             |
| `glassray-coach reset --yes`             | Wipe the local data directory (asks to confirm without `--yes`).                                                                                                                                                                                                                                   |
| `glassray-coach` / `glassray-coach help` | The branded landing screen: server status, every command, guide links. `glassray-coach help <command>` (or `<command> --help`) prints a data command's own usage block.                                                                                                                            |
| `glassray-coach --version`               | Print the CLI version.                                                                                                                                                                                                                                                                             |

<Warning>
  `glassray-coach mcp` was **removed in 0.2** - the CLI below is now the one agent surface. If you had it registered: `claude mcp remove glassray`, then `glassray-coach init`.
</Warning>

## Data commands

Everything the dashboard can do, scriptable - and consumed by coding agents. The contract: **stdout is the API's JSON verbatim**, human messages go to stderr, and exit codes are `0` (ok), `1` (API error), `2` (no Coach running). Run-starting verbs block and poll the run to completion (`--no-wait` to skip, `--timeout <s>` to bound); all take `--port`.

| Command                                                                     | What it does                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `glassray-coach traces list [--q --agent --status --flow --limit --offset]` | List traces, filterable down to one flow's members.                                                                                                                                                                                |
| `glassray-coach traces get <id>`                                            | One trace's full span-tree view.                                                                                                                                                                                                   |
| `glassray-coach traces tail`                                                | Live stream of ingested trace ids, one JSON object per line.                                                                                                                                                                       |
| `glassray-coach stats` / `glassray-coach usage`                             | Store rollups / Coach's own LLM spend vs. budget.                                                                                                                                                                                  |
| `glassray-coach flows list · get · create · update · delete · audit`        | Durable flow CRUD - see [the worked loop](/coach/analyze). `create` takes `--name`, `--selector '<json>'` and/or `--rule` (+ `--classify selector\|llm`).                                                                          |
| `glassray-coach flows discover [--code-root <path>]`                        | Read your agent's own **source** (the `--code-root`, or `codeRoot:` in `glassray.yaml`) and propose flows inferred from it - name-deduped, so it only ever adds.                                                                   |
| `glassray-coach evals list · get · create · update · run · delete`          | Flow-scoped evals; either `create --deviation <id> [--flow <id>]` (promote a deviation) or `create --name <s> --text <s> [--flow <id>] [--threshold <0..1>] [--autorun-threshold <n>]` (author a rule); `run` prints the verdicts. |
| `glassray-coach deviations list · get · discover · resolve`                 | Discovery output and the resolve step of the loop.                                                                                                                                                                                 |
| `glassray-coach deviations discover [--sample --flow]`                      | Deviation discovery from **traces** - clusters recurring failures, optionally scoped to a flow's members. (`discovery run` is a kept alias.)                                                                                       |
| `glassray-coach experiments list · get`                                     | Read-only inspect of A/B experiments: `list [--flow <id>]`, `get <id>` (JSON verbatim).                                                                                                                                            |
| `glassray-coach fix <deviationId>`                                          | Generate the fix doc; prints the deviation with its `fixMarkdown`.                                                                                                                                                                 |
| `glassray-coach runs list · get · cancel`                                   | Inspect and cancel background runs (`queued → running → done\|error`).                                                                                                                                                             |

## Loop verbs (harness & CI)

These verbs drive **`glassray.yaml`** - the portable artifact that holds your flows (rules + selectors), run recipes (`run.command`), and code root (`codeRoot`). `pull`/`push` round-trip the file, `run` executes its recipes, `compare` A/Bs the traffic they produce, and `check` gates CI on the whole rule suite.

| Command                                                                               | What it does                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `glassray-coach pull [--from local\|cloud] [--out glassray.yaml]`                     | Round-trip `glassray.yaml`. Also `pull --as-fixtures [--flow <id>] [--limit <n>] [--dir glassray/fixtures]` and `pull --traces <flow> [-n <count>] [--inputs-dir glassray/inputs]` to freeze corpora / inputs. |
| `glassray-coach push [--file glassray.yaml] [--dry-run] [--prune] [--target local]`   | Reconcile the file into the store - a terraform-style plan/apply (`--dry-run` plans, `--prune` removes what the file dropped).                                                                                 |
| `glassray-coach run <flow> --label <name> [--file glassray.yaml]`                     | Execute the flow's run recipe from `glassray.yaml`; traces land tagged with that **run label** (it becomes the trace `environment`).                                                                           |
| `glassray-coach compare [<flow>] <baseline> <candidate> [--flow <id>] [--sample <n>]` | A/B two corpora over the rule suite. Corpus tokens: a bare token = a run label; prefixed `label:<x>`, `agent:<name>`, `flow:<id>`, `fixtures:<dir>`.                                                           |
| `glassray-coach check [--fixtures] [--dir glassray/fixtures] [--sample <n>]`          | The **CI gate**: runs every rule and exits non-zero if any pass-rate is below its threshold.                                                                                                                   |
| `glassray-coach link <project> [--endpoint <url>] [--token <t>]` · `link --show`      | Record a cloud project ref so local work can be pushed up.                                                                                                                                                     |

## LLM provider

Discovery, evals, flows, background classification, and replay need a model. Coach chooses one via `GLASSRAY_LLM_PROVIDER`:

| Provider              | Needs                             | Notes                                                                              |
| --------------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
| `claude-subscription` | a local `~/.claude` (Claude Code) | **Default when `~/.claude` exists.** Zero-config, no API key.                      |
| `anthropic`           | `ANTHROPIC_API_KEY`               | A metered API key.                                                                 |
| `openai`              | `OPENAI_API_KEY`                  | A metered API key.                                                                 |
| `mock`                | nothing                           | **Default with no `~/.claude`.** Deterministic and offline - the airgap / CI path. |

```bash theme={null}
# Real analysis with an API key
GLASSRAY_LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-... npx @glassray/coach start
```

<Info>
  Every analysis call is metered against **`GLASSRAY_LLM_BUDGET_USD`** (default `$50`; `0` = unlimited). The free `mock` / `claude-subscription` paths accrue `$0` and are never blocked.
</Info>

<Tip>
  You don't have to set env vars - the dashboard's **Settings** page lets you pick the provider, the heavy/light model ids, and the budget from dropdowns. Those choices persist to disk (`settings.json`, `chmod 0600`) and override the environment. API keys stay in the environment, never in Settings.
</Tip>

## Environment variables

Every setting has a working default - a fresh run needs none of these.

| Variable                               | Default                                                  | What it does                                                                                       |
| -------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `GLASSRAY_HOME`                        | `~/.glassray`                                            | Data directory (embedded database + local key).                                                    |
| `GLASSRAY_PORT` (or `PORT`)            | `5899`                                                   | Port Coach binds on `127.0.0.1`.                                                                   |
| `GLASSRAY_LLM_PROVIDER`                | `claude-subscription` if `~/.claude` exists, else `mock` | Analysis backend (see above).                                                                      |
| `GLASSRAY_HEAVY_MODEL_ID`              | `claude-opus-4-8` (`gpt-4o` on `openai`)                 | Heavy-tier model id - applies to every provider.                                                   |
| `GLASSRAY_LIGHT_MODEL_ID`              | `claude-sonnet-4-6` (`gpt-4o-mini` on `openai`)          | Light-tier model id - applies to every provider.                                                   |
| `GLASSRAY_LLM_BUDGET_USD`              | `50`                                                     | Metered spend cap; `0` = unlimited.                                                                |
| `GLASSRAY_RUN_TIMEOUT_MS`              | `600000`                                                 | Backstop timeout for a background run so a stalled model call can't wedge the queue; `0` disables. |
| `GLASSRAY_CLASSIFY_DEBOUNCE_MS`        | `5000`                                                   | Quiet period after the last ingest before the background classify sweep runs.                      |
| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | -                                                        | Required by the matching metered provider.                                                         |
| `GLASSRAY_NO_UPDATE_CHECK`             | -                                                        | Disable the npm update check entirely (also honors `NO_UPDATE_NOTIFIER` and `CI`).                 |

Human-facing commands (the landing screen, `start`, `status`, `init`) print a one-line notice when a newer version is on npm - refreshed in the background at most once a day, with `glassray-coach doctor` doing the one live check. The check is a single HTTPS request to registry.npmjs.org containing only the package name, and it never runs from the server or the data commands - the egress guarantees for your trace data are unchanged.

## Drive the whole loop from your coding agent

Coach ships its agent integration as a skill in the open [Agent Skills](https://agentskills.io) format - one `SKILL.md` that works in Claude Code, OpenAI Codex, VS Code, and GitHub Copilot.

### Install the skill

Pick whichever route fits how you manage skills - all three install the same file:

<Tabs>
  <Tab title="glassray-coach init">
    The zero-thought route, bundled with Coach. From the repo your agent lives in:

    ```bash theme={null}
    glassray-coach init          # → ./.agents/skills/glassray/ + ./.claude/skills/glassray/
    ```

    Installs to **both** standard locations - `.agents/skills/` (the open standard: Codex, VS Code, Copilot) and `.claude/skills/` (Claude Code) - idempotently; `--force` overwrites a locally edited copy.
  </Tab>

  <Tab title="npx skills">
    Prefer a skills manager? The community [`skills` CLI](https://github.com/vercel-labs/skills) installs straight from the Coach repo into 70+ agents (Claude Code, Cursor, Codex, Windsurf, Cline, …):

    ```bash theme={null}
    npx skills add glassray/glassray-coach            # pick agents interactively
    npx skills add glassray/glassray-coach -g         # user-wide instead of per-repo
    npx skills add glassray/glassray-coach -a cursor  # target one agent
    ```

    It discovers the skill from the repo's `skills/` directory and manages updates with `npx skills update glassray`.
  </Tab>

  <Tab title="Manual">
    It's one file - copy it wherever your agent looks for skills:

    ```bash theme={null}
    mkdir -p .agents/skills/glassray
    curl -o .agents/skills/glassray/SKILL.md \
      https://raw.githubusercontent.com/glassray/glassray-coach/main/skills/glassray/SKILL.md
    ```

    Claude Code reads `.claude/skills/`, Codex reads `.agents/skills/`, VS Code + Copilot read both (and `.github/skills/`).
  </Tab>
</Tabs>

### What the skill does

The skill teaches the coding agent the full workflow over the CLI, **server-first** - flows and rules are created in the server (what the dashboard shows), and `glassray.yaml` is the committed snapshot: inventory the durable state first (`flows list` / `evals list` - flows persist across sessions, so nothing gets re-created), **delegate flow discovery to Coach's own code explorer** (`flows discover --code-root` reads your source and writes flows + code-anchored rules straight into the server), review and tighten what it found, wire tracing and verify one trace end-to-end, snapshot with `pull`, and self-correct vague flow definitions with `flows audit`. It finishes with a coverage report - behaviours found vs instrumented vs skipped. Because every command emits stable JSON, what Claude sets up in one terminal session is exactly what the next session finds.

<Tip>
  The easiest entry needs no typing at all: on an empty store, `glassray-coach start` and the dashboard's empty state hand you a **copy-paste onboarding prompt** that drives this whole setup. And once flows and evals exist the loop stays closed on its own: Coach classifies new traffic in the background and **auto-reruns** each flow-bound eval once enough new member traces land (autorun is on by default; tune or disable it per rule) - apply a `glassray-coach fix`, send fresh traffic, and the reruns happen without you. `glassray-coach evals run <id>` forces one immediately.
</Tip>

## Data & privacy

Everything lives under `~/.glassray` (an embedded PGlite database + a local API key, `chmod 0600`). Coach binds `127.0.0.1` only and enforces a loopback guard on every route - nothing is uploaded, and there's no account. To start fresh, `glassray-coach reset --yes`.