> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Personal IDE keys — your AI tools, governed by your company

> Install LangWatch, run `langwatch login`, and use Claude Code / Cursor / Codex with org-attributed spend, a personal monthly budget, and zero per-tool config.

Your team uses Claude Code, Codex, Cursor, and Gemini CLI every day.
LangWatch Governance lets your IT admin issue you a single virtual
key — bound to your identity, governed by your team's policy — that
all of those tools share.

This page is the **end-user** flow. If you're an admin setting it up
for your organization, see [Admin setup](/docs/ai-gateway/governance/admin-setup).

<Note>On SaaS, governance rollout is managed per organization: if you don't see these surfaces, or `langwatch login --device` is refused with a governance error, ask your admin.</Note>

## Why this exists (40-second pitch)

You're an engineer at an enterprise. Your IT/platform team gives you
Claude Code, Cursor, Codex, Gemini CLI — and asks for a few things
in return:

* **Per-user spend attribution** so finance can stop staring at unnamed Anthropic invoices
* **A personal monthly budget** so a runaway recursive prompt at 3 AM Saturday doesn't burn \$10k overnight
* **Audit trail** for SOC 2 / ISO 27001 / HIPAA / EU AI Act
* **Zero-config provider setup** — your IT team wired up Anthropic + OpenAI + Gemini at the org level; you inherit them

LangWatch sits above all of it. One `langwatch login`, one
`langwatch claude`, and you're productive — with everything routed
through the gateway, attributed to you, governed by your company's
policy.

## What you get

* One CLI command to sign in: `langwatch login`
* Wrappers that let you keep using the tools you already know:
  `langwatch claude`, `langwatch codex`, `langwatch cursor`,
  `langwatch gemini`
* A personal dashboard at <code>[https://app.langwatch.ai/me](https://app.langwatch.ai/me)</code>
  showing your spending, requests, most-used models, and recent
  activity
* Budget enforcement at the gateway — if you go over your monthly
  cap, the request fails fast with an actionable error

## Setup

### 1. Install the CLI

The `langwatch` CLI ships as an npm package. Today the supported install path is npm / npx:

<CodeGroup>
  ```bash npm (global install) theme={null}
  npm install -g langwatch
  ```

  ```bash npx (no install) theme={null}
  # Run any command without globally installing
  npx langwatch --version
  npx langwatch login --device
  ```
</CodeGroup>

<Note>The single-binary installers (`curl ... | sh`, Homebrew tap, PowerShell `iex`) are on the roadmap but not yet published. Until then, `npm install -g langwatch` is the canonical path on every OS where Node.js is available.</Note>

Verify:

```bash theme={null}
$ langwatch --version
0.26.0
```

### 2. Sign in via your company SSO

The CLI uses RFC 8628 device-flow OAuth — pass `--device` to opt into the SSO path (the bare `langwatch login` form prompts for an API key, which is the older personal-API-key flow not the governance flow):

```bash theme={null}
$ langwatch login --device
🔐 LangWatch governance login
Control plane: https://app.langwatch.ai

Opening: https://app.langwatch.ai/cli/auth?user_code=ABCD-EFGH
If your browser doesn't open, paste the URL above and enter code: ABCD-EFGH

⠋ Waiting for you to log in
```

Your browser opens to a LangWatch page that asks for your work email,
then redirects to your company's IdP (Okta, Azure AD, Auth0,
whatever). After you complete SSO + MFA, control returns to the
CLI with your inherited providers + budget already populated:

```text theme={null}
✓ Logged in as jane@your-company.com @ your-company

Your AI tools are ready:
  • anthropic  (Claude — Sonnet, Haiku)
  • openai     (GPT-5, GPT-5-mini)
  • gemini     (2.5 Pro, 2.5 Flash)

Monthly budget: $500   |   Used: $0.00

Try it:
  $ langwatch claude   # use Claude Code
  $ langwatch codex    # use Codex
  $ langwatch cursor   # use Cursor

Or open your dashboard:
  $ langwatch me

  Gateway:   https://gateway.langwatch.ai
  Dashboard: https://app.langwatch.ai
```

Behind the scenes:

