@broodnet/cli 0.1.3 → 0.1.4

package/README.md

@@ -36,7 +36,40 @@ 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.
+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.
+
+```sh
+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.
+
+```sh
+broodnet use agent@example.com
+```
+
+---
+
+### `broodnet logout [email]`
+
+Remove one or more saved mailboxes from local config.
+
+```sh
+broodnet logout agent@example.com
+broodnet logout --all
+```
 
 ---
 
@@ -97,24 +130,60 @@ Hi there, ...
 
 ---
 
+### `broodnet mail delete <uid...>`
+
+Permanently delete messages by UID.
+
+```sh
+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:
+
+```json
+{ "success": true, "message": "optional", "data": {} }
+```
+
+or:
+
+```json
+{ "success": false, "error": "something went wrong", "data": null }
+```
+
 ```sh
 broodnet mail inbox --json
 ```
 
 ```json
-[
-  {
-    "uid": 1042,
-    "from": "alerts@github.com",
-    "subject": "[action required] review your billing",
-    "date": "2026-03-10T14:32:00.000Z",
-    "flags": { "seen": false, "answered": false, "flagged": true, "forwarded": false }
-  }
-]
+{
+  "success": true,
+  "data": [
+    {
+      "uid": "1042",
+      "from": "alerts@github.com",
+      "subject": "[action required] review your billing",
+      "date": "2026-03-10T14:32:00.000Z",
+      "flags": { "seen": false, "answered": false, "flagged": true, "forwarded": false }
+    }
+  ]
+}
 ```
 
 ```sh
@@ -123,12 +192,15 @@ broodnet mail open 1042 --json
 
 ```json
 {
-  "uid": 1042,
-  "from": "alerts@github.com",
-  "to": "agent@yourdomain.broodnet.com",
-  "subject": "[action required] review your billing",
-  "date": "2026-03-10T14:32:00.000Z",
-  "body": "Hi there, ..."
+  "success": true,
+  "data": {
+    "uid": "1042",
+    "from": "alerts@github.com",
+    "to": "agent@yourdomain.broodnet.com",
+    "subject": "[action required] review your billing",
+    "date": "2026-03-10T14:32:00.000Z",
+    "body": "Hi there, ..."
+  }
 }
 ```
 
@@ -138,14 +210,22 @@ broodnet mail open 1042 --json
 | ------------------ | ---------------------------------------------------------------------------------------- |
 | `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 first account becomes the active default. Switch between accounts with `--mailbox`:
+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`:
 
 ```sh
+broodnet ls
+broodnet use agent-a@yourdomain.broodnet.com
 broodnet mail inbox --mailbox=agent-a@yourdomain.broodnet.com
 broodnet mail inbox --mailbox=agent-b@yourdomain.broodnet.com
 ```