---
name: alertstore-cli
description: |
  Read-only alertstore access for Investibook agents. Use for TiDB Cloud
  operational alerts identified by an ALT-* id (e.g. ALT-2608-1742): fetch alert
  detail, timeline, and events, and list alerts by cluster / tenant / state.
  Alertstore is the single source of truth for these alerts. Read-only — no
  lifecycle (ack/resolve/assign/comment) or subscription/mute writes.
---

# Alertstore CLI

Use this skill when the workspace context or the user references an alertstore
alert (`ALT-<weeknum>-<seq>`, e.g. `ALT-2608-1742`). Prefer the bundled script so
requests are authenticated and JSON-shaped consistently.

Alertstore is the SSOT for TiDB Cloud operational alerts. It shares the DevOps
gateway, so authentication works exactly like the builtin `devops` skill. The
bundled helper is the complete supported surface for Investibook. Do not fall
back to a generic HTTP helper or a write-capable Alertstore reference.

## Authentication

The script reads credentials from the workspace process environment:

- API key: `DEVOPS_API_KEY` (`DEVOPS_API_TOKEN` remains a compatibility fallback)
- Base URL: `DEVOPS_BASE_URL` / `DEVOPS_BASE_DOMAIN`, default `https://prod.devops.pingcap.com`
- Or pass `--env prod|staging|dev` to select the gateway explicitly (default `prod`)

Do not print or log credential values.

## Ownership: check `attrs.owned` first

Each alert has a frozen `attrs.owned` boolean:

- **`owned: true`** — alertstore runs the full lifecycle and is the source of truth.
- **`owned: false`** — a shadow copy of a Jira-managed alert; lifecycle lives in
  **Jira**, alertstore only stores it for visibility.

This skill is read-only, so it does not act on the lifecycle either way — but
report `attrs.owned` and `external_issue_url` so the user knows where actions
belong (alertstore Web UI for `owned: true`, Jira for `owned: false`).

## Commands

Run from the workspace root:

```bash
python3 .opencode/skills/builtin/alertstore-cli/scripts/alertstore_api.py get-alert --alert-id ALT-2608-1742
python3 .opencode/skills/builtin/alertstore-cli/scripts/alertstore_api.py get-timeline --alert-id ALT-2608-1742
python3 .opencode/skills/builtin/alertstore-cli/scripts/alertstore_api.py list-alerts --state open --classification page --limit 10
python3 .opencode/skills/builtin/alertstore-cli/scripts/alertstore_api.py search-by-cluster --cluster-id 1234567890
python3 .opencode/skills/builtin/alertstore-cli/scripts/alertstore_api.py search-by-tenant --tenant-id tenant_abc123
python3 .opencode/skills/builtin/alertstore-cli/scripts/alertstore_api.py list-events --alertname TiKV_disk_almost_full --status firing
python3 .opencode/skills/builtin/alertstore-cli/scripts/alertstore_api.py get-event --event-id 12345
```

| Command | Required args | Optional args | Description |
|---|---|---|---|
| `get-alert` | `--alert-id` | `--env` | Fetch one `AlertDetail` (attrs, common_facts, instances, audit, am_status, external_issue_url) |
| `get-timeline` | `--alert-id` | `--env` | Human timeline entries; `null` when nobody has interacted with the alert yet |
| `list-alerts` | | `--state` `--classification` `--region` `--tenant-kind` `--assigned-to` `--cluster-id` `--tenant-id` `--limit` `--offset` `--env` | List alerts, newest-first |
| `search-by-cluster` | `--cluster-id` | `--state` `--limit` `--offset` `--env` | List alerts for one cluster |
| `search-by-tenant` | `--tenant-id` | `--state` `--limit` `--offset` `--env` | List alerts for one tenant |
| `list-events` | | `--alertname` `--classification` `--cluster-id` `--tenant-id` `--status` `--limit` `--offset` `--env` | List raw Alertmanager events |
| `get-event` | `--event-id` | `--env` | Fetch one event |

## Notes

- Alert id format is `ALT-<weeknum>-<seq>`, e.g. `ALT-2608-1742`.
- Alert states: `open` → `acked` → `resolved`. Classifications: `page`, `ticket`,
  `logging`. Listing has no total count — page with `--offset` until empty.
- System events (AM status changes, IM topic creation) live in the alert
  detail's `audit[]`, not in `get-timeline`.
- After grounding the alert, feed the alert name into the builtin
  `o11y-alert-rule-lookup` skill to resolve the matching Prometheus rule, then
  use `clinic-cli` for evidence — same downstream as O11Y alerts.

## Write Policy

This skill is **read-only**. Ack, resolve, assign, comment, and
subscription/mute-rule changes are intentionally not available here. Present
findings to the user and point them to the alertstore Web UI (`owned: true`) or
Jira (`owned: false`) for any lifecycle action.