# 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 — returns 503 during graceful shutdown, 204 otherwise                      |
| `GET`  | `/ready`                | Readiness check — returns 204 when ready, 503 with diagnostic JSON when not (see below) |
| `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](/developer-docs/client-libraries/ilagent/mqtt.md#buffering-and-retries).

## Liveness probes

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

* `GET /health` — returns **204** when healthy, **503** during graceful shutdown (after receiving SIGINT/SIGTERM)
* `GET /ready` — returns **204** when all consumers are ready, **503** with a diagnostic JSON body when not

The `/ready` response includes context about which component is not ready:

```json
{"component": "mqtt", "connected": false, "subscriptions_ready": false, "error": "..."}
```

```json
{"component": "kafka", "consumer_started": true, "subscribed": false, "worker_exited": false, "error": "..."}
```

This makes `/ready` suitable as a Kubernetes readiness probe — pods are only added to the service once their consumers are fully connected and subscribed.

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 &
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ilert.com/developer-docs/client-libraries/ilagent/cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.