# CLI

> Use the bloomtext command-line tool to read and send BloomText messages from scripts, cron jobs, and AI coding agents.

Source: https://www.bloomtext.com/developers/api/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](https://www.bloomtext.com/developers/api/reference/), handles pagination and idempotency for you, and prints JSON on request.

## Setup

Installation instructions come with your API key. [Request API access](https://calendly.com/tyler-bloom/bloomtext-homepage-demo-request?utm_campaign=api-access) if you don't have one yet.

The CLI reads your key from the environment:

```bash filename="Terminal"
export BLOOMTEXT_API_KEY="bt_live_4f7c2a9e1b..."
bloomtext whoami
```

```text filename="Output"
Riverside Family Clinic (6db1e3f5-9b7f-4f2b-8be1-0f1e1d7d7d8c)
App user: Intake Bot
Scopes: conversations:read messages:read messages:write
```

## Commands

```bash
bloomtext conversations list
bloomtext conversations get e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0
```

```bash
# Latest 20 messages
bloomtext messages list --conversation e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0 --limit 20

# Send a message
bloomtext messages send \
  --conversation e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0 \
  --body "Your appointment is confirmed for Tuesday at 10:00."

# Reply in a thread
bloomtext messages send --conversation e5c3b7b8-... --reply-to 4cbfdb50-... --body "Done ✅"

# Read a thread
bloomtext messages replies 4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1
```

```bash
bloomtext reactions add 4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1 --emoji 👍
bloomtext reactions remove 4cbfdb50-6b7d-45d4-94b3-05a52ce3f4d1 --emoji 👍
```

```bash
bloomtext participants list --conversation e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0
bloomtext participants add --conversation e5c3b7b8-... --user 8b9c2d2f-6b1a-44f4-a7b1-0d6d3f2d6f55
bloomtext participants remove --conversation e5c3b7b8-... --user 8b9c2d2f-...
```

```bash
# Start an export and wait for the download URL
bloomtext exports create --conversation e5c3b7b8-8f08-4d5a-9af1-0d11b0f4b7a0 \
  --projection messages --from 2026-09-01 --to 2026-09-30 --wait
```

Run `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](https://www.bloomtext.com/developers/api/errors/) 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`:

```bash filename="Terminal"
# 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.tsv
```

## Use 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:

```md filename="AGENTS.md"
## 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.txt
```

For agents that support skills, install the [BloomText API skill](https://www.bloomtext.com/developers/api/mcp/#agent-skill) as well. It covers the API's rules in more depth.

Or hand an assistant the whole reference in one go:

**Learn the BloomText API:**

```text
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](https://www.bloomtext.com/developers/api/mcp/) is usually a better fit.