Email infrastructure for AI agents. Read, mark, 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 most recently logged-in mailbox becomes active.

broodnet ls

List all configured mailboxes and mark which one is active.

broodnet ls

Use --json for machine-readable output.

broodnet use <email>

Set the active mailbox. This becomes the default mailbox used by all commands when --mailbox is not specified.

broodnet use [email protected]

broodnet logout [email]

Remove one or more saved mailboxes from local config.

broodnet logout [email protected]
broodnet logout --all

broodnet mail inbox

List messages in your inbox. By default, the newest messages are shown first.

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 <number> | 20 | Number of messages to fetch | | --offset <number> | 0 | Number of matching messages to skip. By default, the newest. | | --sort <direction> | newest | Sort order: newest or oldest | | --unread | — | Show only unread messages | | --read / --seen | — | Show only read messages | | --important / --flagged | — | Show only flagged messages | | --answered | — | Show only answered messages | | --unanswered | — | Show only unanswered messages | | --mailbox <address> | active account | Address of a specific logged-in mailbox | | --json | — | Machine-readable output with messages, totals, pagination, sort |

Use --offset with --limit to page through the selected sort order.

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) |

broodnet mail mark <uid...>

Set or clear supported message flags without opening or deleting the message.

broodnet mail mark 1042 --seen
broodnet mail mark 10 11 12 --flagged
broodnet mail mark 1042 --seen --flagged
broodnet mail mark 1042 --unflagged

Options:

| Flag | Default | Description | | ------------- | -------------- | --------------------------------------- | | --seen | — | Mark messages as read | | --unseen | — | Mark messages as unread | | --flagged | — | Mark messages as flagged | | --unflagged | — | Remove the flagged marker | | --mailbox | active account | Address of a specific logged-in mailbox | | --json | — | Machine-readable output (see below) |

Conflicting pairs like --seen --unseen and --flagged --unflagged are rejected.

broodnet mail delete <uid...>

Permanently delete messages by UID.

broodnet mail delete 1042
broodnet mail delete 10 11 12

In interactive mode, the CLI asks for confirmation. In non-interactive mode (agents/CI), pass --yes.

Options:

| Flag | Default | Description | | ----------- | -------------- | ------------------------------------------------- | | --mailbox | active account | Address of a specific logged-in mailbox | | --yes | — | Skip confirmation (required when non-interactive) | | --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.

The output is always a stable envelope:

{ "success": true, "message": "optional", "data": {} }

or:

{ "success": false, "error": "something went wrong", "data": null }

broodnet mail inbox --json

{
  "success": true,
  "data": [
    {
      "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

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

broodnet mail mark 1042 --seen --json

{
  "success": true,
  "data": {
    "marked": ["1042"]
  }
}

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. | | BROODNET_API_URL | Override the API base URL (default: https://api.broodnet.com). |

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

Development note

In local dev (npm run dev), the CLI version shown by help/version is read from npm_package_version. In production builds (npm run build), Vite injects __CLI_VERSION__ from package.json.

Multiple accounts

Each broodnet login call adds an account to the local config. The most recently logged-in mailbox becomes active. Use broodnet ls to see what’s configured and broodnet use to switch the active mailbox. You can also override per-command with --mailbox:

broodnet ls
broodnet use [email protected]
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.