thunderbird-cli

Low-level CLI to manage Mozilla Thunderbird email from the shell. 38 commands designed for AI agents.

Part of the thunderbird-cli project.

What it does

tb is a thin HTTP client that talks to a local Thunderbird WebExtension via a bridge daemon. It exposes 38 commands across all messenger.* APIs:

• Search & read — full-text search across accounts, batch reads, threads
• Compose — draft, open, or send (defaults to draft for safety)
• Folders — list, create, rename, delete, info, sync
• Attachments — list and download (base64 → file)
• Bulk ops — mark-read, move, delete, tag, fetch with filters
• Token-optimized — --fields, --compact, --max-body for AI use

All output is JSON wrapped in {ok, data} / {ok, error, code}.

Prerequisites

This package alone is not enough. You need:

1. Mozilla Thunderbird 128+ with email accounts configured
2. thunderbird-cli-bridge daemon running on 127.0.0.1:7700
3. The signed Thunderbird WebExtension loaded in Thunderbird

See the main repo setup guide for the full installation.

Install

npm install -g thunderbird-cli

Or use without installing:

npx thunderbird-cli health

Quick examples

tb stats                                    # account/folder counts
tb search "invoice" --since 7d              # find recent invoices
tb read 123 --headers                       # cheap headers-only read
tb compose --to "[email protected]" --body "Hi"       # save as draft
tb compose --to "[email protected]" --body "Hi" --send  # send immediately
tb attachment-download 123 1.2 --output invoice.pdf

Full reference: docs/COMMANDS.md

Configuration

| Env var | Default | |---|---| | TB_BRIDGE_HOST | 127.0.0.1 | | TB_BRIDGE_PORT | 7700 | | TB_AUTH_TOKEN | (none) |

Config file: ~/.config/thunderbird-cli/config.json

License

MIT