engagelab-email-cli 1.1.1 → 1.4.0

package/README.md

@@ -1,6 +1,14 @@
 # EngageLab Email CLI
 
-Command line tool for EngageLab Email Agent workflows. Use it to query inbound messages, inspect threads, listen for new messages, reply to inbound mail, and send outbound mail.
+EngageLab Email CLI helps agents and developers work with inbound and outbound email from the command line.
+
+Use it to:
+
+- List and inspect email threads
+- Read inbound messages
+- Poll for new inbound messages
+- Reply to inbound messages
+- Send new emails
 
 ## Install
 
@@ -8,32 +16,46 @@ Command line tool for EngageLab Email Agent workflows. Use it to query inbound m
 npm install -g engagelab-email-cli
 ```
 
-Check the installed command:
+Check the installed version:
 
 ```bash
 engagelab-email-cli -V
 ```
 
+When you run a command that connects to EngageLab Email, the CLI checks whether a newer CLI version is available. If an update is required, it stops and shows the update command:
+
+```bash
+npm install -g engagelab-email-cli@latest
+```
+
 ## Configure
 
-Save your API base URL and Secret Key locally:
+Save your service address and Secret Key locally:
 
 ```bash
 engagelab-email-cli config set --base-url http://localhost:8087 --secret-key sk_xxx
 ```
 
-View the current configuration:
+If you do not configure `baseUrl` manually, the CLI will obtain it automatically from the Secret Key. If you do configure `baseUrl`, the CLI uses the configured value.
+
+View the saved configuration:
 
 ```bash
 engagelab-email-cli config list
 ```
 
-`config list` masks the Secret Key and never prints the full value.
+Clear the saved configuration:
 
-You can also pass credentials per command:
+```bash
+engagelab-email-cli config clear
+```
+
+`config list` masks the Secret Key.
+
+You can also pass credentials for a single command:
 
 ```bash
-engagelab-email-cli --base-url http://localhost:8087 --secret-key sk_xxx emails receiving list --json
+engagelab-email-cli --base-url http://localhost:8087 --secret-key sk_xxx emails receiving list
 ```
 
 Configuration priority:
@@ -42,138 +64,274 @@ Configuration priority:
 2. Environment variables: `ENGAGELAB_EMAIL_BASE_URL`, `ENGAGELAB_EMAIL_SECRET_KEY`
 3. Local config file
 
-## Recommended Agent Usage
+## Quick Start
 
-For Agent or Skill integrations, use `--json` and JSON body files. This avoids shell quoting issues with long text, HTML, arrays, and newlines.
+List recent inbound messages:
 
 ```bash
-engagelab-email-cli emails receiving listen --limit 10 --interval 5 --json
-engagelab-email-cli threads messages <thread-id> --include-content --json
-engagelab-email-cli emails receiving reply <message-uid> --body-file reply.json --json
-engagelab-email-cli emails send --body-file send.json --json
+engagelab-email-cli emails receiving list --page-size 20
+```
+
+Read one inbound message:
+
+```bash
+engagelab-email-cli emails receiving get <message-uid>
 ```
 
-`emails receiving listen --json` prints NDJSON: one JSON object per new message line.
+View the full thread around a message:
 
-## Threads
+```bash
+engagelab-email-cli threads messages <thread-id> --include-content
+```
 
-List threads:
+Reply to an inbound message:
 
 ```bash
-engagelab-email-cli threads list --mailbox-id 1001 --subject refund --participant alice@example.com --page-no 1 --page-size 20
+engagelab-email-cli emails receiving reply <message-uid> --text "Thanks, we received your message."
 ```
 
-Get one thread:
+Send a new email:
 
 ```bash
-engagelab-email-cli threads get <thread-id> --json
+engagelab-email-cli emails send \
+  --mailbox-id 1001 \
+  --to alice@example.com \
+  --subject "Hello" \
+  --text "Hello from EngageLab Email CLI."
 ```
 
-List messages in a thread:
+For scripts or agents, add `--json` to get machine-readable output:
 
 ```bash
-engagelab-email-cli threads messages <thread-id> --limit 50 --include-content --json
+engagelab-email-cli emails receiving list --page-size 20 --json
 ```
 
-## Receiving
+## Commands
+
+### `config set`
+
+Save local configuration.
 
-List inbound messages:
+| Option | Description |
+| --- | --- |
+| `--base-url <url>` | Service address, such as `http://localhost:8087`. |
+| `--secret-key <key>` | Secret Key. It must start with `sk_`. |
+
+Example:
 
 ```bash
-engagelab-email-cli emails receiving list --mailbox-id 1001 --keyword refund --json
+engagelab-email-cli config set --base-url http://localhost:8087 --secret-key sk_xxx
 ```
 
