CLI

A command-line interface for API Alerts. Send events from your terminal, shell scripts, cron jobs, and CI/CD pipelines.

For AI agents and automation

export APIALERTS_API_KEY="your-api-key"
npx @apialerts/cli send --json -m "Task complete" -c agents

No install step, no config file, parseable JSON output, works in any container with Node.

Installation

brew tap apialerts/tap
brew install --cask apialerts

curl -fsSL https://apt.apialerts.com/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/apialerts.gpg
echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/apialerts.gpg] https://apt.apialerts.com stable main" | sudo tee /etc/apt/sources.list.d/apialerts.list
sudo apt update && sudo apt install apialerts

sudo rpm --import https://rpm.apialerts.com/key.gpg
sudo tee /etc/yum.repos.d/apialerts.repo <<EOF
[apialerts]
name=API Alerts
baseurl=https://rpm.apialerts.com
enabled=1
gpgcheck=1
gpgkey=https://rpm.apialerts.com/key.gpg
EOF
sudo dnf install apialerts

winget install APIAlerts.CLI

scoop bucket add apialerts https://github.com/apialerts/scoop-bucket
scoop install apialerts

# Zero install, fetched on demand
npx @apialerts/cli send -m "Deploy complete"

# Or install as a project devDependency
npm install -D @apialerts/cli
npx apialerts send -m "Deploy complete"

go install github.com/apialerts/cli@latest

sudo dpkg -i apialerts_<version>_linux_amd64.deb

Setup

You’ll need an API key from your workspace. After logging in, navigate to your workspace and open the API Keys section.

The CLI resolves the API key in this order: --key flag, APIALERTS_API_KEY env var, then the saved config at ~/.apialerts/config.json.

Interactive setup (recommended)

apialerts init

Non-interactive (CI/CD or scripts)

apialerts config --key YOUR_API_KEY

Environment variable (ephemeral runners, AI agents)

export APIALERTS_API_KEY=YOUR_API_KEY
apialerts send -m "Build complete"

Use the env var when writing to ~/.apialerts/config.json isn’t appropriate (Docker containers, sandboxed agents, ephemeral CI runners).

View your current key

apialerts config

Remove your key

apialerts config --unset

Usage

# Simple notification
apialerts send -m "Deployment successful"

# With routing (recommended for production)
apialerts send -e ci.deploy.success -m "Deployment successful"

# With all options
apialerts send \
  -e user.purchase \
  -m "$49.99 from [email protected]" \
  -t "New Sale" \
  -c payments \
  -g billing,sales \
  -l https://dashboard.example.com \
  -d '{"plan":"pro","source":"organic"}'

# With env var auth (recommended for CI / agents)
APIALERTS_API_KEY="your-api-key" apialerts send -e ci.deploy.success -m "Deployment successful"

-e (event) is optional but recommended. Routers match this value with Unix glob (fnmatch): dotted keys like ci.deploy.success match ci.*, and free-form keys like User Signup match User *. Dotted notation is just a tidy convention, not a requirement.

Flags

Machine-readable output

Pass --json on any command to switch output to a single-line JSON object. Successful sends print to stdout; errors print to stderr (and exit 1). This is intended for shell scripts, CI pipelines, and AI agents that need to parse the result.

apialerts send --json -m "Deploy complete"
# stdout: {"workspace":"Acme Corp","channel":"general","warnings":[]}

Test Connectivity

Send a test event to verify your API key and connection:

apialerts test

test also accepts --key to verify a specific key without writing it to config, and --debug for verbose output.

CI/CD Pipelines

GitHub Actions: native GitHub Actions integration for your workflows.

cURL / HTTP: send notifications from any environment with a one-liner.