# l4 alerts create

> Create a cost alert from a JSON rule file, or from a rule piped in on stdin.

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


`l4 alerts create` creates a cost alert from a JSON rule file.

```bash
l4 alerts create --file <path|-> [--yes]
```

## The rule file

```json title="production-budget.json"
{
  "name": "Production budget",
  "source_id": "123456789012",
  "params": {
    "kind": "budget",
    "budget": 40000,
    "reset": "monthly",
    "rules": [{ "amount": 80, "unit": "percent" }]
  },
  "recipients": [{ "name": "Ana", "email": "ana@example.com", "member": true }],
  "slack_channel_ids": ["C0123ABCD"]
}
```

| Field               | Description                                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | What the alert is called, shown in every notification                                                                                                |
| `source_id`         | What it watches: an id from [`l4 alerts sources`](/cli/commands/alerts#sources)                                                                      |
| `params`            | The rule. `kind` is `budget`, `changes` or `commitment`, and [Cost alerts](/cost-alerts#types) says when each one fires                              |
| `recipients`        | Members of your organization to notify. Each takes `name`, `email` and `member: true`                                                                |
| `slack_channel_ids` | Up to 10 Slack channel ids to post in. Leave it out to post in your organization's default channel, if one is set. An empty list posts in no channel |

An alert needs a recipient or a Slack channel, and the API refuses one with neither.

## Flags

| Flag           | Description                                           |
| -------------- | ----------------------------------------------------- |
| `-f`, `--file` | The rule file, or `-` to read it from stdin. Required |
| `-y`, `--yes`  | Skip the confirmation prompt                          |

## Confirmation

At a terminal, the command asks `Create this cost alert? [y/N]`. Anything other than `y` or `yes` aborts, prints `Aborted.`, and exits `0` without calling the API. In a pipe or a script, where stdout is not a terminal, it creates the alert without asking.

> **Warning**
>
> `--file -` reads the rule from stdin, which leaves nothing to answer the prompt with. At a terminal, pass `--yes` with it, or the command exits `1` with `--file - reads the rule from stdin, which leaves nothing to answer the prompt with: pass --yes`.

## Requires a read-write key

`l4 auth login` mints a read-only key, which fails here with exit `1` and `permission denied`. See [CLI authentication](/cli/authentication#browser-login-mints-a-read-only-key) for how to create a read-write key.

## Output

A success line, then the new alert's id, name and source. With `--json`, the alert as the API stored it.

## Errors

| Exit | Symptom                                         | Cause                                                                                                                                        |
| ---- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `1`  | `--file is required`                            | No `--file` was passed                                                                                                                       |
| `1`  | `cannot read ...` or `... is not a JSON object` | The file is missing, or is not one JSON object                                                                                               |
| `1`  | `... is larger than 1048576 bytes`              | The file is over 1 MiB                                                                                                                       |
| `1`  | `403` permission denied                         | The key is read-only                                                                                                                         |
| `1`  | `422` with a reason                             | The API refused the rule: a source that does not fit the kind, an alert that reaches nobody, or a Slack channel the LevelFour bot cannot see |

## Related

* [`l4 alerts update`](/cli/commands/alerts/update): change an alert from a file of the fields to change
* [`l4 alerts get`](/cli/commands/alerts#get): read a rule back as JSON