> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/dstl8-docs/events.md).

# Events

Platform events are first-class markers on the Dstl8 timeline — deploys, configuration changes, CI results, scaling actions, maintenance windows, and free-form notes. Send them from scripts, deploy pipelines, and CI, then correlate them with logs and incidents to answer the eternal question: *what changed right before things broke?*

Events come from several places:

* **Automatic** — Kubernetes events flow in through a connected [Kubernetes source](/controltheory-documentation/dstl8-docs/sources/kubernetes.md), and GitHub Actions `workflow_run` results are promoted automatically when a [GitHub source](/controltheory-documentation/dstl8-docs/sources/github-actions.md) is connected.
* **Manual** — send events from the CLI (`dstl8 events send`), the API, or the web UI (the **+ Create Event** button on a workspace's Events page).

### Where events show up

* **Web UI** — the **Events** page shows events across the whole organization; each workspace also has its own Events page. Events are rendered as color-coded markers on log timeline charts (blue for deploys, green for CI, purple for config changes, and so on), so a deploy line lands right on top of the error spike it caused.
* **Incidents** — related events appear alongside an incident so Möbius and humans can correlate cause and effect.
* **TUI** — `dstl8 tui` has an Events tab at both the org and workspace level. Press `Enter` on a row for a scrollable detail modal with the message, attributes, and annotations.
* **CLI** — `dstl8 events list`, `get`, and `search`, documented below.

### Event types and severities

| Type          | Typical use                                                   |
| ------------- | ------------------------------------------------------------- |
| `deploy`      | A deployment started or finished                              |
| `ci`          | A CI pipeline or workflow result                              |
| `config`      | A configuration change (feature flag, env var, infra setting) |
| `scaling`     | A scaling action (HPA change, replica count, instance resize) |
| `maintenance` | A maintenance window                                          |
| `note`        | A free-form human note ("started load test")                  |
| `custom`      | Anything else                                                 |

Severity is `info` (default), `warning`, or `error`.

## Viewing events from the CLI

```bash
dstl8 events list                                # last 24h, newest first
dstl8 events list --start -7d --type deploy,ci   # last 7 days, only deploys and CI
dstl8 events list -w myworkspace -s error        # workspace-scoped, error severity
dstl8 events list --source k8s,github            # only k8s- and github-sourced events
dstl8 events list --object service:checkout      # events for one object
dstl8 events list --search "rollback" --json     # keyword filter, NDJSON output
dstl8 events get <event-id>                      # full detail for one event
dstl8 events search "cache warmer failing"       # semantic search (keyword fallback)
```

`event` is an alias for `events`, and `--json` produces one JSON object per line for piping into `jq` or scripts.

**`list` flags:**

| Flag              | Description                                                   |
| ----------------- | ------------------------------------------------------------- |
| `--start`         | Start time (default `-24h`)                                   |
| `--end`           | End time (default now)                                        |
| `--type`          | Event type filter (comma-separated or repeatable)             |
| `-s, --severity`  | Severity filter (`info`, `warning`, `error`; comma-separated) |
| `--source`        | Source type filter (`cli`, `k8s`, `api`, `ui`, `github`, …)   |
| `--object`        | Object filter as `type:name` (e.g. `service:checkout`)        |
| `--search`        | Keyword search over title/message/reason/object               |
| `-w, --workspace` | Workspace name or ID                                          |
| `-n, --limit`     | Max number of events (default 100)                            |
| `--json`          | NDJSON output                                                 |

Time formats for `--start`/`--end`: relative (`-30m`, `-1h`, `-24h`, `-7d`, `now`) or absolute (`2026-07-08`, `2026-07-08T09:30:00`).

`dstl8 events search` uses semantic search when embeddings are available, falling back to keyword search otherwise (the mode used is printed to stderr).

## Sending events

```bash
dstl8 events send --type deploy --title "Deployed checkout v1.42" \
    --reason deploy.finished --object service:checkout --env prod \
    --attr image=checkout:v1.42 --attr sha=abc123

dstl8 events send --type note --title "Started load test" --occurred-at -5m

dstl8 events send --type config --title "Raised HPA max to 20" --severity warning
```

`send` prints the created event ID on success (or the full event with `--json`) so scripts can capture it. Events sent from the CLI are recorded with `source_type=cli`.

**`send` flags:**

| Flag               | Description                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `--type`           | **Required.** Event type (`deploy`, `ci`, `config`, `scaling`, `maintenance`, `note`, `custom`, …) |
| `--title`          | **Required.** Short one-line title                                                                 |
| `--reason`         | Machine-readable subtype (e.g. `deploy.finished`)                                                  |
| `--message`        | Longer message body                                                                                |
| `--severity`       | `info` (default), `warning`, or `error`                                                            |
| `--object`         | Object association as `type:name` (e.g. `service:checkout`)                                        |
| `--env`            | Environment (e.g. `prod`)                                                                          |
| `--cluster`        | Cluster name                                                                                       |
| `--namespace`      | Namespace                                                                                          |
| `-w, --workspace`  | Workspace name or ID (omit for an org-wide event)                                                  |
| `--attr key=value` | Attribute (repeatable)                                                                             |
| `--occurred-at`    | When it happened (`now`, `-5m`, or `2026-07-08T12:00:00Z`; default now)                            |
| `--ended-at`       | End time for span-like events (maintenance windows, load tests)                                    |
| `--dedup-key`      | Coalesce repeated events into one counted row                                                      |
| `--json`           | Print the full created event as JSON                                                               |

{% hint style="info" %}
Use `--dedup-key` for anything that might fire repeatedly (a retrying deploy hook, a flapping config sync). Events with the same dedup key coalesce into a single row with a count instead of flooding the timeline.
{% endhint %}

## CI/CD integration

Call `dstl8 events send` from a deploy script, GitHub Actions step, or Terraform hook to drop a marker on the timeline the moment a change ships:

```bash
# At the end of a deploy script:
dstl8 events send --type deploy \
  --title "Deployed $SERVICE $VERSION" \
  --reason deploy.finished \
  --object "service:$SERVICE" --env prod \
  --attr "sha=$GIT_SHA" --attr "version=$VERSION"
```

The CLI authenticates from its local config (`~/.config/dstl8/`), so the machine running the script needs to have been logged in once with `dstl8 login`. For headless runners, restore a pre-authenticated `~/.config/dstl8/` directory (its `profiles.toml` and `auth.json`) from your secrets store before calling the CLI.

{% hint style="success" %}
**Using GitHub Actions?** You may not need the CLI at all — when a [GitHub source](/controltheory-documentation/dstl8-docs/sources/github-actions.md) is connected, `workflow_run` results are promoted to platform events automatically.
{% endhint %}

## Deleting events

Deletion is intentionally restricted: only human- or tooling-authored events (`cli`, `api`, `ui`) can be removed, via the web UI. Machine-generated events (`k8s`, `github`) are an immutable timeline.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/dstl8-docs/events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.