steve/emcli
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 5 Wiki Activity

docs: update admin command reference to positional grammar

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Steve Cliff
2026-06-27 12:28:23 +01:00
parent 1a03ce1c69
commit 1e00f68a3d
1 changed files with 59 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
USER-MANUAL.md
+59 -37
View File
@@ -176,17 +176,18 @@ emcli account add # opens the form
Or with flags (good for scripting): Or with flags (good for scripting):
```bash ```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 \ --imap-host imap.example.com --imap-port 993 --imap-security tls \
--smtp-host smtp.example.com --smtp-port 465 --smtp-security tls \ --smtp-host smtp.example.com --smtp-port 465 --smtp-security tls \
--username you@example.com --password 'your-password' --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:** **`account add` flags:**
| Flag | Default | Notes | | Flag | Default | Notes |
|---|---|---| |---|---|---|
| `--name` | — | Account name the agent will use (required) |
| `--mode` | `RO` | `RO` (read-only) or `RW` (read + send) | | `--mode` | `RO` | `RO` (read-only) or `RW` (read + send) |
| `--imap-host` | — | IMAP server (required) | | `--imap-host` | — | IMAP server (required) |
| `--imap-port` | `993` | | | `--imap-port` | `993` | |
@@ -198,10 +199,10 @@ emcli account add --name work --mode RW \
| `--password` | — | Login password or app password | | `--password` | — | Login password or app password |
| `--from` | — | Send-as address (blank = use username); bare or `"Display Name <addr>"` | | `--from` | — | Send-as address (blank = use username); bare or `"Display Name <addr>"` |
| `--subject-regex` | — | Inbound subject filter (optional) | | `--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) | | `--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: **`--process-backlog`.** When `emcli` first sees a folder:
- **off (default):** existing mail is treated as already handled — `list --new` starts empty and - **off (default):** existing mail is treated as already handled — `list --new` starts empty and
only mail that arrives *after* this point counts as new. 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): 4. Add the account (paste the app password; the spaces Google shows are optional):
```bash ```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 \ --imap-host imap.gmail.com --imap-port 993 --imap-security tls \
--smtp-host smtp.gmail.com --smtp-port 465 --smtp-security tls \ --smtp-host smtp.gmail.com --smtp-port 465 --smtp-security tls \
--username you@gmail.com --password 'xxxxxxxxxxxxxxxx' --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: Most IMAP/SMTP providers work the same way. A typical cPanel-style host:
```bash ```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 \ --imap-host mail.yourdomain.com --imap-port 993 --imap-security tls \
--smtp-host mail.yourdomain.com --smtp-port 465 --smtp-security tls \ --smtp-host mail.yourdomain.com --smtp-port 465 --smtp-security tls \
--username you@yourdomain.com --password 'your-password' --username you@yourdomain.com --password 'your-password'
@@ -252,34 +253,42 @@ confirm.
emcli account list 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): **Edit an account** — interactive (opens the form pre-filled):
```bash ```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 **Edit with flags** — only the flags you pass are changed; everything else is preserved. Leaving
`--password` out keeps the existing password. `--password` out keeps the existing password.
```bash ```bash
emcli account edit --name work --mode RW --smtp-host smtp.example.com --smtp-port 587 --smtp-security starttls emcli account edit 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 gmail --password 'new-app-password' # rotate the app password
``` ```
```bash ```bash
emcli account edit --name work --from 'Work Team <you@yourdomain.com>' # set the send-as address emcli account edit work --from 'Work Team <you@yourdomain.com>' # set the send-as address
emcli account edit --name work --from '' # clear it (revert to username) emcli account edit work --from '' # clear it (revert to username)
``` ```
> Note: the flag form of `account edit` covers connection/auth fields, `--from`, and > 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 > `--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 > username. To enable or disable whitelists use `whitelist enable`/`whitelist disable` (section 6).
> --name X` with no other flags), or the `whitelist` commands in section 6.
**Remove an account** (requires `--yes`): **Remove an account** (requires `--yes` when stdin is not a terminal):
```bash ```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 ### Inbound whitelist
Enable it on the account (`--whitelist-in`, or the interactive form), then manage entries: Manage entries, then enable filtering when ready:
```bash ```bash
emcli whitelist in add --account gmail --address boss@example.com emcli whitelist add gmail boss@example.com --in
emcli whitelist in add --account gmail --address @partner.com emcli whitelist add gmail @partner.com --in
emcli whitelist in list --account gmail emcli whitelist list gmail --in
emcli whitelist in remove --account gmail --address boss@example.com 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. When enabled, the agent only sees mail from listed senders. Everything else is invisible.
### Outbound whitelist ### Outbound whitelist
Enable it (`--whitelist-out`), then manage entries the same way with `whitelist out`: Same pattern with `--out`:
```bash ```bash
emcli whitelist out add --account gmail --address @example.com emcli whitelist add gmail @example.com --out
emcli whitelist out list --account gmail 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 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: A regular expression on the account. If set, the agent only sees mail whose subject matches:
```bash ```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. sends and reads nothing.
```bash ```bash
emcli doctor # check every account emcli doctor # check every account
emcli doctor --account gmail # check just one emcli doctor gmail # check just one (positional)
emcli doctor --account gmail # same — flag form also works
``` ```
Example output: Example output:
@@ -541,6 +557,7 @@ the reason. Secrets never appear here.
### Settings ### Settings
```bash ```bash
emcli config list # list all settings and their current values
emcli config set audit_retention_days 90 emcli config set audit_retention_days 90
emcli config get audit_retention_days 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 - `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. 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 ## 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`. `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 **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. invisible by design.
**`send` is blocked.** **`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). (and set SMTP details).
- `whitelist_out` — a recipient isn't on the outbound whitelist. Add it, or review the rule. - `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 <command> --help # usage and flags for one command emcli <command> --help # usage and flags for one command
# Admin (requires EMCLI_ADMIN_KEY) # Admin (requires EMCLI_ADMIN_KEY)
emcli init # create DB + add first account (form) emcli init # create DB + add first account (form)
emcli account add [flags | none for form] # add an account emcli account add [<name>] [flags] # add an account; no args → interactive form
emcli account list # full table (admin) / name+from+can_send JSON (agent) 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 show N # display one account's settings
emcli account remove --name N --yes # delete an account emcli account edit N [flags | none for form] # change an account
emcli whitelist in|out add|remove|list --account N [--address A] emcli account remove N [--yes] # delete an account (--yes or TTY confirm)
emcli config set|get <key> [value] # e.g. audit_retention_days emcli whitelist <add|remove|list|enable|disable> N [addr…] --in|--out
emcli config list # list all settings and descriptions
emcli config set|get <key> [value] # e.g. audit_retention_days
emcli audit list [--account N] [--limit K] emcli audit list [--account N] [--limit K]
emcli version emcli version
# Agent (requires EMCLI_KEY or EMCLI_ADMIN_KEY; one line of JSON each) # 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 list --account N [--folder F] [--new] [--limit K] [--before U] [--since U]
emcli get --account N [--folder F] --uid 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] emcli search --account N [--folder F] [--from A] [--subject-contains S] [--text S] [--since-date D] [--before-date D] [--limit K]