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

# Incidents and changes

> List and inspect incidents, see who is on call, acknowledge and resolve incidents, annotate dashboards, run synthetic checks from CI, and carry out approved changes with the MoleSignal CLI.

## How a change runs

A command that changes something, such as acknowledging an incident, asks MoleSignal through a
managed tool, as Mole Agent and agent tools do. The organization's Tool Policy sets how each
tool runs, at **Mole Agent → Settings → Tools & capabilities**:

| Execution mode | What the command does |
| - | - |
| Automatic | The change runs at once. |
| Confirmation | MoleSignal asks to confirm, and the command asks on the terminal. `-y` (`--yes`) answers yes ahead of time, as in CI. Without a terminal or `--yes`, nothing changes. |
| Single approval, dual approval | MoleSignal opens an approval request for reviewers at **Mole Agent → Approvals**. The command prints the approval and exits with `3`. With `--wait`, it waits for the decision, up to `--timeout` (30 minutes by default), and then carries the change out. |
| Disabled | The command fails with the reason. |

Without a policy of its own, a tool runs by its risk: the default modes are confirmation for
`create_annotation` and `submit_search_job`, and single approval for `acknowledge_incident`,
`resolve_incident`, and `run_synthetic_monitor`. `--reason` says why, for the reviewers and the
audit log.

Confirming needs the MCP protocol revision 2026-07-28, which the CLI speaks when MoleSignal does.
`molesignal status` reports the revision in use.

## List incidents

```bash theme={null}
molesignal incidents
```

The list shows the active incidents, newest first, with their status, severity, age, services,
and summary. `--status resolved` or `--status all` lists others, `--since 7d` only those opened
since then, and `-n` sets how many.

`molesignal incidents show` prints one incident: its rule, times, services, labels, notes such as
the runbook, and sampled traces. `--rca` adds the root-cause analysis, and `--web` opens the
incident in MoleSignal:

```bash theme={null}
molesignal incidents show <incident> --rca
```

## Acknowledge and resolve incidents

```bash theme={null}
molesignal incidents ack <incident>
```

```bash theme={null}
molesignal incidents resolve <incident> --reason "Rolled back to 2.3.9"
```

Both go through the Tool Policy and take `alerts.acknowledge`.

## See who is on call

```bash theme={null}
molesignal oncall
```

The list shows who is on call for each enabled on-call schedule. `--schedule` keeps one schedule,
and `--at` asks about another time, such as `--at "2026-10-27 09:00"`.

## Carry out approved changes

`molesignal approvals` lists the approval requests that wait for reviewers and those approved but
not yet carried out, from Mole Agent and from agent tools and commands. `--all` lists decided ones
too.

```bash theme={null}
molesignal approvals
```

`molesignal approvals show <approval>` prints one request: its action, target, reason, impact, and
reviews. `molesignal approvals execute <approval>` carries out an approved change; MoleSignal may
ask to confirm it first:

```bash theme={null}
molesignal approvals execute <approval>
```

## Annotate dashboards

`molesignal annotate` adds an annotation at a moment or over a stretch of time, on every dashboard
or on one:

```bash theme={null}
molesignal annotate "Release 2.4.0" --tags release,checkout --yes
```

| Option | Meaning |
| - | - |
| `--description <text>` | More about it. |
| `--tags <a,b>` | Tags to find it by. |
| `--dashboard <id>` | Only on this dashboard. |
| `--stream <stream>` | The stream it is about. |
| `--time <time>`, `--end <time>` | When it started and ended. The default is now, as a moment. |

The annotation takes `dashboards.edit`.

## Run synthetic checks

`molesignal synthetics` lists the checks with their kind, state, and lifecycle.
`molesignal synthetics results <check>` lists a check's latest runs at each location, with their
outcome, duration, and the reason a run failed. A check is named by its id or by its name.

`molesignal synthetics run` runs a check now at each of its locations. With `--wait`, the command
waits for the runs and exits with `1` when one failed or did not finish within `--timeout`
(10 minutes by default), so that a pipeline can stop a release on it:

```bash theme={null}
molesignal synthetics run "Checkout API" --wait --yes
```

A run passes when its outcome is healthy or flaky. Running a check takes `synthetics.manage`; to
run checks from CI without a reviewer, set `run_synthetic_monitor` to **Automatic** in the Tool
Policy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.