-Get one inbound message:
+### `config list`
+
+Show saved configuration.
+
+Example:
 
 ```bash
-engagelab-email-cli emails receiving get <message-uid> --json
+engagelab-email-cli config list
 ```
 
-Listen for new inbound messages:
+### `config clear`
+
+Clear saved local configuration, including `baseUrl` and `secretKey`.
+
+Example:
 
 ```bash
-engagelab-email-cli emails receiving listen --limit 10 --interval 5 --json
+engagelab-email-cli config clear
 ```
 
-Continue from a known cursor:
+### `threads list`
+
+List email threads.
+
+| Option | Description |
+| --- | --- |
+| `--mailbox-id <id>` | Filter by mailbox ID. |
+| `--subject <text>` | Search by subject. |
+| `--participant <email>` | Search by participant email address. |
+| `--start-time <timestamp>` | Filter by latest message start time in milliseconds. |
+| `--end-time <timestamp>` | Filter by latest message end time in milliseconds. |
+| `--page-no <number>` | Page number. |
+| `--page-size <number>` | Number of results per page. |
+| `--json` | Output raw JSON. |
+
+Example:
 
 ```bash
-engagelab-email-cli emails receiving listen --after 1500 --limit 10 --interval 5 --json
+engagelab-email-cli threads list --subject refund --page-no 1 --page-size 20
 ```
 
-`listen` is a long-running polling command:
+### `threads get <thread-id>`
 
-- If `--after` is not provided, it seeds the cursor from the latest message and does not print historical messages on startup.
-- It polls `GET /v1/message/listen` every `--interval` seconds.
-- `--interval` defaults to `5`; the minimum is `2`.
-- It updates the cursor from the newest returned message.
-- It keeps running until `Ctrl+C` or process termination.
+Show one thread.
 
-## Reply
+| Argument/Option | Description |
+| --- | --- |
+| `<thread-id>` | Thread ID. |
+| `--json` | Output raw JSON. |
 
-Reply with plain text:
+Example:
 
 ```bash
-engagelab-email-cli emails receiving reply <message-uid> --text "您好，您的邮件已收到。" --json
+engagelab-email-cli threads get b0d9d6a1-1d17-4df8-8245-c807d7e8cb50
 ```
 
-Reply with a JSON file:
+### `threads messages <thread-id>`
+
+List messages in a thread.
+
+| Argument/Option | Description |
+| --- | --- |
+| `<thread-id>` | Thread ID. |
+| `--limit <number>` | Maximum number of messages to return. |
+| `--include-content` | Include message content and attachment information. |
+| `--json` | Output raw JSON. |
+
+Example:
 
 ```bash
-engagelab-email-cli emails receiving reply <message-uid> --body-file reply.json --json
+engagelab-email-cli threads messages b0d9d6a1-1d17-4df8-8245-c807d7e8cb50 --include-content --json
 ```
 
-`reply.json`:
+### `emails receiving list`
+
+List inbound messages.
+
+| Option | Description |
+| --- | --- |
+| `--mailbox-id <id>` | Filter by mailbox ID. |
+| `--keyword <text>` | Search by keyword. |
+| `--page-no <number>` | Page number. |
+| `--page-size <number>` | Number of results per page. |
+| `--json` | Output raw JSON. |
 
-```json
-{
-  "subject": "Re: Refund request",
-  "text": "您好，您的退款申请已收到。",
-  "html": "<p>您好，您的退款申请已收到。</p>",
-  "cc": ["ops@example.com"],
-  "bcc": []
-}
+Example:
+
+```bash
+engagelab-email-cli emails receiving list --keyword refund --page-size 20
 ```
 
-## Send
+### `emails receiving get <message-uid>`
+
+Show one inbound message.
+
+| Argument/Option | Description |
+| --- | --- |
+| `<message-uid>` | Message UID. |
+| `--json` | Output raw JSON. |
 
-Send with command options:
+Example:
 
 ```bash
-engagelab-email-cli emails send --mailbox-id 1001 --to alice@example.com --subject "Refund update" --text "您的退款申请已经处理完成。" --json
+engagelab-email-cli emails receiving get 7e2b2de6-14c5-4ef1-a1e2-f4337e4606e2 --json
 ```
 
-Send an HTML file:
+### `emails receiving listen`
+
+Poll for new inbound messages. This command keeps running until you stop it with `Ctrl+C`.
+
+| Option | Description |
+| --- | --- |
+| `--after <id>` | Start after a known cursor ID. |
+| `--limit <number>` | Maximum messages per poll. Default: `10`. |
+| `--interval <seconds>` | Polling interval. Default: `5`; minimum: `2`. |
+| `--json` | Output one JSON message per line. |
+
+Example:
 
 ```bash
