# atbridge — CLI reference

> Every atbridge CLI command and flag, in plain text for AI agents and scripts.
> JSON in, JSON out; the same operations as MCP. Generated from the live command
> tree, so it never drifts. Companion: llms-mcp.txt (the same ops as MCP tools).

Usage: atbridge <command> [subcommand] [flags]

# atbridge bridge — Bridge (Thunderbird native-messaging) control + diagnostics

## atbridge bridge accounts
List Thunderbird accounts and identities (for use with mail send --identity)
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge bridge install
Install the native-messaging host so Thunderbird launches atbridge
Flags:
  --all-permissions-allowed bool   TEST BUILDS ONLY (FR-PERM-05): write the host wrapper with the permission-gate bypass so e2e/int suites work; refused on prod builds
  --force bool   Regenerate the auth token + overwrite the manifest

## atbridge bridge pair
Show the loopback token to paste into the extension (Snap/Flatpak fallback)
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge bridge ping
Round-trip ping through the bridge to the TB extension

# atbridge bridge service — Manage the standalone bridge service (loopback fallback for Snap/Flatpak Thunderbird)

## atbridge bridge service install
Write the systemd --user unit for the standalone bridge host

## atbridge bridge service start
Enable + start the bridge service now (systemctl --user enable --now)

## atbridge bridge service status
Show whether the bridge service is installed + active

## atbridge bridge status
Show bridge state and live health
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge bridge tb-check
Check that Thunderbird's offline-storage settings work for atbridge search
Flags:
  --email string   Email address to check; defaults to the activated license's bound email
  --pretty bool   human-readable output (default: JSON)

# atbridge calendar — Calendar commands (events + cross-calendar clash detection)

## atbridge calendar clash
Check whether a proposed time window clashes with any calendar
Flags:
  --end string   Proposed end, ISO 8601
  --pretty bool   human-readable output (default: JSON)
  --start string   Proposed start, ISO 8601

# atbridge calendar events — Calendar event commands

## atbridge calendar events create
Create an event (recurring with --recur). Warns on cross-calendar clashes unless --force.
Flags:
  --all-day bool   Mark as an all-day event
  --attach stringArray   Attach a local file (repeatable)
  --attach-url stringArray   Attach a URL/link (repeatable)
  --attendee stringArray   Invitee email (repeatable; `email` or `email:optional`)
  --cal string   Calendar id (see `atbridge calendar list`)
  --category stringArray   Category (repeatable)
  --count int   Number of occurrences (alternative to --until) (default 0)
  --desc string   Description
  --end string   End, ISO 8601
  --force bool   Create even if it clashes with existing events
  --location string   Location
  --privacy string   public | private | confidential
  --recur string   RRULE body for a recurring series (e.g. FREQ=WEEKLY;BYDAY=MO)
  --reminder stringArray   Reminder: 15m|2h|1d (before start), end:30m, or at:<ISO> (repeatable)
  --send-invites bool   Email iTIP invitations to the attendees
  --start string   Start, ISO 8601
  --title string   Event title
  --until string   Recurrence end (ISO 8601)

## atbridge calendar events delete
Delete an event by id (--scope this removes just one occurrence of a series)
Flags:
  --on string   Occurrence start, ISO 8601 — required with --scope this
  --scope string   this | all (default all) — which occurrences to delete

## atbridge calendar events rsvp
Respond to an invite (accepted | declined | tentative)
Flags:
  --email string   Which attendee is you (if ambiguous)
  --response string   accepted | declined | tentative

## atbridge calendar events search
Search events in a time window (across all calendars by default)
Flags:
  --cal string   Restrict to one calendar id (default: all)
  --count bool   Print only {total, approx} — the event count in the window
  --from string   Start of window, ISO 8601 (e.g. 2026-06-10T00:00:00Z)
  --limit int   Max events (0 = all in the window) (default 0)
  --offset int   Skip the first N events (pagination) (default 0)
  --pretty bool   human-readable output (default: JSON)
  --query string   Free-text filter on title/location/description
  --to string   End of window, ISO 8601
  --verbose bool   Include description, attendees + reminders per event in JSON (default: lean; use `calendar events show` for full detail)

## atbridge calendar events show
Show one event
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge calendar events update
Update an event (recurrence via --recur; --scope this edits one occurrence). Re-checks clashes unless --force.
Flags:
  --all-day bool   Mark as an all-day event
  --attach stringArray   Attach a local file (repeatable; pass none to clear)
  --attach-url stringArray   Attach a URL/link (repeatable)
  --attendee stringArray   Replace attendees (repeatable; `email` or `email:optional`; pass none to clear)
  --category stringArray   Category (repeatable; pass none to clear)
  --count int   Number of occurrences (with --recur) (default 0)
  --desc string   Description
  --end string   End, ISO 8601
  --force bool   Update even if the new time clashes
  --location string   Location
  --on string   Occurrence start, ISO 8601 — required with --scope this
  --privacy string   public | private | confidential (empty to clear)
  --recur string   Recurrence rule, e.g. `FREQ=WEEKLY;BYDAY=MO` (empty to clear)
  --reminder stringArray   Reminder: 15m|2h|1d, end:30m, or at:<ISO> (repeatable; pass none to clear)
  --scope string   this | following | all (default all) — which occurrences to edit
  --send-invites bool   Email iTIP updates to the attendees
  --start string   Start, ISO 8601
  --title string   Event title
  --until string   Recurrence end, ISO 8601 (with --recur)

