CLI Config-as-Code

Manage relays, schedules, and relay rules idempotently with a TypeScript config file.

Install

npm install -D @beepsdev/cli

Authentication

Set your API key:

export BEEPS_API_KEY="bk_your_key_here"

Or use a config file:

{
  "apiKey": "bk_your_key_here",
  "baseUrl": "https://api.beeps.dev/v0"
}

beeps relay plan --config ./beeps.cli.json
export BEEPS_CLI_CONFIG="./beeps.cli.json"

Precedence: command flags > CLI config file > environment variables.

Create beeps.config.ts

import type { BeepsConfig } from "@beepsdev/sdk";

const config = {
  version: 1,
  relays: [
    {
      externalKey: "myco::relay::primary",
      name: "Primary",
      description: "Primary rotation",
    },
  ],
  schedules: [
    {
      externalKey: "myco::schedule::primary-weekly",
      relayExternalKey: "myco::relay::primary",
      name: "Primary Schedule",
      type: "weekly",
      handoffDay: "monday",
      handoffTime: "00:00",
      members: [{ email: "dev1@myco.com" }, { email: "dev2@myco.com" }],
    },
  ],
  relayRules: [
    {
      externalKey: "myco::rule::primary-notify",
      relayExternalKey: "myco::relay::primary",
      group: "default",
      order: 1,
      name: "Notify Primary",
      ruleType: "schedule_notify",
      enabled: true,
      config: {
        scheduleExternalKey: "myco::schedule::primary-weekly",
      },
    },
  ],
} satisfies BeepsConfig;

export default config;

Set startAt only when you want a schedule to begin in the future. If you omit it, beeps starts the schedule immediately when the config is applied.

Validate and Plan

beeps config lint -f beeps.config.ts
beeps relay plan -f beeps.config.ts

For CI:

beeps config lint -f beeps.config.ts --json
beeps relay plan -f beeps.config.ts --json

Apply Changes

beeps relay apply -f beeps.config.ts --dry-run   # preview
beeps relay apply -f beeps.config.ts              # apply

To remove relay rules that are not in the config:

beeps relay apply -f beeps.config.ts --prune

Export From Remote

beeps relay export -o beeps.config.ts

Deploy in CI

Since beeps.config.ts uses externalKey everywhere, it’s idempotent and safe to re-run.

GitHub Actions

name: Deploy beeps config

on:
  push:
    branches: [main]
    paths: [beeps.config.ts]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install @beepsdev/cli
      - run: npx beeps relay apply -f beeps.config.ts
        env:
          BEEPS_API_KEY: ${{ secrets.BEEPS_API_KEY }}