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

# Set up with the CLI

> One command takes your repo from nothing to a watched Glassray account — sign in, connect everything in a quick browser wizard, wire the SDK locally, and confirm a real trace landed before it finishes.

Glassray watches your agent, catches what breaks, and helps you ship the fix. `glassray setup`
is the set-and-forget way to get there: run one command in your agent's repo, do a quick setup
in your browser, and come back to a **verified, watched account**.

The command is a **launcher**. It signs you in, hands the connecting — GitHub, traces, Slack —
to a browser wizard, mirrors each step back to your terminal as you finish it, and then does
the one thing that has to happen locally: wiring the tracing SDK into your code. It won't call
itself done until it has seen a real, correctly-tagged trace arrive.

None of your source code ever leaves your machine — the CLI edits files locally (or hands a
prompt to your own Claude Code) and only talks to Glassray over HTTPS.

## One command

```bash theme={null}
npx @glassray/cli setup
```

<Steps>
  <Step title="Sign in (terminal)">
    The CLI opens your browser to sign in (it also prints the link, so this works over SSH).
    Sign in — or sign up, and you'll name your organization and become its admin. Your account
    key is saved to `~/.config/glassray/credentials.json`, readable only by you, and never
    written into a committed file: `.mcp.json` refers to it only as `${GLASSRAY_TOKEN}`.

    <Note>
      Belong to more than one organization? The CLI shows a picker — choose one, or create a
      brand-new organization right there. (`--org <name-or-id>` still works on both
      `glassray setup` and `glassray login`, and is the way to choose in CI.)
    </Note>
  </Step>

  <Step title="Pick your project (terminal)">
    Next, the CLI asks **which project** this setup is for — prod, staging, demo, local — or
    creates a new one on the spot (just hit Enter to keep the default). Everything after this
    lands in that workspace: the GitHub and Slack connections, your trace source, and the
    onboarding itself. If your key is already bound to a project from an earlier run, the CLI
    tells you and skips the question.
  </Step>

  <Step title="Finish setup in your browser">
    A short wizard opens, in the browser where you're already signed in — scoped to the project
    you just picked — and walks you through connecting everything:

    * **Connect your code** — install the Glassray GitHub App (read-only) and pick your repo.
    * **Connect traces** — either pull from a provider you already use (LangSmith, Langfuse,
      PostHog), or choose the **SDK** and Glassray wires it into your code from your terminal.
    * **Notifications** — connect Slack so you get pinged when something breaks (skippable).

    When you finish, the wizard tells you to head back to your terminal.
  </Step>

  <Step title="Back in your terminal — live status + SDK">
    As each browser step lands, your terminal lights up: `GitHub ✓  Slack ✓  Sources ✓`. If you
    chose the **SDK** (or skipped traces), the CLI provisions your trace source in the project
    you picked earlier and confirms it — `source created in project "staging"`.
    Then the CLI **shows your ingest key** and **asks** before it
    writes anything — say yes and it saves the key to your env file (it detects `.env.local` or
    `.env`, and gitignores it). Then it wires `@glassray/tracing` into your code — tagging every
    trace with the three things Glassray needs (`glassray.customer` / `agent` / `flow`).

    That happens locally. If it hands the work to Claude Code, the run is **headless** — Claude
    applies the change and exits back to your terminal, streaming its progress as it goes — and
    it can never `git commit` or `git push`: those are hard-blocked, so the change always lands
    uncommitted for you to review. (`--run` runs Claude Code without asking; `--prompt-only` just
    prints the prompt; `--skip-instrument` wires no code but still provisions your key.)
  </Step>

  <Step title="Confirm a trace lands">
    Run your agent once. The CLI keeps watching until a trace with the right tags shows up in
    Glassray, then prints the report. If nothing lands, it names the likely cause — wrong key,
    wrong endpoint, a missing `flush()`, or a filter dropping it. (If you'd rather check later,
    `glassray verify --wait` is the same gate on its own.)
  </Step>
</Steps>

## What it leaves behind

* Your ingest key as `GLASSRAY_API_KEY` in `.env.local` (or `.env`), gitignored — the key your
  agent uses to send traces. Only on the SDK path, and only if you said yes when it asked.
* `.mcp.json` — so your AI assistant (Claude Code, Cursor) can use Glassray's tools. The key is
  referenced as `${GLASSRAY_TOKEN}`, never written in, so the file is safe to commit.
* A small, reviewable change to your code — the SDK setup + tags — again, only on the SDK path.

Want your coding agent to run the loop for you later? `glassray init` drops the Glassray skill
into `.claude/skills/glassray` and `.agents/skills/glassray` — an operating manual it can follow.

No daemon, no commits, no lock-in. From here your day-to-day surface is Slack and your own Claude
Code; the dashboard is optional.

## Re-running is always safe

Re-run `glassray setup` any time. If your onboarding is already done, it **skips the browser
wizard entirely** and goes straight to status — and, on the SDK path, the local wiring. Every
step checks what's already there, so *just run it again* is the universal recovery: no cleanup,
no duplicate orgs, no duplicate sources.

## CI / headless

First-time onboarding needs a browser — the connecting happens in the wizard. Two headless paths:

* **Already onboarded once (in a browser)?** `glassray setup --api-key <org-key>` skips the
  browser and just does the local SDK wiring + verify.
* **Scripting from scratch?** The genuinely headless pieces are the SDK ones —
  `glassray instrument --prompt-only` then `glassray verify --wait` (both take `--api-key`). To
  connect a trace source without a browser (CI / agents), use the MCP tools —
  `connect_otlp_source` / `connect_pull_source` — since `glassray connect` now just opens the
  dashboard.

The key comes from whichever you set, in order: the `--api-key` flag, then the `GLASSRAY_TOKEN`
environment variable, then the saved credential. `GLASSRAY_TOKEN` is deliberately **different**
from the SDK's `GLASSRAY_API_KEY` ingest key, so a shell that exports one can never be mistaken
for the other.

See the [command reference](/cli/reference) for every command and flag.