CLI
The smsfabric command does two things from a terminal:
smsfabric sendsends an SMS.smsfabric listenprints 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.
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/smsInstall
Section titled “Install”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.
pnpm installpnpm --filter @smsfabric/cli... buildnode packages/cli/dist/bin.js --helpThe examples on this page write smsfabric for node packages/cli/dist/bin.js.
Authentication
Section titled “Authentication”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.
Send an SMS
Section titled “Send an SMS”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.
Receive webhook events locally
Section titled “Receive webhook events locally”smsfabric listen --forward-to http://localhost:3000/hooks/sms --events message.delivered,message.failedlisten 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/smsListening 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.
Signing secret
Section titled “Signing secret”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.
Limits
Section titled “Limits”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.
Exit codes
Section titled “Exit codes”| 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. |
Environment variables
Section titled “Environment variables”| 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. |