-engagelab-email-cli emails send --mailbox-id 1001 --to alice@example.com --subject "Refund update" --html-file ./email.html --json
+engagelab-email-cli emails receiving listen --limit 10 --interval 5 --json
 ```
 
-Send with a JSON file:
+Continue from a known cursor:
 
 ```bash
-engagelab-email-cli emails send --body-file send.json --json
+engagelab-email-cli emails receiving listen --after 1500 --limit 10 --interval 5 --json
 ```
 
-`send.json`:
+### `emails receiving reply <message-uid>`
+
+Reply to an inbound message.
+
+| Argument/Option | Description |
+| --- | --- |
+| `<message-uid>` | Message UID to reply to. |
+| `--subject <text>` | Reply subject. |
+| `--text <text>` | Plain text reply content. |
+| `--html <html>` | HTML reply content. |
+| `--text-file <path>` | Read plain text reply content from a file. |
+| `--html-file <path>` | Read HTML reply content from a file. |
+| `--cc <email>` | CC address. Can be repeated. |
+| `--bcc <email>` | BCC address. Can be repeated. |
+| `--reply-to <email>` | Reply-To address. Can be repeated. |
+| `--preview-text <text>` | Preview text. |
+| `--attachment <path>` | Attach a file. Can be repeated. Up to 10 files, 10MB total. |
+| `--sandbox` | Send in sandbox mode. |
+| `--json` | Output raw JSON. |
 
-```json
-{
-  "mailboxId": 1001,
-  "to": ["alice@example.com"],
-  "subject": "Refund update",
-  "text": "您的退款申请已经处理完成。",
-  "html": "<p>您的退款申请已经处理完成。</p>",
-  "cc": [],
-  "bcc": []
-}
+Example:
+
+```bash
+engagelab-email-cli emails receiving reply 7e2b2de6-14c5-4ef1-a1e2-f4337e4606e2 \
+  --text "Thanks, we received your message." \
+  --attachment ./receipt.pdf
+```
+
+### `emails send`
+
+Send a new email.
+
+| Option | Description |
+| --- | --- |
+| `--mailbox-id <id>` | Mailbox ID to send from. Required. |
+| `--from <email>` | Sender address. |
+| `--to <email>` | Recipient address. Can be repeated. Required. |
+| `--subject <text>` | Email subject. Required. |
+| `--text <text>` | Plain text email content. |
+| `--html <html>` | HTML email content. |
+| `--text-file <path>` | Read plain text email content from a file. |
+| `--html-file <path>` | Read HTML email content from a file. |
+| `--cc <email>` | CC address. Can be repeated. |
+| `--bcc <email>` | BCC address. Can be repeated. |
+| `--reply-to <email>` | Reply-To address. Can be repeated. |
+| `--preview-text <text>` | Preview text. |
+| `--attachment <path>` | Attach a file. Can be repeated. Up to 10 files, 10MB total. |
+| `--sandbox` | Send in sandbox mode. |
+| `--json` | Output raw JSON. |
+
+Example:
+
+```bash
+engagelab-email-cli emails send \
+  --mailbox-id 1001 \
+  --to alice@example.com \
+  --to bob@example.com \
+  --subject "Refund update" \
+  --text "Your refund has been processed." \
+  --attachment ./receipt.pdf
+```
+
+Send HTML content from a file:
+
+```bash
+engagelab-email-cli emails send \
+  --mailbox-id 1001 \
+  --to alice@example.com \
+  --subject "Monthly report" \
+  --html-file ./report.html
 ```
 
-## Body Input Rules
+## Output
+
+By default, the CLI prints readable tables or summaries and shows a short loading message while requests are running.
+
+Use `--json` when another tool or script needs to parse the result.
+
+```bash
+engagelab-email-cli emails receiving get <message-uid> --json
+```
 
-- `--body-file` and `--body-json` are mutually exclusive.
-- `--body-file` or `--body-json` cannot be combined with field-level body options.
-- `--text` and `--text-file` are mutually exclusive.
-- `--html` and `--html-file` are mutually exclusive.
-- `emails send` requires `mailboxId`, at least one `to`, `subject`, and at least one of `text` or `html`.
-- `emails receiving reply` requires at least one of `text` or `html`.
+`emails receiving listen --json` prints one message JSON object per line.