CLI

The BlueBot CLI is the bluebot command. It does from a terminal what the dashboard and the API do: send a text, read your texts, check that your Mac is ready, manage webhooks and stops. Its most useful command is bluebot listen, which forwards your account’s events to a webhook handler running on your own machine, signed the same way as a real delivery, so you can build the handler without a tunnel.

Install

The package is @usebluebot/cli; the command it installs is bluebot. It needs Node 18 or newer.

npm install --global @usebluebot/cli
bluebot --version

To run it once without installing, use npx @usebluebot/cli <command>. The plain npm name bluebot belongs to somebody else, so install the scoped package.

Sign in

bluebot login

login asks for an API key and checks it with GET /v1/me. Make the key in the dashboard under Developers → API keys, named “CLI”; tick every scope to use every command, or only the ones you need (listen needs messages:read, the webhooks commands need webhooks:manage, status and whoami need account:read). The key is typed hidden and stored in your system’s keychain: the macOS Keychain, Windows Credential Manager, or the Secret Service on Linux. Where there’s no keychain, such as a container, it goes in a credentials.json file in the config folder that only you can read (mode 0600).

When your terminal shows colour, login greets you with BlueBot drawn in dots. With --json, NO_COLOR or no terminal, it prints plain text.

Use profiles for more than one account or key, such as --profile work. bluebot logout forgets a profile’s key (--all forgets every one); revoke the key itself in the dashboard.

bluebot whoami

Signed in to maria@sparkleclean.com (acct_1Hq2LxW9cVbN3mKpRtYs0a)
Key       CLI (bb_live_7Fh2…), live
Scopes    messages:send, messages:read, contacts:read, contacts:write, webhooks:manage, account:read
Profile   default

Global flags

Every command takes these.

Send a text

bluebot send +15555550123 "Your table for four is ready."

→ +1 555-555-0123  queued  msg_1Hq2LxW9cVbN3mKpRtYs0a

bluebot send <to> [text]. <to> is a phone number in any format (US numbers can leave off +1) or an email address the person uses for iMessage. Leave out the text, or write -, to read it from standard input: fortune | bluebot send +15555550123 -.

Sent texts show in blue for iMessage and green for SMS once the service is known. A text that can’t go yet prints its hold:

→ +1 555-555-0123  queued, held: quiet hours until 8:00 AM  msg_1Hq2LxW9cVbN3mKpRtYs0a

Texts from the CLI show source: "cli" in BlueBot.

Read your texts

bluebot messages
bluebot messages --direction in --since 24h
bluebot messages --follow

bluebot messages (or bluebot messages list) prints your newest texts as a table: time, direction, the person, service, state and the first words.

--follow reads your account’s event feed every two seconds, so it shows texts typed by hand on your Mac or iPhone too, as BlueBot copies them.

The other messages commands:

Check your Mac

bluebot status

Mac       online, MacBook Air (BlueBot 1.4.2, macOS 15.1), last check-in 6 seconds ago
Checks    Messages ok, Full Disk Access ok, Text Message Forwarding ok, Awake ok, FileVault ok
Today     41 sent, 6 of 50 new people, daily limit 1,000, resets at 12:00 AM
Queue     3 queued, 1 held, 0 unconfirmed
BlueBot   sending normally

status reads GET /v1/device and GET /v1/status. A check that needs you is shown in yellow with what the Mac saw and what to do. It exits 0 either way; add --json and read checks_ok to use it in a script.

Look up a number

bluebot lookup +15555550123

+1 555-555-0123  imessage (from your history, last text 2 days ago)

It reads your own Messages history through your Mac and waits up to 15 seconds. A number you’ve never texted is unknown, because Apple gives no way to ask.

Files, templates, conversations, chats, contacts, stops, settings and events

Webhooks

Listen for events on your machine

A real webhook needs a public https address. While you build the handler, listen stands in for one: it reads your account’s event feed and posts each event to a URL on your machine, http://localhost included.

bluebot listen --forward-to http://localhost:3000/bluebot/webhooks

Ready. Forwarding events to http://localhost:3000/bluebot/webhooks
Your local signing secret is whsec_c2VjcmV0LWZvci1sb2NhbC10ZXN0aW5nLW9ubHk=
Set it as BLUEBOT_WEBHOOK_SECRET in your handler. Press Ctrl-C to stop.

19:44:13  message.received   evt_7Kd3WnP9xQ2mLc5RvT8bHy  → 204 (38 ms)
19:44:31  message.sent       evt_2Mx8TqR4vB9nKd1WcY6pLs  → 204 (12 ms)
19:45:02  message.delivered  evt_9Pq4LmZ7wC3xNb6TkR1vYs  → 500 (210 ms)

How it works:

• It starts from now, or from --since, and asks GET /v1/events for new events every two seconds, which uses 30 of your key’s 120 requests a minute.
• It posts each event to --forward-to, oldest first, with the same body and the same three headers a real delivery has (webhook-id, webhook-timestamp, webhook-signature), signed with a secret that belongs to your machine. The CLI makes that secret the first time and keeps it with your key, so it stays the same between runs; set it as BLUEBOT_WEBHOOK_SECRET, and the same verification code works locally and in production.
• It prints each event and what your handler answered. It doesn’t retry: fix the handler and use --since to run the events through again.
• It reads events only. It doesn’t make a webhook in your account, and your real webhooks keep receiving events as usual.

Test events (from webhooks test) aren’t in the event feed, so listen never sees them. To try a handler on an event that hasn’t happened, run listen in one terminal and, in another, bluebot webhooks trigger message.failed --forward-to http://localhost:3000/bluebot/webhooks. Testing webhooks covers this and tunnels.

Open the docs or the dashboard

bluebot open docs opens these docs in your browser, and bluebot open dashboard opens the dashboard.

Shell completion

bluebot completion <bash|zsh|fish> prints a completion script. Add it to your shell, for example bluebot completion zsh > "${fpath[1]}/_bluebot" for zsh.

Output and scripting

In a terminal, commands print tables and short lines. With --json, they print the API’s JSON and nothing else, so you can pipe it to jq:

bluebot messages --state failed --all --json | jq -r '.[] | [.to, .failure.reason] | @tsv'

• A single record prints as the object the API returns.
• A list prints the page as the API returns it (object, data, has_more, next_cursor); with --all, an array of every item.
• listen --print-json and messages --follow --json print one JSON object per line.
• Errors go to standard error. With --json, that’s BlueBot’s error body, { "error": { … } }.

Without --json, an error prints BlueBot’s message, hint, documentation link and request id:

Error: Send `to` or `chat_id`. (invalid_request)
Hint: Check the fields named in the message and send it again.
Docs: https://usebluebot.com/docs/errors/invalid_request
Request: req_1Hq2LxW9cVbN3mKpRtYs0a

Colour, BlueBot’s face and other decoration never appear in errors or in --json output.

Exit codes

The CLI retries what is safe to retry, as the SDKs do: connection failures, 429 and 5xx answers, twice, waiting what BlueBot asks.

Settings and environment

Settings live in config.json in the config folder: $BLUEBOT_CONFIG_DIR, else $XDG_CONFIG_HOME/bluebot, else ~/.config/bluebot on macOS and Linux and %APPDATA%\bluebot on Windows. It holds each profile’s account, the start of its key and its base URL; keys and local signing secrets live in the keychain, or in credentials.json (mode 0600) where there is none.