# Overview

> List, read, create, change, pause, resume and delete cost alerts from the terminal, with rules kept as JSON files.

Source: https://docs.levelfour.ai/cli/commands/alerts


`l4 alerts` manages your organization's [cost alerts](/cost-alerts): the rules that watch an account, a saved cost view or your commitments, and tell the people and Slack channels named on them when a line is crossed. `costalerts` and `alert` are aliases.

```bash
l4 alerts <command> [flags]
```

## Subcommands

| Command                                 | Purpose                                                | Scope        |
| --------------------------------------- | ------------------------------------------------------ | ------------ |
| [`list`](#list)                         | Every alert, what it watches, and whether it is firing | `read`       |
| [`get`](#get)                           | One alert in full: recipients, Slack channels and rule | `read`       |
| [`sources`](#sources)                   | The ids a rule's `source_id` can take                  | `read`       |
| [`events`](#events)                     | What an alert has said, newest first                   | `read`       |
| [`create`](/cli/commands/alerts/create) | Create an alert from a JSON rule file                  | `read-write` |
| [`update`](/cli/commands/alerts/update) | Change the fields a JSON file names                    | `read-write` |
| [`pause`, `resume`](#pause-and-resume)  | Silence an alert, or arm it again                      | `read-write` |
| [`delete`](/cli/commands/alerts/delete) | Delete an alert and its history                        | `read-write` |

Every command that takes an `<id>` checks it before calling the API. An id is a UUID, as `l4 alerts list` prints it, and anything else fails with `... is not a cost alert id`.

Global flags (`--json`, `--jq`, `--template`, `--quiet`, `--token`, `--api`) apply to every subcommand. See [CLI overview](/cli#global-flags).

## list

```bash
l4 alerts list
```

One row per alert: its id, name, source, the kind of rule it is (`budget`, `changes` or `commitment`), and its status. `firing` means at least one thing the alert watches has crossed its line, and outranks `enabled`. A paused alert reads `paused by` the person or key that paused it.

## get

```bash
l4 alerts get <id>
```

The alert's name, id, source, kind, status, recipients and Slack channels, then the rule as compact JSON. A channel prints as `#name (id)`, with the name it had when the alert was saved. `--json` prints the whole alert as the API returns it, which is also the shape a rule file takes.

## sources

```bash
l4 alerts sources
```

What an alert can watch, as `ID`, `Label`, `Group` and `Provider`. `Group` is `accounts`, `views` or `commitments`. Every id here is valid in the `source_id` field of a rule file.

## events

```bash
l4 alerts events <id> [--limit 50] [--offset 0]
```

One row per firing and per recovery, newest first: when, the slice it was about (`whole source` when the alert watches one thing), the state, the figure observed, the threshold, the cost basis, and whether anyone was notified.

| Flag       | Description                             |
| ---------- | --------------------------------------- |
| `--limit`  | Events per page, 1 to 200. Default `50` |
| `--offset` | Events to skip. Default `0`             |

## Pause and resume

```bash
l4 alerts pause <id> [--yes]
l4 alerts resume <id> [--yes]
```

`pause` stops an alert from notifying anyone and keeps it, with its history. `resume` arms it again. Both prompt for confirmation unless you pass `--yes`, print the alert's new status, and need a read-write key.

## Rule files

`create` and `update` read JSON from a file, or from stdin with `--file -`, so a rule can be reviewed in a pull request before it reaches the API. The file is the request body: [`create`](/cli/commands/alerts/create) has the fields, and [Cost alerts](/cost-alerts#types) explains each kind of rule. The CLI refuses a file over 1 MiB, or one that is not a JSON object, before it sends anything.

## Examples

```bash
l4 alerts list
l4 alerts get 8f2b1c4e-0000-4a1b-9c3d-5e6f70819234 --json
l4 alerts create --file production-budget.json
l4 alerts pause 8f2b1c4e-0000-4a1b-9c3d-5e6f70819234 --yes
```

## Related

* [Cost alerts](/cost-alerts): the types of rule, where alerts arrive, and how often they are checked
* [Cost Alerts API reference](/api-reference/cost-alerts): the endpoints underneath
* [CLI authentication](/cli/authentication#browser-login-mints-a-read-only-key): the read-write key the writes need