Skip to content

CLI

The smsfabric command does two things from a terminal:

  • smsfabric send sends an SMS.
  • smsfabric listen prints your webhook events as they happen and posts them to a server on your machine. You don’t need a public URL or a tunnel.
Terminal window
export SMSFABRIC_API_KEY="sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
smsfabric send --to +201001234567 --body "Your order is out for delivery."
smsfabric listen --forward-to http://localhost:3000/hooks/sms

The CLI is not on npm yet. Build it from the SMSFabric repository, then run the built file. You need Node.js 20 or later and pnpm.

Terminal window
pnpm install
pnpm --filter @smsfabric/cli... build
node packages/cli/dist/bin.js --help

The examples on this page write smsfabric for node packages/cli/dist/bin.js.

The CLI reads the API key from SMSFABRIC_API_KEY and from nowhere else. There is no --api-key option, so the key never ends up in your shell history or the process list.

With a test key (sf_test_…), every message goes to the virtual device: you get the full API and real events, and no SMS leaves a phone. See Sandbox.

Terminal window
smsfabric send --to +201001234567 --body "Your code is 4821"

The CLI prints one line per message, with its id, status and recipient:

msg_k2v8x0q4n1 queued +201001234567
Option Meaning
--to <number> Recipient in E.164. Repeat it for up to 100 recipients.
--body <text> The message text.
--device <id> Send from this phone (dev_…).
--sim <id> Send from this SIM (sim_…).
--pool <id> Send through this pool (pool_…).
--at <time> Schedule the message for an ISO 8601 time, such as 2026-12-01T09:00:00Z.
--idempotency-key <key> Use the same key to retry without sending twice. Without it, each run gets a new key. See Idempotency.
--json Print the API response as JSON.
--base-url <url> The API address. Default: SMSFABRIC_BASE_URL, then https://api.smsfabric.com.

The key needs the messages:send scope.

Terminal window
smsfabric listen --forward-to http://localhost:3000/hooks/sms --events message.delivered,message.failed

listen prints each webhook event of your organization as it happens. With --forward-to, it also posts each event to your server, with the same body and the same SMSFabric-Signature and SMSFabric-Event-Id headers a real webhook has. Your handler’s signature check works unchanged.

Signing secret for this run: whsec_…
Forwarding to http://localhost:3000/hooks/sms
Listening for message.delivered, message.failed. Press Ctrl+C to stop.
12:00:04 message.delivered evt_x1c9… -> 204 (12 ms)
Option Meaning
--forward-to <url> Where to post events. It must be on this machine unless you add --allow-remote.
--events <list> Comma-separated event types. Default: every event.
--allow-remote Allow a forward address on another machine. Events can contain message text, so use it only for a server you trust.
--json Print each event’s full JSON body on stdout, for piping into jq. Status lines go to stderr.
--base-url <url> The API address.

The key needs the webhooks:manage scope.

Set SMSFABRIC_WEBHOOK_SECRET to the secret your app verifies with, and listen signs with it. Without it, listen makes a secret for the run and prints it once: give that value to your app.

listen is for development.

  • Events that happen while it is not connected are not replayed.
  • A forward that fails is reported and not retried.
  • An organization can have 5 listeners connected at once.

For production, register an endpoint. It gets retries for about 24 hours and a delivery log.

Code Meaning
0 Done. For send, every message was accepted.
1 The API refused the request, the network failed, or a recipient was blocked.
2 The command was typed wrong, or SMSFABRIC_API_KEY is not set.
Variable Meaning
SMSFABRIC_API_KEY Required. sf_test_… or sf_live_….
SMSFABRIC_BASE_URL The API address. It must be https, except for localhost.
SMSFABRIC_WEBHOOK_SECRET The secret listen signs forwarded events with.