Skip to content

Swift CLI

Install the Swift CLI with Homebrew and send updates from macOS terminal workflows.

Use the Swift CLI to send Agent Alerts from terminal workflows and scripts on macOS 13 or later.

Install with Homebrew

brew tap andreasink/agent-alerts-cli https://github.com/AndreasInk/agent-alerts-cli.git
brew install andreasink/agent-alerts-cli/agentalerts
agentalerts setup

Setup opens the website pairing flow. Review the requested access, scan its QR code with Agent Alerts on iPhone, compare the code on both devices, and approve the connection.

Paste the one-time token into the CLI's hidden prompt. Store tokens only in the secret storage for the runtime that sends your updates. Do not put tokens in commands, source code, logs, or conversations. Token plaintext is shown once; if it is lost, revoke that connection and create a replacement.

Send the first example

Download funnel.json into your terminal's current folder, then run:

agentalerts send --file funnel.json --activity-id funnel

This uses the gallery's activation funnel sample, with illustrative values of 100%, 72%, 58%, and 41%. The example sends a Live Activity and notification. Check the command result and confirm what appeared on your iPhone.

Update the same activity

Use the same --activity-id for the same subject. Replace the file's content with the next observed result, then send again. Keep different workflows on different stable IDs.

Builder content files use builderSpec and data. Gallery downloads already use the Swift CLI's supported content format. The remote MCP example request beside an image may use a different request shape; do not treat it as a CLI content file.

Hooks and automation

The CLI repository includes hooks and integration instructions. Choose an event that matches the claim you want to report: an agent turn ending does not establish that a task finished or tests passed.

Keep recurring scheduling in your AI client, CI system, or scheduler. Agree on refresh cadence, escalation, and notification behavior before enabling a workflow.

For exact options and current hook setup, use the Swift CLI README. For a service running outside macOS, use the webhook API.