CLI Config

The CLI needs a mailbox token and connection settings to access mail.

First-time setup

Run broodnet login with a mailbox token:

• Required: --token
• Result: the CLI saves the mailbox and sets it as the active mailbox

Where config is stored

By default, the CLI stores config at:

• ~/.config/broodnet/config.json

The config can hold multiple mailboxes.

Selecting a mailbox

Mail commands accept an optional --mailbox flag. If you do not pass it, the CLI selects a mailbox using this logic:

If BROODNET_TOKEN is set (ephemeral auth): the CLI uses it directly and skips any saved config entirely. No login required.

Otherwise, the CLI reads from saved config in this order:

1. --mailbox flag
2. BROODNET_MAILBOX environment variable
3. the active mailbox in your config
4. the first mailbox in your config

Managing saved mailboxes

• broodnet ls lists saved mailboxes and marks the active one.
• broodnet use <mailbox> sets the active mailbox.
• broodnet logout removes mailboxes from local config:
  • broodnet logout <mailbox> removes one
  • broodnet logout --all removes all
  • with exactly one mailbox saved, running broodnet logout with no args removes it immediately
  • in interactive mode with multiple mailboxes saved, running broodnet logout with no args shows a picker
  • in non-interactive mode with multiple mailboxes, you must pass an address or --all

Removing the active mailbox clears the active pointer — no other mailbox is promoted automatically.

Per-mailbox defaults

Each saved mailbox can have a configured from address — a default sender used by mail send when --from is not passed. This is also used as the display name shown by broodnet ls.

Set it with broodnet mail config --from:

broodnet mail config --from='Agent Bot <agent@acme.com>'

The value must be a verified sender for that mailbox. To view the current default:

broodnet mail config

To remove a default, set it to the mailbox address itself. If no default is configured, mail send falls back to the mailbox address as the sender.

API endpoint override

To point the CLI at a different API environment (for example, a staging endpoint), set:

• BROODNET_API_URL