Skip to main content

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.

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.
Governance is currently a preview. The web flag release_ui_ai_governance_enabled controls UI visibility — ask your admin to confirm it’s on for your org. The CLI surface is always available once the CLI is installed.

​
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 https://app.langwatch.ai/me 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: 
npm install -g langwatch
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.
Verify: 
$ 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): 
$ 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: 
✓ 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 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).
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.

​
3. Use your tools normally

$ 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: 
$ 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
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 for the assertion shape per tool.

​
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: 
# Add to your ~/.zshrc or ~/.bashrc
eval "$(langwatch init-shell zsh)"
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: 
$ 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

$ langwatch logout-device
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 — how the unified observability substrate underwrites SOC 2 / ISO 27001 / EU AI Act / GDPR / HIPAA-most-uses
  • Per-origin retention — thirty_days / one_year / seven_years retention classes; your IT admin picks the class for each ingest source
  • OCSF / SIEM export — your security team’s SIEM (Splunk, Datadog, Sentinel) pulls these events on a cron via the OCSF v1.1 read API
  • Ingestion sources — the broader picture of what other AI platforms feed into the same governance dashboard

​
For admins setting this up