> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/developer-docs/client-libraries/ilagent/cli.md).

# 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`). A `severity` outside the `1`–`5` range is rejected with HTTP 400 |
| `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).

### Enriching proxied events

The static enrichment flags `--label`, `--severity`, and `--service` apply to a plain HTTP daemon as well, stamping every event received via `POST /api/events`:

```sh
ilagent daemon -p 8977 --label env=prod --severity 3 --service alias=web-frontend
```

See [Event Mapping → Enriching events](/developer-docs/client-libraries/ilagent/event-mapping.md#enriching-events) for the full set of label, severity, routing key, and service flags.

## 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.