> ## 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.
# Governance CLI debug helpers
> Inspect IngestionSources, tail recent OCSF events, and read the org governance setup state from the terminal.
**Pairs with:** [AI Gateway → CLI Integrations](/docs/ai-gateway/cli/overview). The `langwatch` CLI is shared between Gateway and Governance, `login` and `logout` are gateway-side, `ingest` and `governance status` subcommands are governance-side, both behind the same device-flow OAuth.
A small set of read-only commands for SREs, governance admins, and on-call engineers to answer "is data flowing?" without opening the web UI. They reuse the same backend the [admin oversight dashboard](/docs/ai-governance/control-plane) and the [per-source detail page](/docs/ai-gateway/governance/admin-setup#ingestion-sources) already render, so what you see in the terminal and what you see in the browser are guaranteed identical (byte-for-byte on `--json`).
## When to use
* **"Did my OTLP push actually land?"**: `langwatch ingest tail ` and watch events stream as you fire from the upstream platform.
* **"Why isn't the source flipping to Active?"**: `langwatch ingest health ` shows 24h, 7d, 30d counts plus the timestamp of the last successful event.
* **"Has anyone in this org started using governance yet?"**: `langwatch governance status` mirrors the OR-of-flags that drives the MainMenu Govern entry promotion in the web app.
* **"I need machine output for a runbook step, SIEM script"**: every command accepts `--json` and is contract-stable against the equivalent tRPC procedure.
These commands are **not** for end-user developers, they don't proxy completions, debit budgets, or mutate state. For coding-CLI integration, see [Coding CLI Integrations](/docs/ai-gateway/cli/overview).
## Prerequisites
```bash theme={null}
# Authenticate via device-flow OAuth, opens your browser to /cli/auth
langwatch login --device
```
The same `~/.langwatch/config.json` the rest of the governance CLI uses persists the Bearer access token. Token TTL is 1h with a long-lived refresh token; the CLI rotates transparently. `langwatch logout` server-revokes both.
The `ingest` and `governance` subcommands are always registered — `langwatch --help` lists them once the CLI is installed. Per-account governance entitlement is enforced server-side.
## `langwatch governance status`
The org-level setup-state OR-of-flags. Mirrors `api.governance.setupState` exactly, same boolean shape that promotes the MainMenu **Govern** entry from hidden → visible once any 3 of 5 are true.
```text theme={null}
$ langwatch governance status
Governance setup state
· Personal VKs
· Routing policies
✓ Ingestion sources
✓ Anomaly rules
✓ Recent activity (30d)
Governance active: yes
```
A `✓` is a flag the org already qualifies for; a `·` is one it does not. The bottom line (`Governance active: yes/no`) is the OR of the five, `yes` if any of them are on, `no` otherwise.
`--json` for machine output (exact contract match with the tRPC procedure):
```text theme={null}
$ langwatch governance status --json
{
"setup": {
"hasPersonalVKs": false,
"hasRoutingPolicies": false,
"hasIngestionSources": true,
"hasAnomalyRules": true,
"hasRecentActivity": true,
"governanceActive": true
}
}
```
Pipe to `jq` for runbook predicates: `langwatch governance status --json | jq -r '.setup.governanceActive'`.
## `langwatch ingest list`
The org's IngestionSources, active by default. Pass `--all` to include archived rows.
```text theme={null}
$ langwatch ingest list
NAME TYPE STATUS LAST EVENT
Dogfood OTel · alexis lane otel_generic active 46m ago
```
Status colouring:
* **active** (green), events received in the last 30d.
* **awaiting\_first\_event** (yellow), secret minted, source created, no events yet.
* **archived** (grey), soft-deleted, hidden by default.
`--json` returns the full row shape used by `api.ingestionSources.list`:
```text theme={null}
$ langwatch ingest list --json
[
{
"id": "JxQztBgN90QeX12-afJ0C",
"name": "Dogfood OTel · alexis lane",
"sourceType": "otel_generic",
"description": null,
"status": "active",
"lastEventAt": "2026-04-27T07:11:19.105Z",
"createdAt": "2026-04-27T06:25:27.884Z",
"archivedAt": null
}
]
```
The `id` is the same one you pass to `ingest health` and `ingest tail`.
## `langwatch ingest health `
A one-shot snapshot: events received in the last 24h, 7d, 30d, plus the timestamp of the most recent successful event. Wraps `api.activityMonitor.sourceHealthMetrics`, the same query the per-source detail page's metric strip uses.
```text theme={null}
$ langwatch ingest health JxQztBgN90QeX12-afJ0C
Dogfood OTel · alexis lane (JxQztBgN90QeX12-afJ0C)
Status: active
Events (24h): 1
Events (7d): 1
Events (30d): 1
Last event: 47m ago
```
`--json`:
```text theme={null}
$ langwatch ingest health JxQztBgN90QeX12-afJ0C --json
{
"source": {
"id": "JxQztBgN90QeX12-afJ0C",
"name": "Dogfood OTel · alexis lane",
"status": "active"
},
"health": {
"events24h": 1,
"events7d": 1,
"events30d": 1,
"lastSuccessIso": "2026-04-27T07:11:18.963Z"
}
}
```
Useful for a Datadog, Grafana check: pipe `events24h` through `jq` and alert when it drops to zero on a source you expect traffic from.
## `langwatch ingest tail `
Stream the most recent OCSF-normalised events for a source. Wraps `api.activityMonitor.eventsForSource`, the same query the per-source detail page renders, so the CLI tail and the web event list show identical data.
```text theme={null}
$ langwatch ingest tail JxQztBgN90QeX12-afJ0C --limit 5
2026-04-27T07:11:18.963Z api.call chat_completion → claude-3-5-sonnet
```
Format per row: ` → $cost /