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

# CLI alerts

> Manage Formo alerts from the CLI: create, update, toggle, and delete alerts that notify your team when events or users match.

The `formo alerts` command group manages project alerts. Alerts notify a webhook (including Slack, via a Slack incoming-webhook URL) when event or user filters match.

## `formo alerts list`

List alerts for the active project.

<Note>
  Requires `alerts:read` scope on your API key.
</Note>

### Options

| Option | Type | Required | Description |
| - | - | - | - |
| `--page` | `number` | ❌ | Page number, 1-indexed |
| `--size` | `number` | ❌ | Page size |

```bash theme={null}
formo alerts list --size 25
```

***

## `formo alerts get <alertId>`

Get a single alert by ID.

<Note>
  Requires `alerts:read` scope on your API key.
</Note>

```bash theme={null}
formo alerts get alert_abc123
```

***

## `formo alerts create`

Create a new project alert.

<Note>
  Requires `alerts:write` scope on your API key.
</Note>

### Options

| Option | Type | Required | Description |
| - | - | - | - |
| `--name` | `string` | ✅ | Alert name |
| `--trigger-type` | `enum` | ✅ | Trigger type: `event` or `user` |
| `--trigger-filters` | `string` | ❌ | JSON array of trigger filter objects |
| `--recipient` | `string` | ❌ | JSON array of recipient objects |
| `--secret` | `string` | ❌ | Webhook secret for the alert |
| `--slack-property-keys` | `string` | ❌ | JSON array of event/user property keys to include in Slack alerts |

### Recipient Shape

`--recipient` is a JSON array. Only `type: "webhook"` is currently delivered to; use a `hooks.slack.com` URL as the `value` to post to Slack. `email`/`slack` type values are accepted by the schema but not delivered; use `webhook` instead.

```json theme={null}
[
  { "type": "webhook", "value": ["https://example.com/formo-webhook"] }
]
```

### Examples

```bash theme={null}
formo alerts create --name "High value tx" --trigger-type event

formo alerts create \
  --name "Whale activity" \
  --trigger-type user \
  --trigger-filters '[{"field":"net_worth_usd","op":"gt","value":"100000"}]' \
  --recipient '[{"type":"webhook","value":["https://example.com/formo-webhook"]}]'

formo alerts create \
  --name "Slack revenue alert" \
  --trigger-type user \
  --trigger-filters '[{"field":"revenue","op":"gt","value":"","numericThreshold":"1000"}]' \
  --recipient '[{"type":"webhook","value":["https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"]}]' \
  --slack-property-keys '["event","revenue","address"]'
```

***

## `formo alerts update <alertId>`

Update an existing alert.

<Note>
  Requires `alerts:write` scope on your API key.
</Note>

The API expects the full alert configuration, so provide the required alert fields again when updating.

### Options

| Option | Type | Required | Description |
| - | - | - | - |
| `--name` | `string` | ✅ | Alert name |
| `--trigger-type` | `enum` | ✅ | Trigger type: `event` or `user` |
| `--trigger-filters` | `string` | ❌ | JSON array of trigger filter objects |
| `--recipient` | `string` | ❌ | JSON array of recipient objects |
| `--secret` | `string` | ❌ | Webhook secret for the alert |
| `--slack-property-keys` | `string` | ❌ | JSON array of event/user property keys to include in Slack alerts |

```bash theme={null}
formo alerts update alert_abc123 \
  --name "Renamed alert" \
  --trigger-type event \
  --recipient '[{"type":"webhook","value":["https://example.com/formo-webhook"]}]'
```

***

## `formo alerts toggle <alertId>`

Toggle an alert status.

<Note>
  Requires `alerts:write` scope on your API key.
</Note>

| Option | Type | Required | Description |
| - | - | - | - |
| `--status` | `enum` | ✅ | New status: `active` or `inactive`. `paused` is accepted as a deprecated alias for `inactive`. |

```bash theme={null}
formo alerts toggle alert_abc123 --status inactive
formo alerts toggle alert_abc123 --status active
```

***

## `formo alerts delete <alertId>`

Delete an alert.

<Note>
  Requires `alerts:write` scope on your API key.
</Note>

```bash theme={null}
formo alerts delete alert_abc123
```

<Warning>
  Deleting an alert is permanent.
</Warning>


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