devotel — Orbit by Devotel developer CLI

A first-party command-line tool for scripting sends, managing numbers, and tailing real-time logs/DLRs from your terminal. Typed against the Orbit platform's /openapi.json.

Docs: https://docs.orbit.devotel.io

Install

npm install -g @devotel-orbit/cli

The package installs a single devotel binary.

5-minute first SMS

# 1. Log in with an API key (Dashboard → Developers → API keys)
devotel auth login --token dv_live_xxx

# 2. Grab a sandbox number to send from
devotel sandbox numbers

# 3. Send
devotel send sms --to +15551234567 --body "Hello from Orbit"

# 4. Watch it land in real time
devotel logs tail

Commands

| Command | Description | | ------------------ | ------------------------------------------------------ | | auth login | Store a credential (--token, --url, --profile) | | auth logout | Remove a stored credential | | auth whoami | Show the active profile (token redacted) | | send sms | Send an SMS (--to, --body, --from) | | numbers list | List provisioned phone numbers | | sandbox numbers | List sandbox numbers | | logs tail | Stream real-time request logs / DLRs (Ctrl-C to stop) | | listen | Forward live webhooks to a local URL (--forward-to) | | migrate twilio | Port a Twilio account's config into Orbit (--account-sid, --auth-token, --entities, --conversation-days, --run) | | migrate status | Check a migration job's progress (<jobId>) |

Add --json to any read command for machine-readable output.

Migrating from Twilio

devotel migrate twilio drives the same one-click-migration wizard the dashboard's Import screen uses, from your terminal or a CI pipeline. It reads config from your Twilio account (never your live traffic) and brings it onto Orbit:

# 1. Preview — always a dry run first, nothing is written yet
devotel migrate twilio --account-sid ACxxxxxxxx --auth-token your_auth_token

# 2. Happy with the preview? Commit it
devotel migrate twilio --account-sid ACxxxxxxxx --auth-token your_auth_token --run

# 3. Watch it land
devotel migrate status imp_xxxxxxxx

By default it ports phone_numbers, messaging_services, templates, and contacts — pass --entities phone_numbers,contacts to narrow it, or --conversation-days 30 to shrink the contact/message lookback window. Your Twilio Auth Token is exchanged server-side for a short-lived encrypted envelope and is never written to ~/.devotel/config.json. This migrates configuration and metadata only — it does not move live traffic; outbound voice/SMS keeps exiting through Devotel's own wholesale network both before and after you run it. See the Twilio migration guide for the full concept mapping (SMS, voice/TwiML, webhooks, Verify).

Local webhook forwarding

Build and debug webhook handlers on your machine without deploying or standing up a public tunnel. devotel listen tails your tenant's live events and POSTs each one to your local server, signed exactly like a production webhook:

devotel listen --forward-to localhost:3000/webhook

Forwarding Orbit webhooks → http://localhost:3000/webhook
Webhook signing secret: whsec_8f3c…
Listening for new events… press Ctrl-C to stop.
message.delivered  1719345600123-0 → http://localhost:3000/webhook  [200]

Each forwarded request carries an X-Devotel-Signature: t=<ts>,v1=<hmac> header. Verify it locally with the printed signing secret exactly as you would a live webhook:

import { Orbit } from "@devotel-orbit/node";

const event = Orbit.webhooks.constructEvent(
  rawBody,
  req.headers["x-devotel-signature"],
  process.env.ORBIT_WEBHOOK_SECRET, // the whsec_… printed by `devotel listen`
);

Flags:

• --forward-to <url> — local target (a bare host:port/path defaults to http://).
• --types <csv> — only forward these event types, e.g. message.delivered,message.failed.
• --secret <whsec_…> — reuse a fixed signing secret (or set $DEVOTEL_WEBHOOK_SECRET) instead of a fresh per-session one.
• --replay — also forward the events already buffered before you started, then keep tailing.

Credentials & profiles

Credentials are stored at ~/.devotel/config.json (0600), overridable via $DEVOTEL_CONFIG_HOME. Use --profile <name> (or $DEVOTEL_PROFILE) to keep separate prod / staging credentials. dv_… keys are sent as X-API-Key; session JWTs are sent as Authorization: Bearer.

Keeping types in sync

The CLI ships hand-maintained types so the published bundle has zero codegen-time dependencies. To diff them against a live spec when routes change:

DEVOTEL_OPENAPI_URL=https://api.orbit.devotel.io/openapi.json \
  pnpm --filter @devotel-orbit/cli codegen

Outbound routing

The CLI only ever calls the first-party Orbit API. Outbound SMS submitted via devotel send sms is terminated server-side through the Devotel wholesale softswitch (invariant #45) — the CLI never speaks to upstream carriers directly.

License

MIT. See LICENSE.