## atbridge calendar freebusy
Find free time slots in a window (honours existing events + working hours)
Flags:
  --cal string   Restrict busy lookup to one calendar id (default: all)
  --duration string   Minimum opening length (e.g. 30m, 1h) (default 30m)
  --from string   Window start, ISO 8601
  --limit int   Max slots to return (default 20)
  --to string   Window end, ISO 8601
  --working-hours string   Daily window in local time, e.g. 09:00-18:00 (default: none)

## atbridge calendar list
List configured calendars
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge calendar refresh
Trigger a calendar re-sync now (all calendars, or one via --cal)
Flags:
  --cal string   Refresh only this calendar id (see atbridge calendar list)

## atbridge calendar settings
Show Thunderbird's calendar settings (working hours, days, timezone)

## atbridge check
Check whether a newer atbridge core/extension is available

# atbridge compose — @bridge Branded Email — render a structured block spec to a branded email

## atbridge compose render
Render a Compose spec (--spec) to a branded email and draft/send it
Flags:
  --attach string   Comma-separated attachment file paths (regular attachments, alongside the branded body). FR-COMPOSE-14/15.
  --charts bool   Preview mode: rasterise chart blocks (extension delegate) instead of the placeholder
  --from string   Sender email address (which logged-in account sends) — REQUIRED for draft/review/send
  --identity string   Deprecated alias for --from (accepts an email or a Thunderbird identity id)
  --mode string   draft (default, saves to Drafts) | review (opens the compose window to read+send) | send — overrides the spec
  --spec string   Path to a JSON spec { to, subject, blocks, images?, theme?, mode? }

# atbridge compose templates — List/show/save/delete @bridge Branded Email templates

## atbridge compose templates delete
Delete one of your saved templates

## atbridge compose templates list
List the available templates (shipped starters + your saved ones)
Flags:
  --lang string   UI language for builtin descriptions (en, es; BCP-47 tags resolve to base)

## atbridge compose templates save
Save an @bridge-composed email as a reusable template (Pro/Enterprise)
Flags:
  --description string   Optional one-line description
  --from-last bool   Save the email you most recently composed
  --spec string   Save a spec file as a template (alternative to --from-last)

## atbridge compose templates show
Print a template's spec as JSON (shipped or saved; fill in, then `compose render --spec`)

# atbridge compose theme — Get/set the saved @bridge Branded Email theme (brand colors + fonts)

## atbridge compose theme get
Print the default, saved override, and effective theme as JSON

## atbridge compose theme reset
Clear the saved theme (back to the atbridge default)

## atbridge compose theme set
Save a theme override read as JSON ({colors,fonts}) from stdin

# atbridge connect — @bridge Connect — LLM access from inside Thunderbird (Personal: capped; Pro: unlimited)

## atbridge connect activate
Activate @bridge Connect on this device
Generates a fresh per-device key, encrypts your LLM API key under it,
asks the backend to wrap the device key with the current server master,
and writes both files to ~/.atbridge/.

Use --key-stdin to pipe the API key in (preferred for scripts and CI;
keys passed via --key end up in your shell history).

Supported providers: anthropic, antigravity-cli, claude-cli, codex-cli, deepseek, gemini, groq, kimi, mistral, nvidia, ollama, openai, openai-compatible, openrouter, xai.
The `openai-compatible` preset is the escape hatch for any
provider that speaks the OpenAI chat-completions shape but isn't in
the list — pass --base-url with the API root.
Flags:
  --also-base-url string   base URL for --also-provider=openai-compatible
  --also-key string   API key for --also-provider (no stdin variant — use two activate calls if both keys are secret)
  --also-provider string   second provider to configure in the same call
  --base-url string   API base URL — required for --provider=openai-compatible, optional override for any other provider (e.g. ollama on a non-default port)
  --key string   API key for --provider (prefer --key-stdin)
  --key-stdin bool   read the API key from stdin (one line)
  --pretty bool   human-readable output (default: JSON)
  --provider string   primary provider (one of: anthropic, antigravity-cli, claude-cli, codex-cli, deepseek, gemini, groq, kimi, mistral, nvidia, ollama, openai, openai-compatible, openrouter, xai)

## atbridge connect chat
Run one turn of a multi-turn Connect conversation (reads JSON on stdin)
Reads a JSON envelope on stdin:

  {"provider":"openai","model":"gpt-4o-mini","messages":[
     {"role":"user","content":"..."},
     {"role":"assistant","content":"..."},
     {"role":"user","content":"..."}]}

and returns the assistant's next reply. The conversation pane keeps the
transcript locally and sends the recent history each turn (this call is
stateless server-side). --provider / --model override the envelope.
Needs the connect connector (Personal/Pro/Free-trial); general chat is
unmetered. Same secure-storage flow as `connect invoke`.
Flags:
  --model string   override model from the stdin envelope
  --pretty bool   human-readable output (default: JSON)
  --provider string   override provider from the stdin envelope

## atbridge connect deactivate
Tear down Connect on this device (server + local files)
Calls POST /api/connect/deactivate (removes the per-device wrap row
server-side) and deletes the local connect-keys.enc + connect-wrapped.bin
files. --keep-local skips the local delete so a re-subscription can
seamlessly resume by re-running activate.

