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.

If you try to switch to a mailbox that is not saved locally, broodnet use <mailbox> exits non-zero with error: mailbox <address> not found. In --json mode, the error envelope uses code: "NOT_FOUND".

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.

Environment overrides

These environment variables let you redirect or tunnel CLI traffic without changing saved config. They are useful in proxied environments, CI systems, or when running behind a corporate firewall.

API endpoint

Variable	Default	Description
BROODNET_API_URL	https://api.broodnet.com	Override the REST API base URL (e.g. a staging endpoint).

HTTP proxy

Node’s built-in fetch does not read proxy env vars automatically. The CLI configures a proxy agent when any of these are set:

Variable	Notes
HTTPS_PROXY / https_proxy	Used for all HTTPS API calls. Preferred.
HTTP_PROXY / http_proxy	Fallback if the HTTPS variants are not set.

All API calls are routed through the proxy. Standard http://host:port and http://user:pass@host:port proxy URLs are supported.

IMAP connection

IMAP connections are raw TCP — they are not automatically tunnelled through an HTTP proxy. In sandboxed environments where direct TCP or UDP-based DNS is blocked, you can redirect the IMAP connection to a local tunnel (e.g. via socat):

Variable	Default	Description
BROODNET_IMAP_HOST	mail.broodnet.com	Override the IMAP server hostname or IP.
BROODNET_IMAP_PORT	993	Override the IMAP port.

Example — tunnel IMAP through a local socat relay on port 1993:

socat TCP-LISTEN:1993,fork PROXY:proxy.corp.example:mail.broodnet.com:993,proxyport=3128 &
BROODNET_IMAP_HOST=127.0.0.1 BROODNET_IMAP_PORT=1993 broodnet mail inbox