# CLI Commands

## Sending events

Create an alert event from the command line:

```sh
ilagent event -k il1api123... -t ALERT -s 'a summary from the shell'
```

Additional options:

| Flag | Description                                            |
| ---- | ------------------------------------------------------ |
| `-k` | Alert source integration key (required)                |
| `-t` | Event type: `ALERT`, `ACCEPT`, or `RESOLVE` (required) |
| `-s` | Summary text (required for ALERT)                      |
| `-g` | Attach an image URL                                    |
| `-l` | Attach a link URL                                      |
| `-o` | Set priority: `HIGH` or `LOW`                          |

## Sending heartbeats

Ping a heartbeat alert source:

```sh
ilagent heartbeat -k il1hbt123...
```

## Running as a daemon

Start ilagent as a long-running process with optional HTTP server, MQTT, and Kafka consumers:

```sh
ilagent daemon -p 8977 -b il1hbt123...
```

| Flag | Description                                                   | Default      |
| ---- | ------------------------------------------------------------- | ------------ |
| `-p` | HTTP server port (server only starts when a port is provided) | *(disabled)* |
| `-b` | Heartbeat integration key for regular uptime pings            | *(disabled)* |

The daemon does not start an HTTP server by default. Provide `-p` to enable the proxy with `POST /api/events` support.

## HTTP proxy

When started with `-p`, the daemon runs a local HTTP server that accepts the same event and heartbeat payloads as the ilert API. Events are buffered in a local SQLite database and delivered asynchronously with automatic retries:

* **Idle**: polls every 5 seconds
* **Active**: polls every 500ms to drain the queue quickly
* **Failing**: exponential backoff up to 60 seconds

```sh
ilagent daemon -p 8977
```

### Endpoints

| Method | Path                    | Description                                                                     |
| ------ | ----------------------- | ------------------------------------------------------------------------------- |
| `POST` | `/api/events`           | Queue an event for delivery (same schema as `https://api.ilert.com/api/events`) |
| `GET`  | `/api/heartbeats/{key}` | Proxy a heartbeat ping                                                          |
| `GET`  | `/health`               | Health check                                                                    |
| `GET`  | `/ready`                | Readiness check                                                                 |
| `GET`  | `/`                     | Returns the ilagent version                                                     |

### Max retries

By default, events that keep failing are dropped after 100 attempts. Use `--max_retries` to change this limit:

```sh
ilagent daemon -p 8977 --max_retries 50
```

Set `--max_retries 0` for unlimited retries (events stay in the queue until they succeed).

This setting also applies to the [MQTT buffer queue](https://docs.ilert.com/developer-docs/client-libraries/mqtt#buffering-and-retries).

## Cleanup

Mass-resolve open alerts:

```sh
ilagent cleanup -k your-api-key --resource alerts
```

## Liveness probes

When the HTTP server is running (`-p`), ilagent exposes:

* `GET /health` — health check
* `GET /ready` — readiness check

We recommend also providing `-b il1hbt123...` to periodically ping a heartbeat alert source for uptime monitoring.

## Running detached

```sh
nohup sh -c 'ilagent daemon -m 192.168.1.14 -b il1hbt123... -v -v' > ./ilagent.log 2>&1 &
```