Idempotent: deactivating an already-clean device returns ok with
had_state: false. Safe to call after a subscription cancellation —
local files staying around (without --keep-local) is fine, they're
useless without server cooperation.
Flags:
  --keep-local bool   keep local connect-*.enc/bin files (server-side teardown only)
  --pretty bool   human-readable output (default: JSON)
  --provider string   remove ONLY this provider's stored key locally (keeps the others + the device wrap; no server teardown)

## atbridge connect invoke
Run one Connect call (rate-limit → unwrap → decrypt → LLM)
Performs the full Connect round-trip end-to-end:
  1. Local rate-limit gate (10/min/device)
  2. POST /api/connect/unwrap-key
  3. AES-GCM decrypt connect-keys.enc
  4. Build prompt from --action + context
  5. Call OpenAI / Anthropic with the user's own API key
  6. Wipe device key + API key from memory

The result is printed as JSON (default) or pretty KV (--pretty).
Used by the bridge HTTP handler in slice 9 to fulfil `connect.invoke` calls.
Flags:
  --action string   improve|summarise|custom (required)
  --custom-prompt string   free-text instruction (required when --action=custom)
  --draft-body string   current compose draft body (optional)
  --draft-body-stdin bool   read the draft body from stdin instead of --draft-body
  --draft-subject string   current compose draft subject (optional)
  --invoke-stdin bool   read the full invoke envelope (action/provider/model/custom_prompt/context) as one JSON blob on stdin. Overrides every other flag except --pretty. Used by the TB bridge host so long draft/thread bodies aren't constrained by Windows' 32k command-line cap.
  --model string   model id (e.g. gpt-4o-mini, claude-haiku-4-5-20251001)
  --pretty bool   human-readable output (default: JSON)
  --provider string   openai|anthropic (required)
  --thread string   preceding-thread excerpt for the reply context (optional)

## atbridge connect status
Show whether Connect is active on this device
Reports the local file state (do connect-keys.enc + connect-wrapped.bin
exist?) and the licence-side connector entitlement. Does NOT call the
backend — that's a side effect of every invoke.
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge connect test
On-demand connectivity check for saved providers (lists models + pings them)
Probes the providers whose keys are stored on THIS device: fetches each
one's live model catalog and pings a model with a tiny completion, reporting
PASS/FAIL + latency + the exact error.

DIAGNOSTIC ONLY — spends real tokens, needs live keys, never auto-run.

  atbridge connect test                          # every configured provider, default model
  atbridge connect test --provider gemini        # one provider
  atbridge connect test --provider openai --models gpt-4o-mini,gpt-4o
  atbridge connect test --curated                # FR-CONNECT-11 contract test:
                                                 #   every curated model + a tool
                                                 #   round-trip; non-zero on any fail
  atbridge connect test --pretty
