CLI
The bloomtext command-line tool wraps the API for scripts, cron jobs, quick checks from a terminal, and AI coding agents. It covers every endpoint in the API reference, handles pagination and idempotency for you, and prints JSON on request.
Setup
Installation instructions come with your API key. Request API access if you don’t have one yet.
The CLI reads your key from the environment:
export BLOOMTEXT_API_KEY="bt_live_4f7c2a9e1b..."
bloomtext whoamiRiverside Family Clinic (6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c)
App user: Intake Bot
Scopes: conversations:read messages:read messages:writeCommands
Conversations
bloomtext conversations list
bloomtext conversations get e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0Run bloomtext <command> --help for every flag.
Global flags
| Flag | Does |
|---|---|
--json | Print raw API JSON instead of tables. Stable, and safe to parse. |
--all | Follow next_cursor and return every page. |
--limit <n> | Page size, up to 100. |
--idempotency-key <key> | Use your own key instead of a generated one. |
--quiet | Print only IDs, one per line. |
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | The API returned an error. The problem details are printed to stderr. |
2 | Invalid flags or arguments. |
3 | Authentication failed (401) or a scope is missing (403). |
4 | Rate limited after automatic retries. |
The CLI retries 429 and 503 responses with backoff, reusing the same idempotency key, before giving up.
Scripting
Combine --json with jq:
# IDs of every conversation the app user is in
bloomtext conversations list --all --json | jq -r '.data[].id'
# Send one message per line of a file (conversation_id<TAB>text)
while IFS=$'\t' read -r conversation text; do
bloomtext messages send --conversation "$conversation" --body "$text" --quiet
done < reminders.tsvUse with AI coding agents
Agents like Claude Code, Codex, and Cursor work well with the CLI because every command has a --json mode, clear exit codes, and --help text written for machines as much as people.
Add this to your repository’s AGENTS.md or CLAUDE.md so the agent knows how to use it:
## BloomText
- Use the `bloomtext` CLI to read and send BloomText messages. The key is in `BLOOMTEXT_API_KEY`; never print or commit it.
- Always pass `--json` and parse the output. Check the exit code: 0 ok, 1 API error (details on stderr), 3 auth or scope problem.
- Only post to conversations the task names. Never send patient information to any tool outside BloomText.
- Docs for agents: https://www.bloomtext.com/developers/api/llms.txtFor agents that support skills, install the BloomText API skill as well. It covers the API’s rules in more depth.
Or hand an assistant the whole reference in one go:
Read https://www.bloomtext.com/developers/api/llms-full.txt and help me use the bloomtext CLI and the BloomText API.
For agents that call tools directly rather than a shell, the MCP server is usually a better fit.