Email infrastructure for AI agents. Read and manage your Broodnet mailboxes from the terminal.

Installation

npm install -g @broodnet/cli

Requires Node.js 22+.

Getting started

You need a Broodnet account and at least one mailbox. Sign up at broodnet.com.

Once you have a mailbox, grab its token from the dashboard and authenticate:

broodnet login --token=bnt_XXXxxXXX

Credentials are saved to ~/.config/broodnet/config.json. You only need to do this once per mailbox.

Modules

mail

Read email from your Broodnet mailboxes over IMAP. Requires a mailbox token — issued per mailbox from the Broodnet dashboard when you create a mailbox.

Commands

broodnet login

Authenticate a mailbox token and save the connection config locally.

broodnet login --token=bnt_XXXxxXXX

Validates the token against the API, fetches IMAP settings, and writes them to ~/.config/broodnet/config.json. Run this once per mailbox. Multiple accounts are supported — the first one logged in becomes the active default.

broodnet mail inbox

List the latest messages in your inbox.

broodnet mail inbox

UID      FLAGS  FROM                 SUBJECT                                  DATE
-------- ------ -------------------- ---------------------------------------- --------------------
1042     ●★     [email protected]    [action required] review your billing     2 hours ago
1041     ○      [email protected]   BRD-42 was closed                        yesterday
1040     ○↩     [email protected]     your mailbox is ready                    Mar 8

Flags: ● unread · ○ read · ↩ replied · ★ flagged · ⤴ forwarded

Options:

| Flag | Default | Description | | ----------- | -------------- | --------------------------------------- | | --limit | 20 | Number of messages to fetch | | --mailbox | active account | Address of a specific logged-in mailbox | | --json | — | Machine-readable output (see below) |

broodnet mail open <uid>

Fetch and display a message by its UID. Marks it as read.

broodnet mail open 1042

────────────────────────────────────────────────────────────
From:    [email protected]
To:      [email protected]
Subject: [action required] review your billing
Date:    Mar 10, 2026 14:32
────────────────────────────────────────────────────────────

Hi there, ...

Options:

| Flag | Default | Description | | ----------- | -------------- | --------------------------------------------- | | --mailbox | active account | Address of a specific logged-in mailbox | | --raw | — | Print raw RFC822 source including all headers | | --json | — | Machine-readable output (see below) |

--json flag

Every command accepts --json. Output goes to stdout as formatted JSON — no colors, no tables, no banners. Designed for piping into agents or scripts.

broodnet mail inbox --json

[
  {
    "uid": 1042,
    "from": "[email protected]",
    "subject": "[action required] review your billing",
    "date": "2026-03-10T14:32:00.000Z",
    "flags": { "seen": false, "answered": false, "flagged": true, "forwarded": false }
  }
]

broodnet mail open 1042 --json

{
  "uid": 1042,
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "[action required] review your billing",
  "date": "2026-03-10T14:32:00.000Z",
  "body": "Hi there, ..."
}

Environment variables

| Variable | Description | | ------------------ | ---------------------------------------------------------------------------------------- | | BROODNET_TOKEN | Mailbox token. Bypasses the config file entirely — useful in CI or containerized agents. | | BROODNET_MAILBOX | Select a specific logged-in mailbox by address. |

When BROODNET_TOKEN is set, no login is required — the token is validated at runtime on every command.

Multiple accounts

Each broodnet login call adds an account to the local config. The first account becomes the active default. Switch between accounts with --mailbox:

broodnet mail inbox [email protected]
broodnet mail inbox [email protected]

Exit codes

| Code | Meaning | | ---- | ------------------------------------- | | 0 | Success | | 1 | General error | | 2 | Auth error (token invalid or missing) | | 3 | IMAP connection error |

License

MIT — see LICENSE.