1. The CLI ran an [RFC 8628 device-flow OAuth](https://datatracker.ietf.org/doc/html/rfc8628) handshake against the LangWatch control plane.
2. Your browser ran the SSO flow your IT admin configured (Okta, Google Workspace, Azure AD, or password-only).
3. LangWatch minted a **personal virtual key** scoped to your user identity — signed by the gateway, bound to your monthly budget, audit-trailed per-request.
4. The CLI fetched your inheritable providers + budget from `/api/auth/cli/bootstrap` and rendered the ceremony you see above.

Tokens persisted at `~/.langwatch/config.json` (mode 0600).

<Note>You did **not** pick a model provider during setup. Your
admin already wired up Anthropic, OpenAI, Gemini, etc. at the
organization level. You just inherit them.</Note>

### 3. Use your tools normally

```bash theme={null}
$ langwatch claude
▲  Claude Code v2.1.0
✓  Connected via LangWatch (jane@your-company.com)
> help me refactor this auth middleware
```

Same Claude Code experience as before — flags, terminal handling,
exit codes are all identical because `langwatch claude` `exec`'s
the underlying tool with the right env vars pre-injected.

The same pattern works for Codex, Cursor, Gemini CLI, and opencode:

```bash theme={null}
$ langwatch codex    "fix the failing tests"
$ langwatch cursor                            # opens Cursor with gateway env
$ langwatch gemini   "explain this stack trace"
$ langwatch opencode                          # opens opencode with gateway env
```

<Info>**Verified end-to-end in CI.** `langwatch login` + each of the five wrappers above (`claude`, `codex`, `cursor`, `gemini`, `opencode`) is exercised in the `governance-wrapper.e2e.test.ts` Node-only e2e suite — fake control-plane, fake gateway, mocked tool binaries — covering login config write, env-var injection, routing with bearer-VK, budget pre-flight (402/200/5xx), and exit-code propagation. 16 scenarios, 3-second runtime, runs on every PR. See [CLI debug → e2e coverage](/docs/ai-governance/cli-debug#cli-wrapper-e2e-coverage) for the assertion shape per tool.</Info>

### 4. Or, set it up always-on

If typing `langwatch` every time is friction, you can have your
shell pre-export the env vars so plain `claude`, `codex`, etc.
already route through the gateway:

<CodeGroup>
  ```bash zsh / bash theme={null}
  # Add to your ~/.zshrc or ~/.bashrc
  eval "$(langwatch init-shell zsh)"
  ```

  ```fish fish theme={null}
  # Add to your ~/.config/fish/config.fish
  langwatch init-shell fish | source
  ```

  ```powershell PowerShell theme={null}
  # Add to your $PROFILE
  langwatch init-shell powershell | Invoke-Expression
  ```
</CodeGroup>

After re-sourcing your shell rc, `claude` (without the wrapper)
talks to the gateway too.

## Your dashboard

Open `https://app.langwatch.ai/me` (or run `langwatch me`) to see
your usage:

* Spent vs. budget for the month
* Total requests, week-over-week
* Most-used model
* Spending breakdown by tool (Claude Code, Cursor, Codex)
* Recent activity (last 10 requests with cost + summary)

Your dashboard shows **only** your usage. To switch to a team's
view, use the workspace switcher in the top-left of the navbar.

## Hitting your budget

If you cross 80% of your monthly cap, the dashboard shows a yellow
warning banner. If you hit 100%, your next request fails with a
clear message:

```bash theme={null}
$ langwatch claude
⚠  Budget limit reached

   You've used $500.00 of your $500.00 monthly budget.
   To continue, ask your team admin to raise your limit.

   Admin: platform-team@your-company.com

   Need urgent access? Run:
     langwatch request-increase
```

`langwatch request-increase` opens your dashboard at the budget-request
page (the URL carries the user / limit / spent params HMAC-signed) so
the admin sees the request with full context and can adjust your
budget in real time — no token re-issuance required.

Budgets reset on the period your admin configured (monthly or
weekly).

## Security

* Your access token is short-lived (\~1h) and refreshed automatically.
* Your refresh token is stored at `~/.langwatch/config.json` with
  mode 0600. We're working on OS keyring integration; for now,
  protect that file as you would any local secret.
* Revoking your account at the LangWatch admin console invalidates
  both tokens immediately. Your CLI begins failing within 60s.
* The CLI never sees a raw provider key. The gateway holds the
  upstream credentials.

## Sign out

```bash theme={null}
$ langwatch logout
Logged out — credentials cleared.
```

This clears `~/.langwatch/config.json` locally **and** revokes your
refresh token at the server, so leaked-state can't be reused. The
`-device` suffix disambiguates from the older `langwatch login` API-
key flow (which has its own logout via clearing the env var or
re-running `langwatch login`).

## What's behind the scenes

If you're curious about the platform side:

* [Compliance architecture](/docs/ai-gateway/governance/compliance-architecture) — how the unified observability substrate underwrites SOC 2 / ISO 27001 / EU AI Act / GDPR / HIPAA-most-uses
* [Per-origin retention](/docs/ai-gateway/governance/retention) — `thirty_days` / `one_year` / `seven_years` retention classes; your IT admin picks the class for each ingest source
* [OCSF / SIEM export](/docs/ai-gateway/governance/ocsf-export) — your security team's SIEM (Splunk, Datadog, Sentinel) pulls these events on a cron via the OCSF v1.1 read API
* [Ingestion sources](/docs/ai-governance/ingestion-sources/index) — the broader picture of what other AI platforms feed into the same governance dashboard

## For admins setting this up

* [Admin setup](/docs/ai-gateway/governance/admin-setup) — SSO, gateway provider keys, org-wide monthly budget ceiling
* [Try it locally (dogfood loop)](/docs/ai-gateway/governance/admin-setup#try-it-locally-dogfood-loop) — mint a persona, fire a real completion, watch real spend land on `/me/usage`
* [Control plane](/docs/ai-gateway/governance/control-plane) — the full Tier 1-5 governance dashboard architecture