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 access token:

export BEEPS_ACCESS_TOKEN="bat_your_token_here"

Or use a config file:

{
  "apiKey": "bat_your_token_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.

Trust model

beeps.config.ts is executed, not parsed (the same model used by vite.config.ts, next.config.ts, etc.) — treat it as code you own. The CLI requires the path explicitly (-f / --file); there is no implicit cwd resolution. Before loading, the CLI also refuses configs that are:

• symbolic links (pass the resolved path),
• owned by a different user, or
• group- or world-writable (chmod go-w beeps.config.ts if you hit this).

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_ACCESS_TOKEN: ${{ secrets.BEEPS_ACCESS_TOKEN }}