diff --git a/USER-MANUAL.md b/USER-MANUAL.md index 9961ed1..47493f1 100644 --- a/USER-MANUAL.md +++ b/USER-MANUAL.md @@ -176,17 +176,18 @@ emcli account add # opens the form Or with flags (good for scripting): ```bash -emcli account add --name work --mode RW \ +emcli account add work --mode RW \ --imap-host imap.example.com --imap-port 993 --imap-security tls \ --smtp-host smtp.example.com --smtp-port 465 --smtp-security tls \ --username you@example.com --password 'your-password' ``` +The account name is the first positional argument. Omit it to open the interactive form. + **`account add` flags:** | Flag | Default | Notes | |---|---|---| -| `--name` | — | Account name the agent will use (required) | | `--mode` | `RO` | `RO` (read-only) or `RW` (read + send) | | `--imap-host` | — | IMAP server (required) | | `--imap-port` | `993` | | @@ -198,10 +199,10 @@ emcli account add --name work --mode RW \ | `--password` | — | Login password or app password | | `--from` | — | Send-as address (blank = use username); bare or `"Display Name "` | | `--subject-regex` | — | Inbound subject filter (optional) | -| `--whitelist-in` | off | Enable inbound whitelist | -| `--whitelist-out` | off | Enable outbound whitelist | | `--process-backlog` | off | Treat existing mail as "new" (see below) | +To enable whitelisting after adding an account, use `whitelist enable` (section 6). + **`--process-backlog`.** When `emcli` first sees a folder: - **off (default):** existing mail is treated as already handled — `list --new` starts empty and only mail that arrives *after* this point counts as new. @@ -219,7 +220,7 @@ Gmail needs an **app password**, not your normal Google password. 4. Add the account (paste the app password; the spaces Google shows are optional): ```bash -emcli account add --name gmail --mode RW \ +emcli account add gmail --mode RW \ --imap-host imap.gmail.com --imap-port 993 --imap-security tls \ --smtp-host smtp.gmail.com --smtp-port 465 --smtp-security tls \ --username you@gmail.com --password 'xxxxxxxxxxxxxxxx' @@ -233,7 +234,7 @@ An app password keeps working until you revoke it, change your main Google passw Most IMAP/SMTP providers work the same way. A typical cPanel-style host: ```bash -emcli account add --name work --mode RW \ +emcli account add work --mode RW \ --imap-host mail.yourdomain.com --imap-port 993 --imap-security tls \ --smtp-host mail.yourdomain.com --smtp-port 465 --smtp-security tls \ --username you@yourdomain.com --password 'your-password' @@ -252,34 +253,42 @@ confirm. emcli account list ``` +**Show an account's current settings:** + +```bash +emcli account show gmail +``` + +Prints the account name, mode, IMAP/SMTP host, username, send-from address, subject filter, and +whitelist state. The password is never shown. + **Edit an account** — interactive (opens the form pre-filled): ```bash -emcli account edit --name gmail +emcli account edit gmail ``` **Edit with flags** — only the flags you pass are changed; everything else is preserved. Leaving `--password` out keeps the existing password. ```bash -emcli account edit --name work --mode RW --smtp-host smtp.example.com --smtp-port 587 --smtp-security starttls -emcli account edit --name gmail --password 'new-app-password' # rotate the app password +emcli account edit work --mode RW --smtp-host smtp.example.com --smtp-port 587 --smtp-security starttls +emcli account edit gmail --password 'new-app-password' # rotate the app password ``` ```bash -emcli account edit --name work --from 'Work Team ' # set the send-as address -emcli account edit --name work --from '' # clear it (revert to username) +emcli account edit work --from 'Work Team ' # set the send-as address +emcli account edit work --from '' # clear it (revert to username) ``` > Note: the flag form of `account edit` covers connection/auth fields, `--from`, and > `--subject-regex`. Passing `--from ''` clears the send-as address so mail falls back to the login -> username. To toggle whitelists or `process-backlog`, use the interactive form (`emcli account edit -> --name X` with no other flags), or the `whitelist` commands in section 6. +> username. To enable or disable whitelists use `whitelist enable`/`whitelist disable` (section 6). -**Remove an account** (requires `--yes`): +**Remove an account** (requires `--yes` when stdin is not a terminal): ```bash -emcli account remove --name work --yes +emcli account remove work --yes ``` --- @@ -292,24 +301,30 @@ Set with `--mode RO|RW` on `account add`/`edit`. `RO` accounts reject every `sen ### Inbound whitelist -Enable it on the account (`--whitelist-in`, or the interactive form), then manage entries: +Manage entries, then enable filtering when ready: ```bash -emcli whitelist in add --account gmail --address boss@example.com -emcli whitelist in add --account gmail --address @partner.com -emcli whitelist in list --account gmail -emcli whitelist in remove --account gmail --address boss@example.com +emcli whitelist add gmail boss@example.com --in +emcli whitelist add gmail @partner.com --in +emcli whitelist list gmail --in +emcli whitelist remove gmail boss@example.com --in +emcli whitelist enable gmail --in # activate filtering +emcli whitelist disable gmail --in # suspend filtering without removing entries ``` +`whitelist list` shows the current entries and whether filtering is ENABLED or DISABLED. +Enabling an empty whitelist warns you that all inbound mail will be blocked until you add addresses. + When enabled, the agent only sees mail from listed senders. Everything else is invisible. ### Outbound whitelist -Enable it (`--whitelist-out`), then manage entries the same way with `whitelist out`: +Same pattern with `--out`: ```bash -emcli whitelist out add --account gmail --address @example.com -emcli whitelist out list --account gmail +emcli whitelist add gmail @example.com --out +emcli whitelist list gmail --out +emcli whitelist enable gmail --out ``` When enabled, **every** recipient of a `send` (to + cc + bcc) must match an entry or the whole @@ -326,10 +341,10 @@ send is blocked. A regular expression on the account. If set, the agent only sees mail whose subject matches: ```bash -emcli account edit --name gmail --subject-regex '^\[ticket\]' +emcli account edit gmail --subject-regex '^\[ticket\]' ``` -Clear it by setting it empty in the interactive form. +Clear it by passing an empty string (`--subject-regex ''`) or using the interactive form. --- @@ -499,8 +514,9 @@ A blocked send (read-only account): sends and reads nothing. ```bash -emcli doctor # check every account -emcli doctor --account gmail # check just one +emcli doctor # check every account +emcli doctor gmail # check just one (positional) +emcli doctor --account gmail # same — flag form also works ``` Example output: @@ -541,6 +557,7 @@ the reason. Secrets never appear here. ### Settings ```bash +emcli config list # list all settings and their current values emcli config set audit_retention_days 90 emcli config get audit_retention_days ``` @@ -548,6 +565,9 @@ emcli config get audit_retention_days - `audit_retention_days` — how long to keep audit rows. On each run, entries older than this are purged. Must be a whole number ≥ 0. `0` or unset means no automatic purging. +`config list` prints every known setting, its current value, and a short description. Unknown keys +are rejected by `config get` and `config set`. + --- ## 11. Troubleshooting @@ -571,11 +591,11 @@ the DEK if one already exists) with both correct keys, then re-add any accounts `587`/`starttls` is a common alternative to `465`/`tls`. **The agent can't see a message you know exists.** It's probably filtered: check the account's -inbound whitelist (`emcli whitelist in list --account NAME`) and subject filter. Filtered mail is +inbound whitelist (`emcli whitelist list NAME --in`) and subject filter. Filtered mail is invisible by design. **`send` is blocked.** -- `ro_mode` — the account is read-only. Change it: `emcli account edit --name NAME --mode RW` +- `ro_mode` — the account is read-only. Change it: `emcli account edit NAME --mode RW` (and set SMTP details). - `whitelist_out` — a recipient isn't on the outbound whitelist. Add it, or review the rule. @@ -597,18 +617,20 @@ emcli # or: emcli help / emcli --help — list all commands emcli --help # usage and flags for one command # Admin (requires EMCLI_ADMIN_KEY) -emcli init # create DB + add first account (form) -emcli account add [flags | none for form] # add an account -emcli account list # full table (admin) / name+from+can_send JSON (agent) -emcli account edit --name N [flags | none for form] # change an account -emcli account remove --name N --yes # delete an account -emcli whitelist in|out add|remove|list --account N [--address A] -emcli config set|get [value] # e.g. audit_retention_days +emcli init # create DB + add first account (form) +emcli account add [] [flags] # add an account; no args → interactive form +emcli account list # full table (admin) / name+from+can_send JSON (agent) +emcli account show N # display one account's settings +emcli account edit N [flags | none for form] # change an account +emcli account remove N [--yes] # delete an account (--yes or TTY confirm) +emcli whitelist N [addr…] --in|--out +emcli config list # list all settings and descriptions +emcli config set|get [value] # e.g. audit_retention_days emcli audit list [--account N] [--limit K] emcli version # Agent (requires EMCLI_KEY or EMCLI_ADMIN_KEY; one line of JSON each) -emcli doctor [--account N] # connectivity/auth check +emcli doctor [N | --account N] # connectivity/auth check emcli list --account N [--folder F] [--new] [--limit K] [--before U] [--since U] emcli get --account N [--folder F] --uid U emcli search --account N [--folder F] [--from A] [--subject-contains S] [--text S] [--since-date D] [--before-date D] [--limit K]