CLI Commands

Using ilagent from the command line to send events and heartbeats.

Sending events

Create an alert event from the command line:

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:

ilagent heartbeat -k il1hbt123...

Running as a daemon

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

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

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:

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.

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:

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

See Event Mapping → 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:

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

{"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

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