Flags:
  --curated bool   FR-CONNECT-11 contract test: ping EVERY curated model + a live tool round-trip; exit non-zero if any fail
  --models string   comma-list of models to ping (default: the provider's default model)
  --pretty bool   human-readable output (default: JSON)
  --provider string   limit to one provider (default: all configured)

# atbridge contacts — Contact commands (read + manage: list, search, show, books, create, update, delete)

## atbridge contacts books
List address books (for `contacts create --book`)
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge contacts create
Create a contact (full TB fields via --email/--phone/--address/--org/--photo/…)
Flags:
  --address stringArray   Postal address `[type:]street;city;state;zip;country` (repeatable)
  --birthday string   Birthday (YYYY-MM-DD)
  --book string   Address book ID (see `contacts books`)
  --department string   Department
  --email stringArray   Email (repeatable; `type:addr` e.g. work:a@x.com)
  --first string   FirstName
  --last string   LastName
  --middle string   Middle name
  --name string   DisplayName
  --nickname string   Nickname
  --note string   Note
  --org string   Organization / company
  --phone stringArray   Phone (repeatable; `type:number` e.g. cell:+15551234)
  --photo string   Photo: a local image file
  --prefix string   Name prefix (e.g. Dr.)
  --prop stringArray   Additional raw properties as key=value; repeatable. Example: --prop Custom1=VIP
  --suffix string   Name suffix (e.g. Jr.)
  --title string   Job title
  --url stringArray   Web page URL (repeatable)

## atbridge contacts delete
Delete a contact by card ID

## atbridge contacts list
List contacts
Flags:
  --count bool   Print only {total, approx} — the total contact count
  --limit int   Max results (default 20)
  --offset int   Skip the first N (pagination) (default 0)
  --pretty bool   human-readable output (default: JSON)
  --verbose bool   Include the full parsed vCard + props per contact in JSON (default: lean — id, name, emails; use `contacts show` for full detail)

## atbridge contacts list-add
Add a contact (card id) to a mailing list
Flags:
  --contact string   Contact card ID (see `contacts search`)
  --list string   Mailing list ID or name

## atbridge contacts list-create
Create a mailing list / group in an address book
Flags:
  --book string   Address book ID (see `contacts books`)
  --desc string   Description (optional)
  --name string   List name (used to address it in `to`)
  --nick string   Alias for --nick-name
  --nick-name string   Nickname (optional); MCP field: nick_name

## atbridge contacts list-delete
Delete a mailing list (members' contact cards are kept)

## atbridge contacts list-members
List the members of a mailing list
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge contacts list-remove
Remove a contact (card id) from a mailing list
Flags:
  --contact string   Contact card ID (see `contacts search`)
  --list string   Mailing list ID or name

## atbridge contacts lists
List mailing lists / groups (optionally within one book)
Flags:
  --book string   Only lists in this address book ID
  --pretty bool   human-readable output (default: JSON)

## atbridge contacts search
Search contacts across all fields (name, emails, phone, org, title, address, note); omit the query to list all
Flags:
  --count bool   Print only {total, approx} — the total matching
  --limit int   Max results (default 20)
  --offset int   Skip the first N matches (pagination) (default 0)
  --pretty bool   human-readable output (default: JSON)
  --verbose bool   Include the full parsed vCard + props per contact in JSON (default: lean — id, name, emails; use `contacts show` for full detail)

## atbridge contacts show
Show contact details
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge contacts update
Update a contact. Rich flags (--phone/--address/--photo/…) rewrite the card as a vCard.
Flags:
  --address stringArray   Postal address `[type:]street;city;state;zip;country` (repeatable)
  --birthday string   Birthday (YYYY-MM-DD)
  --department string   Department
  --email stringArray   Email (repeatable; `type:addr` e.g. work:a@x.com)
  --first string   FirstName (empty → clear)
  --last string   LastName (empty → clear)
  --middle string   Middle name
  --name string   DisplayName (empty → clear)
  --nickname string   Nickname
  --note string   Note
  --org string   Organization / company
  --phone stringArray   Phone (repeatable; `type:number` e.g. cell:+15551234)
  --photo string   Photo: a local image file
  --prefix string   Name prefix (e.g. Dr.)
  --prop stringArray   Property assignments (key=value); use empty value to clear. Repeatable.
  --suffix string   Name suffix (e.g. Jr.)
  --title string   Job title
  --url stringArray   Web page URL (repeatable)

# atbridge license — License + subscription management

## atbridge license activate
Activate a license on this device
Activate a license on this device. With no flags, walks your Thunderbird
identities and picks the matching license automatically — the agent-
friendly default. `--email` + `--key` skip the
auto-detect path and run an explicit verify. `--auto` forces
auto-detect even when `--email` is supplied (use the email as
the picker disambiguator when multiple licenses match).

Auto-detect requires the bridge to be reachable (Thunderbird running
with the atbridge extension loaded). Run `atbridge bridge install`
via the Node CLI on a fresh box; the Go binary doesn't own the bridge
manifest yet.

Storage-preflight errors (e.g. offline storage disabled for the bound
email) cause exit code 2 — same as the Node CLI — so wrapping scripts
can branch on activation-with-warnings vs activation-blocked.
Flags:
  --auto bool   Force the auto-detect path even if --email is supplied
  --email string   Email the license was purchased with (explicit mode, or auto-picker disambiguator)
  --key string   License key, ATBR-XXXX-XXXX-XXXX-XXXX (explicit mode)
  --pretty bool   human-readable output (default: JSON)

## atbridge license billing
Subscription view + Stripe Billing Portal access
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge license billing portal
Get a Stripe Customer Portal URL to manage billing
Flags:
  --open bool   Open the portal URL in your browser (Windows: `start`, mac: `open`, linux: `xdg-open`)
  --pretty bool   human-readable output (default: JSON)

## atbridge license billing status
Show subscription status, plan, billing-cohort, and renewal date
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge license consent
Show (or accept) the privacy disclosure for contacting atbridge.ai
Flags:
  --accept bool   Record acceptance without prompting

# atbridge license devices — List + manage this license's activated devices

## atbridge license devices deactivate
Deactivate a device by its device_id (yours or a peer's). Use `devices list` to find ids.
Flags:
  --id string   device_id from `atbridge license devices list`

## atbridge license devices list
List every device activated on your license (any device — not just this one)
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge license refresh
Force a fresh /license/verify against the server
Mirror of node-cli's `atbridge license refresh`. Runs the
same /api/license/verify roundtrip as `license status --refresh`
but with no entitlement printout — useful in scripts where you only
care about the success/failure exit code.

Slice-2 caveat: this Go build does NOT yet flush pending local usage to
the server (the node-cli version does, via /api/usage/sync). Run the
node-cli refresh if you have unsynced ops you care about.

## atbridge license start-trial
Start a free trial — emails a code, then mints + activates a free license
Start a free trial in two steps:

  atbridge license start-trial --email you@example.com           # emails a code
  atbridge license start-trial --email you@example.com --code 123456   # activates

Phase 2 verifies the minted key and writes license.json, exactly like
`license activate`.
Flags:
  --code string   The 6-digit code from your email (second step)
  --email string   Your email — the trial code is sent here
  --newsletter bool   opt in to occasional product-news email (default: off)
  --pretty bool   human-readable output (default: JSON)

## atbridge license status
Show the cached license + entitlement on this device
Reads ~/.atbridge/license.json (or $ATBRIDGE_CACHE_DIR/license.json) and
prints the cached entitlement. `--refresh` performs a fresh
/api/license/verify roundtrip and persists the result before rendering.

`--pretty` switches the output from JSON (default) to a
human-readable KV table.
Flags:
  --pretty bool   human-readable output (default: JSON)
  --refresh bool   force a fresh verify against the server before printing

# atbridge mail — Mail commands (read + manage: folders, search, list, show, thread, move, delete, mark)

## atbridge mail attachment-save
Save one (--index) or all (--all) attachments to a directory (--out)
Flags:
  --all bool   Save every attachment
  --index int   0-based attachment index to save (default 0) (default 0)
  --out string   Output directory (required)

## atbridge mail attachments
List a message's attachments (index, filename, type, size)
Flags:
  --pretty bool   human-readable output (default: JSON)

## atbridge mail delete
Trash a message (or many via --ids / selector); --hard to skip trash
Flags:
  --account string   Bulk selector: restrict to an account — EXACT full email or account id (FR-IDENT-02, no substring)
  --folder string   Bulk selector: restrict to a folder
  --hard bool   Permanently delete (skip trash)
  --ids string   Bulk: comma-separated message ids
  --max int   Bulk: max messages affected (safety cap) (default 100)
  --query string   Bulk selector: full-text query

## atbridge mail draft
Compose a draft (alias for `mail send --draft`)
Flags:
  --attach string   Comma-separated attachment file paths
  --bare-markdown bool   Skip the default markdown stylesheet
  --bcc string   Comma-separated BCC
  --cc string   Comma-separated CC
  --dsn bool   Request a delivery status notification
  --from string   Sender email address (which logged-in account sends) — REQUIRED
  --header stringArray   Custom header `X-Name: value` or `X-Name=value` (repeatable; TB requires X- names)
  --html string   HTML body (inline value)
  --html-file string   HTML body, read from a file
  --identity string   Deprecated alias for --from (accepts an email or a Thunderbird identity id)
  --inline-image stringArray   Inline image for the HTML body: PATH or CID=PATH (repeatable). Reference it in HTML as <img src="cid:CID">; CID defaults to the filename without extension. Embeds as multipart/related (renders inline in Gmail/Outlook), not a dangling attachment. FR-COMPOSE-14.
  --md string   Markdown body (inline value)
  --md-file string   Markdown body, read from a file
  --mjml string   MJML body (inline value)
  --mjml-file string   MJML body, read from a file
  --no-inline-css bool   Disable CSS inlining (default: on)
  --no-signature bool   Suppress the identity's TB signature
  --priority string   Message priority: lowest | low | normal | high | highest
  --receipt bool   Request a read receipt (return receipt)
  --reply-to string   Comma-separated Reply-To addresses
  --subject string   Subject line
  --text string   Plain-text body (inline value)
  --text-file string   Plain-text body, read from a file
  --to string   Comma-separated recipients (required)

## atbridge mail edit-draft
Edit an existing draft — only the fields you pass change; the rest are kept
Flags:
  --bcc string   Replace BCC (comma-separated)
  --cc string   Replace CC (comma-separated)
  --html string   Replace the body with HTML
  --html-file string   Replace the body with HTML from a file
  --subject string   New subject
  --text string   Replace the body with plain text
  --text-file string   Replace the body with plain text from a file
  --to string   Replace recipients (comma-separated)

## atbridge mail empty-trash
Permanently delete everything in an account's Trash
Flags:
  --account string   Account: EXACT full email or account id (FR-IDENT-02, no substring)
  --max int   Max messages to delete (default 100)

## atbridge mail fetch
Trigger Thunderbird's Get Messages (new-mail check) now
Flags:
  --account-key string   Poll only the account with this key (default: all accounts)

## atbridge mail folder-create
Create a mail folder (nested "Parent/Child" supported)
Flags:
  --account string   Account: EXACT full email or account id (FR-IDENT-02, no substring)
  --name string   Folder name; use "Parent/Child" to nest

## atbridge mail folder-delete
Delete a mail folder (special-use folders are protected)
Flags:
  --account string   Account: EXACT full email or account id (FR-IDENT-02, no substring)
  --path string   Folder path to delete

## atbridge mail folder-rename
Rename a mail folder
Flags:
  --account string   Account: EXACT full email or account id (FR-IDENT-02, no substring)
  --name string   New folder name
  --path string   Current folder path (e.g. INBOX/Old or Receipts)

## atbridge mail folders
List indexed folders with message counts
Flags:
  --account string   Restrict to one account — substring of its name/email/id (reads are lenient; writes need an EXACT account, FR-IDENT-02). Env: ATBRIDGE_DEFAULT_ACCOUNT
  --pretty bool   human-readable output (default: JSON)

## atbridge mail forward
Forward a message
Flags:
  --attach string   Comma-separated attachment file paths
  --bare-markdown bool   Skip the default markdown stylesheet
  --bcc string   Comma-separated BCC
  --cc string   Comma-separated CC
  --draft bool   Save as a draft instead of sending
  --dsn bool   Request a delivery status notification
  --from string   Sender email address (which logged-in account sends) — REQUIRED
  --header stringArray   Custom header `X-Name: value` or `X-Name=value` (repeatable; TB requires X- names)
  --html string   HTML body (inline value)
  --html-file string   HTML body, read from a file
  --identity string   Deprecated alias for --from (accepts an email or a Thunderbird identity id)
  --inline-image stringArray   Inline image for the HTML body: PATH or CID=PATH (repeatable). Reference it in HTML as <img src="cid:CID">; CID defaults to the filename without extension. Embeds as multipart/related (renders inline in Gmail/Outlook), not a dangling attachment. FR-COMPOSE-14.
  --later bool   Open a compose window to send later
  --md string   Markdown body (inline value)
  --md-file string   Markdown body, read from a file
  --mjml string   MJML body (inline value)
  --mjml-file string   MJML body, read from a file
  --no-inline-css bool   Disable CSS inlining (default: on)
  --no-signature bool   Suppress the identity's TB signature
  --priority string   Message priority: lowest | low | normal | high | highest
  --receipt bool   Request a read receipt (return receipt)
  --reply-to string   Comma-separated Reply-To addresses
  --review bool   Open a compose window to review (nothing is sent — you click Send). FR-COMPOSE-14.
  --subject string   Override subject
  --template bool   Save as a template
  --text string   Plain-text body (inline value)
  --text-file string   Plain-text body, read from a file
  --to string   Comma-separated recipients (required)

## atbridge mail list
List recent messages in a folder
Flags:
  --account string   Restrict to one account — substring of its name/email/id (reads are lenient; writes need an EXACT account, FR-IDENT-02). Env: ATBRIDGE_DEFAULT_ACCOUNT
  --count bool   Print only {total, approx} — the message count in the folder
  --folder string   Folder label (default INBOX)
  --limit int   Max results (default 20)
  --offset int   Skip the first N (pagination) (default 0)
  --pretty bool   human-readable output (default: JSON)
  --verbose bool   Include the full per-result metadata (headerMessageId, folderLabel, accountName, conversationId) in JSON output. Default: lean rows — fetch the rest with `mail get`

## atbridge mail mark
Update flags on a message (or many via --ids / selector): read state, star, tags
Flags:
  --account string   Bulk selector: restrict to an account — EXACT full email or account id (FR-IDENT-02, no substring)
  --folder string   Bulk selector: restrict to a folder
  --ids string   Bulk: comma-separated message ids
  --max int   Bulk: max messages affected (safety cap) (default 100)
  --query string   Bulk selector: full-text query
  --read bool   Mark as read
  --star bool   Add star/flag
  --tags string   Comma-separated tag keys (replaces existing tags)
  --unread bool   Mark as unread
  --unstar bool   Remove star/flag

## atbridge mail move
Move a message (or many via --ids / selector) to another folder
Flags:
  --account string   Bulk selector: restrict to an account — EXACT full email or account id (FR-IDENT-02, no substring)
  --folder string   Bulk selector: restrict to a folder
  --ids string   Bulk: comma-separated message ids
  --max int   Bulk: max messages affected (safety cap) (default 100)
  --query string   Bulk selector: full-text query
  --to string   TARGET folder to move into (label like 'INBOX' or nested 'Notifications/Jira'; first match). NOTE: --folder below is the bulk SOURCE filter, not the target.

## atbridge mail reply
Reply to the sender of a message
Flags:
  --attach string   Comma-separated attachment file paths
  --bare-markdown bool   Skip the default markdown stylesheet
  --bcc string   Comma-separated BCC
  --cc string   Comma-separated CC
  --draft bool   Save as a draft instead of sending
  --dsn bool   Request a delivery status notification
  --from string   Sender email address (which logged-in account sends) — REQUIRED
  --header stringArray   Custom header `X-Name: value` or `X-Name=value` (repeatable; TB requires X- names)
  --html string   HTML body (inline value)
  --html-file string   HTML body, read from a file
  --identity string   Deprecated alias for --from (accepts an email or a Thunderbird identity id)
  --inline-image stringArray   Inline image for the HTML body: PATH or CID=PATH (repeatable). Reference it in HTML as <img src="cid:CID">; CID defaults to the filename without extension. Embeds as multipart/related (renders inline in Gmail/Outlook), not a dangling attachment. FR-COMPOSE-14.
  --later bool   Open a compose window to send later
  --md string   Markdown body (inline value)
  --md-file string   Markdown body, read from a file
  --mjml string   MJML body (inline value)
  --mjml-file string   MJML body, read from a file
  --no-inline-css bool   Disable CSS inlining (default: on)
  --no-signature bool   Suppress the identity's TB signature
  --priority string   Message priority: lowest | low | normal | high | highest
  --receipt bool   Request a read receipt (return receipt)
  --reply-to string   Comma-separated Reply-To addresses
  --review bool   Open a compose window to review (nothing is sent — you click Send). FR-COMPOSE-14.
  --subject string   Override subject
  --template bool   Save as a template
  --text string   Plain-text body (inline value)
  --text-file string   Plain-text body, read from a file
  --to string   Override recipients (comma-separated)

## atbridge mail reply-all
Reply to all recipients of a message
Flags:
  --attach string   Comma-separated attachment file paths
  --bare-markdown bool   Skip the default markdown stylesheet
  --bcc string   Comma-separated BCC
  --cc string   Comma-separated CC
  --draft bool   Save as a draft instead of sending
  --dsn bool   Request a delivery status notification
  --from string   Sender email address (which logged-in account sends) — REQUIRED
  --header stringArray   Custom header `X-Name: value` or `X-Name=value` (repeatable; TB requires X- names)
  --html string   HTML body (inline value)
  --html-file string   HTML body, read from a file
  --identity string   Deprecated alias for --from (accepts an email or a Thunderbird identity id)
  --inline-image stringArray   Inline image for the HTML body: PATH or CID=PATH (repeatable). Reference it in HTML as <img src="cid:CID">; CID defaults to the filename without extension. Embeds as multipart/related (renders inline in Gmail/Outlook), not a dangling attachment. FR-COMPOSE-14.
  --later bool   Open a compose window to send later
  --md string   Markdown body (inline value)
  --md-file string   Markdown body, read from a file
  --mjml string   MJML body (inline value)
  --mjml-file string   MJML body, read from a file
  --no-inline-css bool   Disable CSS inlining (default: on)
  --no-signature bool   Suppress the identity's TB signature
  --priority string   Message priority: lowest | low | normal | high | highest
  --receipt bool   Request a read receipt (return receipt)
  --reply-to string   Comma-separated Reply-To addresses
  --review bool   Open a compose window to review (nothing is sent — you click Send). FR-COMPOSE-14.
  --subject string   Override subject
  --template bool   Save as a template
  --text string   Plain-text body (inline value)
  --text-file string   Plain-text body, read from a file
  --to string   Override recipients (comma-separated)

## atbridge mail search
Full-text search across indexed messages
Flags:
  --account string   Restrict to one account — substring of its name/email/id (reads are lenient; writes need an EXACT account, FR-IDENT-02). Env: ATBRIDGE_DEFAULT_ACCOUNT
  --count bool   Print only {total, approx} — the total matching (for pagination) — not the messages. Best-effort for mail; scope with --folder/--since/--until for an exact count
  --folder string   Filter by folder label (e.g. INBOX)
  --from string   Filter by sender — substring of a name or address (e.g. billing@x.com or just billing)
  --limit int   Max results (default 20)
  --offset int   Skip the first N matches (pagination): --offset 20 --limit 20 = results 21-40 (default 0)
  --pretty bool   human-readable output (default: JSON)
  --since string   Lower date bound (inclusive): YYYY-MM-DD or RFC3339
  --snippet bool   Attach a short plaintext gist to each result (skips a follow-up mail get for one-line summaries)
  --subject string   Filter by subject substring
  --to string   Filter by recipient — substring of a name or address
  --until string   Upper date bound (inclusive): YYYY-MM-DD or RFC3339
  --verbose bool   Include the full per-result metadata (headerMessageId, folderLabel, accountName, conversationId) in JSON output. Default: lean rows (id, date, from/to, subject, read/flagged) — fetch the rest with `mail get`

## atbridge mail send
Compose + send a new message (or --draft / --template / --later)
Flags:
  --attach string   Comma-separated attachment file paths
  --bare-markdown bool   Skip the default markdown stylesheet
  --bcc string   Comma-separated BCC
  --cc string   Comma-separated CC
  --draft bool   Save as a draft instead of sending
  --dsn bool   Request a delivery status notification
  --from string   Sender email address (which logged-in account sends) — REQUIRED
  --header stringArray   Custom header `X-Name: value` or `X-Name=value` (repeatable; TB requires X- names)
  --html string   HTML body (inline value)
  --html-file string   HTML body, read from a file
  --identity string   Deprecated alias for --from (accepts an email or a Thunderbird identity id)
  --inline-image stringArray   Inline image for the HTML body: PATH or CID=PATH (repeatable). Reference it in HTML as <img src="cid:CID">; CID defaults to the filename without extension. Embeds as multipart/related (renders inline in Gmail/Outlook), not a dangling attachment. FR-COMPOSE-14.
  --later bool   Open a compose window to send later
  --md string   Markdown body (inline value)
  --md-file string   Markdown body, read from a file
  --mjml string   MJML body (inline value)
  --mjml-file string   MJML body, read from a file
  --no-inline-css bool   Disable CSS inlining (default: on)
  --no-signature bool   Suppress the identity's TB signature
  --priority string   Message priority: lowest | low | normal | high | highest
  --receipt bool   Request a read receipt (return receipt)
  --reply-to string   Comma-separated Reply-To addresses
  --review bool   Open a compose window to review (nothing is sent — you click Send). FR-COMPOSE-14.
  --subject string   Subject line (required)
  --template bool   Save as a template
  --text string   Plain-text body (inline value)
  --text-file string   Plain-text body, read from a file
  --to string   Comma-separated recipients (required)

## atbridge mail show
Show a single message body (gloda id or Message-ID)
Flags:
  --html bool   HTML body
  --include-headers bool   Include parsed headers
  --pretty bool   human-readable output (default: JSON)
  --raw bool   Raw RFC-822 message
  --text bool   Plain-text body (default)

## atbridge mail thread
Show the full conversation for a message
Flags:
  --limit int   Max results (default 50)
  --pretty bool   human-readable output (default: JSON)

## atbridge mcp
Run the MCP stdio server (Claude Desktop / Cursor / any MCP client)
Exposes atbridge's mail / contacts / calendar operations over MCP
(stdio JSON-RPC), so an MCP-compatible AI client can drive Thunderbird.

Read tools are always available. Write tools (send / delete / create / update)
require ATBRIDGE_ALLOW_WRITES=1 so an agent can't send or destroy mail unless
you opt in.

`atbridge mcp` (no subcommand) runs the server; `mcp detect` reports
which AI clients are wired in; `mcp setup --client <id>` writes the entry.

## atbridge mcp detect
Report which AI clients (Claude Desktop / Cursor / VS Code / JetBrains / Antigravity) have atbridge wired in
Flags:
  --allow-writes bool   Render the copy-paste snippet with write tools enabled (ATBRIDGE_ALLOW_WRITES=1)

## atbridge mcp setup
Write the atbridge MCP entry into an AI client's config (--client claude|cursor|vscode|jetbrains|antigravity)
Flags:
  --allow-writes bool   Unlock write tools (compose/send/draft, edits, deletes) by setting ATBRIDGE_ALLOW_WRITES=1 in the entry
  --client string   Which client: claude | cursor | vscode | jetbrains | antigravity

## atbridge mcp tools
List the MCP tools this build registers (read + write) — the docs source of truth

# atbridge notes — Local notes — save, list, show, and remove your @bridge markdown artifacts

## atbridge notes delete
Delete a note by id

## atbridge notes edit
Edit a note in place (body from --text/--from-file/stdin; --title to rename)
Flags:
  --from-file string   Replace the body from a file ('-' = stdin)
  --text string   Replace the body inline
  --title string   New title

## atbridge notes list
List saved notes (newest first)
Flags:
  --count bool   Print only {total, approx} — the total matching
  --limit int   Max results (default 20)
  --offset int   Skip the first N (pagination) (default 0)
  --pretty bool   human-readable output (default: JSON)

## atbridge notes mkdir
Create a folder in the notes tree (relative, e.g. work/2026)

## atbridge notes mv
Move or rename a note (dest is a relative path; an existing folder moves it in)

## atbridge notes path
Print the notes directory

## atbridge notes save
Save a new note (body from --text, --from-file, or piped stdin)
Flags:
  --folder string   Save into a subfolder (relative, e.g. work/2026)
  --from-file string   Read the body from a file ('-' = stdin)
  --source string   Where it came from (e.g. '@bridge chat')
  --tag stringArray   Tag (repeatable)
  --text string   Note body inline
  --title string   Note title (required)

## atbridge notes search
Search notes across all fields (title, body, tags, source); omit the query to list all
Flags:
  --count bool   Print only {total, approx} — the total matching
  --limit int   Max results (default 20)
  --offset int   Skip the first N (pagination) (default 0)
  --pretty bool   human-readable output (default: JSON)

## atbridge notes show
Show a note's content by id or title
Flags:
  --pretty bool   render the markdown body (default: JSON)

# atbridge tasks — Task / to-do commands (list, create, update, complete, delete)

## atbridge tasks complete
Mark a task done (or --reopen to set it back to needs-action)
Flags:
  --reopen bool   Reopen the task instead of completing it

## atbridge tasks create
Create a task (--title required; everything else optional)
Create a task / to-do (VTODO). Beyond --title, all Thunderbird task fields are supported: --start/--due (+--all-day), --priority, --notes, --location, --category, --status, --percent, --recur (+--until/--count), --reminder, and --attach/--attach-url.
Flags:
  --all-day bool   Treat start/due as all-day (date-only)
  --attach stringArray   Attach a local file (repeatable)
  --attach-url stringArray   Attach a URL/link (repeatable)
  --cal string   Task-list calendar id (REQUIRED — see `atbridge calendar list`; FR-IDENT-03, no default-to-first)
  --category stringArray   Category (repeatable)
  --count int   Number of occurrences (alternative to --until) (default 0)
  --due string   Due date, ISO 8601
  --location string   Location
  --notes string   Notes / description
  --percent int   Percent complete (0–100) (default 0)
  --priority string   high | normal | low (or 0–9)
  --recur string   RRULE body for a recurring series (e.g. FREQ=WEEKLY;BYDAY=MO)
  --reminder stringArray   Reminder: 15m|2h|1d (before due), start:30m, or at:<ISO> (repeatable)
  --start string   Start, ISO 8601
  --status string   needs-action | in-process | completed | cancelled
  --title string   Task title
  --until string   Recurrence end (ISO 8601)

## atbridge tasks delete
Delete a task by id

## atbridge tasks list
List tasks (incomplete by default; --all includes completed)
Flags:
  --all bool   Include completed tasks
  --cal string   Restrict to one calendar id
  --count bool   Print only {total, approx} — the total matching
  --limit int   Max results (default 20)
  --offset int   Skip the first N (pagination) (default 0)
  --pretty bool   human-readable output (default: JSON)
  --verbose bool   Include notes, attachments + reminders per task in JSON (default: lean)

## atbridge tasks search
Search tasks across all fields (title, notes, location, categories, status, due)
Flags:
  --all bool   Include completed tasks
  --cal string   Restrict to one calendar id
  --count bool   Print only {total, approx} — the total matching
  --limit int   Max results (default 20)
  --offset int   Skip the first N matches (pagination) (default 0)
  --pretty bool   human-readable output (default: JSON)
  --verbose bool   Include notes, attachments + reminders per task in JSON (default: lean)

## atbridge tasks update
Update a task (only the flags you pass are changed; '' clears a field)
Flags:
  --all-day bool   Treat start/due as all-day (date-only)
  --attach stringArray   Attach a local file (repeatable; pass none to clear)
  --attach-url stringArray   Attach a URL/link (repeatable)
  --category stringArray   Category (repeatable; pass none to clear)
  --count int   Number of occurrences (alternative to --until) (default 0)
  --due string   Due date, ISO 8601 (empty to clear)
  --location string   Location (empty to clear)
  --notes string   Notes / description (empty to clear)
  --percent int   Percent complete (0–100) (default 0)
  --priority string   high | normal | low | 0–9 (empty to clear)
  --recur string   RRULE body (empty to clear the series)
  --reminder stringArray   Reminder: 15m|2h|1d, start:30m, or at:<ISO> (repeatable; pass none to clear)
  --start string   Start, ISO 8601 (empty to clear)
  --status string   needs-action | in-process | completed | cancelled
  --title string   Task title
  --until string   Recurrence end (ISO 8601)

## atbridge uninstall
Remove atbridge (native-messaging host, service, config, binary)
Flags:
  --keep-data bool   Keep ~/.atbridge state (config, token, cache)
  --purge-notes bool   Also delete your saved @bridge Notes (user-data); off by default — notes are preserved
  --yes bool   Confirm removal (required)

## atbridge update
Update atbridge to the latest version (self-replacing)

## atbridge update-extension
Refresh the @bridge add-on XPI in the Thunderbird profile