CLI

The beeps CLI lets you manage relays, schedules, alerts, and integrations directly from the command line — or define your entire on-call setup as code.

Installation

npm (global)

npm install -g @beepsdev/cli

npx

npx @beepsdev/cli --help

Authentication

The easiest path is the browser login flow:

beeps login

It saves an org-scoped token to ~/.config/beeps/config.json. Check your session with beeps whoami; end it with beeps logout.

For CI or scripts, set an environment variable instead:

export BEEPS_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

Or use an explicit JSON config file (must be chmod 600, owned by the current user, and not a symlink):

{
  "accessToken": "YOUR_ACCESS_TOKEN",
  "baseUrl": "https://api.beeps.dev/v0"
}

beeps relay list --config ./beeps.cli.json
# or set once via environment variable
export BEEPS_CLI_CONFIG="./beeps.cli.json"

Resolution order (highest priority first): explicit config file (--config or BEEPS_CLI_CONFIG) > BEEPS_ACCESS_TOKEN > the saved login at ~/.config/beeps/config.json.

Passing an access token on the command line is not supported — argv is visible to other local users via ps and /proc/<pid>/cmdline.

Global Options

These flags are available on every command:

Flag	Description
--base-url <url>	Custom API endpoint
--config <file>	Path to a JSON config file
--timeout <ms>	Request timeout in milliseconds (default: 10000)
--retries <count>	Number of retry attempts (default: 2)
--help	Show usage info

Most commands also accept --json for machine-readable output.

Quick Commands

See who’s on call

beeps schedule on-call --schedule-id sch_abc123

List active alerts

beeps alert list --active

Respond to an alert

beeps alert on-it --alert-id alt_abc123

Resolve an alert

beeps alert resolve --alert-id alt_abc123

List relays

beeps relay list

Simulate a relay

beeps relay simulate --relay-id rly_abc123 --simulate-at 2025-03-01T00:00:00Z

Define your setup as code

beeps relay export -o beeps.config.ts   # export current setup
beeps relay plan -f beeps.config.ts     # preview changes
beeps relay apply -f beeps.config.ts    # apply changes

Command Reference

beeps
├── alert
│   ├── list [--active] [--resolved]
│   ├── get --alert-id <id>
│   ├── on-it --alert-id <id> [--user-id <id>]
│   ├── assign --alert-id <id> --user-id <id>
│   ├── resolve --alert-id <id>
│   ├── responders --alert-id <id>
│   ├── agents --alert-id <id>
│   └── fix-context --alert-id <id>
├── relay
│   ├── list
│   ├── create --name <name> [--external-key <key>]
│   ├── lint --relay-id <id> [--coverage-days <n>]
│   ├── simulate --relay-id <id> --simulate-at <iso>
│   ├── plan -f <config>
│   ├── apply -f <config> [--prune] [--dry-run]
│   ├── export -o <file>
│   └── rule
│       ├── list --relay-id <id>
│       ├── get --relay-id <id> --rule-id <id>
│       ├── create --relay-id <id> --name <name> --rule-type <type>
│       └── delete --relay-id <id> --rule-id <id>
├── schedule
│   ├── list
│   ├── create --name <name> --relay-id <id> --type <type> ...
│   ├── on-call --schedule-id <id>
│   ├── assignments --schedule-id <id> [--count <n>]
│   ├── add-member --schedule-id <id> (--email <email> | --user-id <id>)
│   ├── remove-member --schedule-id <id> --user-id <id>
│   └── override
│       ├── create --schedule-id <id> --user-id <id> --start-at <iso> --end-at <iso>
│       ├── list --schedule-id <id>
│       ├── update --schedule-id <id> --override-id <id>
│       └── cancel --schedule-id <id> --override-id <id>
├── integration
│   ├── list
│   ├── get --integration-id <id>
│   ├── create --provider <provider> --name <name> --access-token-env <var>
│   ├── update --integration-id <id>
│   └── delete --integration-id <id>
├── webhook
│   └── list --relay-id <id>
├── agent-job
│   ├── list
│   ├── get --job-id <id>
│   └── status --job-id <id>
├── member
│   └── list
└── config
    └── lint -f <config>

Reference

• Config-as-Code — define relays, schedules, and rules in TypeScript
• Relay Commands — manage relays and rules directly
• Schedule Commands — manage schedules, members, and overrides
• Alert Commands — triage, respond to, and resolve alerts
• Integration Commands — connect AI agents and notification services

Most commands support --json for machine-readable output; all support --help for usage info.