From 8483f83a77e4ea0f4291f17519a4a05ace66f998 Mon Sep 17 00:00:00 2001
From: "exe.dev user" <exedev@discovery-lotus.exe.xyz>
Date: Sat, 8 Aug 2026 23:02:08 +0000
Subject: [PATCH] feat(mail): add batch subcommand, docs, and CHANGELOG (0.2.6)

Carries forward the unique portion of #13. The env-var and mail-list
work in that PR landed independently via #14 and #16, so only the batch
command remains; this drops the duplicated implementations rather than
conflicting with what shipped.

mail batch runs multiple label/unlabel/archive/move/flag/delete
operations over a single IMAP session, avoiding a connect and auth
round-trip per operation. All operations are validated up front, so
malformed input fails before any connection is opened or any mailbox is
mutated. Names containing IMAP special characters or CRLF are rejected,
and input is capped at 10MB.

Also fixes two defects from #13:
  - The --help-json examples used \" inside raw string literals, which
    emitted literal backslashes into the agent-facing schema.
  - docs/commands.md listed `seq` as a --fields name; the implementation
    that shipped in #16 uses `seq_num`.

Adds a CHANGELOG covering everything in 0.2.6 and bumps the version.

Closes #10.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md               |  37 +++++++
 docs/batch-format.md       |  70 +++++++++++++
 docs/commands.md           |  53 ++++++++++
 internal/cli/batch.go      | 210 +++++++++++++++++++++++++++++++++++++
 internal/cli/batch_test.go | 129 +++++++++++++++++++++++
 internal/cli/cli.go        |   8 +-
 internal/cli/help.go       |  13 +++
 7 files changed, 519 insertions(+), 1 deletion(-)
 create mode 100644 CHANGELOG.md
 create mode 100644 docs/batch-format.md
 create mode 100644 internal/cli/batch.go
 create mode 100644 internal/cli/batch_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..543ad02
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Targeted for the 0.2.6 release.
+
+### Added
+- `mail batch` subcommand: execute multiple label/unlabel/archive/move/flag/delete
+  operations from a JSON array over a single IMAP session, with per-op validation and
+  an optional `--stop-on-error` flag. Reported by @Juan-de-Costa-Rica (#10).
+- Server-side filtering for `mail list` (`--unread` via IMAP `SEARCH UNSEEN`, new
+  `--flagged` via `SEARCH FLAGGED`), additional envelope fields (`from_address`, `to`,
+  `message_id`, `in_reply_to`), and `--fields`/`--compact` JSON selection.
+  Reported by @Juan-de-Costa-Rica (#9), implemented by @kochj23 (#16).
+- `PM_CLI_BRIDGE_PASSWORD` environment variable as a fallback for the Bridge password,
+  for headless environments with no secret service. Takes precedence over the keyring
+  when set and non-empty. Reported by @Juan-de-Costa-Rica (#8), implemented by
+  @kochj23 (#14).
+
+### Fixed
+- `mail delete`, `mail move`, and label operations no longer report success when the
+  target UIDs are not present in the selected mailbox. A STORE that matches nothing is
+  a valid no-op per RFC 3501, so the affected-message count is now checked.
+  Reported by @Juan-de-Costa-Rica (#11), implemented by @kochj23 (#15).
+- The COPY no-match check is gated on the server advertising UIDPLUS, since COPYUID is
+  only guaranteed there; without the guard every successful copy on a non-UIDPLUS
+  server would have been reported as a failure (#17).
+
+### Changed
+- `mail list --unread` now returns up to `--limit` unread messages. Previously the
+  limit was applied before filtering, so the command could return far fewer results
+  than requested (#9).
diff --git a/docs/batch-format.md b/docs/batch-format.md
new file mode 100644
index 0000000..795fc31
--- /dev/null
+++ b/docs/batch-format.md
@@ -0,0 +1,70 @@
+# Batch Operation Format
+
+`pm-cli mail batch` reads a JSON array of operations from stdin (or from a file via `--file`) and executes them in order over a single IMAP connection.
+
+## Input
+
+A JSON array of operation objects:
+
+```json
+[
+  {"op": "label",   "uids": ["uid:123"], "label": "Important"},
+  {"op": "flag",    "uids": ["uid:456"], "read": true},
+  {"op": "archive", "uids": ["uid:789"]}
+]
+```
+
+Input is limited to 10MB. An empty array, malformed JSON, or any invalid operation causes the whole batch to be rejected **before** a connection is opened — nothing is executed.
+
+## Operation fields
+
+| Field | Type | Applies to | Description |
+|-------|------|-----------|-------------|
+| `op` | string | all | One of `label`, `unlabel`, `archive`, `move`, `flag`, `delete`. **Required.** |
+| `uids` | string[] | all | Message selectors — `uid:<n>` or a bare sequence number. **Required, non-empty.** Do not mix UID and sequence selectors within one operation. |
+| `mailbox` | string | all | Source mailbox. Defaults to `INBOX`. |
+| `label` | string | `label`, `unlabel` | Label name (mapped to the `Labels/<name>` folder). **Required** for these ops. |
+| `to` | string | `move` | Destination mailbox. **Required** for `move`. |
+| `read` | bool | `flag` | Mark messages read (`\Seen`). |
+| `unread` | bool | `flag` | Mark messages unread (remove `\Seen`). |
+| `star` | bool | `flag` | Star messages (`\Flagged`). |
+| `unstar` | bool | `flag` | Unstar messages (remove `\Flagged`). |
+
+A `flag` operation requires at least one of `read`, `unread`, `star`, `unstar`.
+
+Mailbox and label names containing IMAP special characters (`{`, `*`, `%`, CR, LF) are rejected.
+
+## Operations
+
+| op | Effect |
+|----|--------|
+| `label` | Copies the messages into `Labels/<label>` (adds the label; original is kept). |
+| `unlabel` | Removes the messages from `Labels/<label>` (removes the label). |
+| `archive` | Moves the messages from `mailbox` to `Archive`. |
+| `move` | Moves the messages from `mailbox` to `to`. |
+| `flag` | Adds/removes `\Seen` / `\Flagged` per the boolean fields. |
+| `delete` | Marks the messages deleted in `mailbox` (moves to Trash; not a permanent expunge). |
+
+## Output
+
+With `--json`, the command prints per-operation results plus totals:
+
+```json
+{
+  "results": [
+    {"op": "label", "success": true},
+    {"op": "flag", "success": false, "error": "no messages matched the given ID(s) in INBOX"}
+  ],
+  "total": 2,
+  "succeeded": 1,
+  "failed": 1
+}
+```
+
+By default every operation is attempted regardless of earlier failures. Pass `--stop-on-error` to halt after the first failure (the already-attempted results are still reported).
+
+## Notes
+
+- Operations execute sequentially in array order over one connection.
+- There is no transaction/rollback: a partial batch leaves partial state. Inspect `results` to see exactly what succeeded.
+- Accurate per-operation success reporting depends on the IMAP layer detecting no-op STORE/COPY commands. See issue #11.
diff --git a/docs/commands.md b/docs/commands.md
index 4843f56..7d5d924 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -14,6 +14,12 @@ These flags are available on all commands:
 | `-v, --verbose` | Verbose output |
 | `-q, --quiet` | Suppress non-essential output |
 
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PM_CLI_BRIDGE_PASSWORD` | Bridge password. When set (non-empty) it is used in preference to the system keyring. Intended for headless/CI environments with no secret service; interactive users should prefer the keyring (`pm-cli config init`). |
+
 ---
 
 ## config
@@ -121,20 +127,37 @@ pm-cli mail list [flags]
 | `--offset` | Skip first N messages | 0 |
 | `-p, --page` | Page number (1-based) | 0 |
 | `--unread` | Only show unread messages | false |
+| `--flagged` | Only show flagged/starred messages | false |
+| `--fields` | Comma-separated fields for JSON output | (all) |
+| `--compact` | Bare JSON array instead of wrapper object | false |
+
+**Filtering:**
+- `--unread` and `--flagged` use a server-side IMAP `SEARCH`, so the result honors `--limit` instead of being thinned out by client-side filtering. They can be combined.
 
 **Pagination:**
 - Use `--offset` to skip messages (e.g., `--offset 20` skips the 20 most recent)
 - Use `--page` for page-based navigation (e.g., `-p 2 -n 20` shows messages 21-40)
 - JSON output includes `offset`, `limit`, and `page` fields
 
+**JSON fields (`--json`):** Each message includes `uid`, `seq_num`, `from`, `from_address`, `to`, `message_id`, `in_reply_to`, `subject`, `date`, `date_iso`, `seen`, `flagged`. (`from` is the display name when present; `from_address` is always the bare address.) Empty fields are omitted.
+
+**Field selection (JSON only):**
+- `--fields` projects each message onto only the named fields, e.g. `--fields uid,subject,from_address`. Valid names: `uid`, `seq_num`, `from`, `from_address`, `to`, `message_id`, `in_reply_to`, `subject`, `date`, `date_iso`, `seen`, `flagged`.
+- `--compact` emits a bare JSON array (no `mailbox`/`count`/`messages` wrapper). Both flags only affect `--json` mode; text output is unchanged.
+
 **Examples:**
 ```bash
 pm-cli mail list
 pm-cli mail list -n 50
 pm-cli mail list -m Sent
 pm-cli mail list --unread
+pm-cli mail list --flagged --json
 pm-cli mail list --json
 
+# Field selection
+pm-cli mail list --json --fields uid,subject,from_address
+pm-cli mail list --json --fields uid,subject --compact
+
 # Pagination
 pm-cli mail list --offset 20           # Skip 20 most recent
 pm-cli mail list -p 2 -n 20            # Page 2 (messages 21-40)
@@ -415,6 +438,36 @@ pm-cli mail download 123 0
 pm-cli mail download 123 0 -o ~/Downloads/report.pdf
 ```
 
+### mail batch
+
+Run multiple operations over a single IMAP session. Reads a JSON array of operations from stdin (or a file via `--file`), avoiding a fresh connection and auth round-trip per operation. Intended for automated triage that applies labels, flags, and moves to many messages per run.
+
+```bash
+pm-cli mail batch [flags]
+```
+
+**Flags:**
+| Flag | Description |
+|------|-------------|
+| `-f, --file` | Read operations from a file instead of stdin |
+| `--stop-on-error` | Stop after the first failed operation |
+
+All operations are validated up front (unknown ops, missing required fields, and IMAP special characters in names are rejected before any connection is opened). Input is capped at 10MB. Output (`--json`) reports per-operation success/failure plus totals.
+
+See [batch-format.md](batch-format.md) for the full operation schema.
+
+**Examples:**
+```bash
+# Mark a message read, then archive another, in one session
+echo '[
+  {"op": "flag",    "uids": ["uid:123"], "read": true},
+  {"op": "archive", "uids": ["uid:456"]}
+]' | pm-cli mail batch --json
+
+# Apply a label and stop on the first failure
+pm-cli mail batch --file ops.json --json --stop-on-error
+```
+
 ### mail draft
 
 Manage email drafts.
diff --git a/internal/cli/batch.go b/internal/cli/batch.go
new file mode 100644
index 0000000..cd26124
--- /dev/null
+++ b/internal/cli/batch.go
@@ -0,0 +1,210 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/bscott/pm-cli/internal/imap"
+	"github.com/bscott/pm-cli/internal/safetext"
+)
+
+// maxBatchInputSize caps batch input to guard against unbounded reads from
+// stdin or an oversized file.
+const maxBatchInputSize = 10 * 1024 * 1024 // 10 MB
+
+// batchOp is a single operation in a batch request.
+type batchOp struct {
+	Op      string   `json:"op"`
+	UIDs    []string `json:"uids"`
+	Label   string   `json:"label,omitempty"`
+	To      string   `json:"to,omitempty"`
+	Mailbox string   `json:"mailbox,omitempty"`
+	Read    bool     `json:"read,omitempty"`
+	Unread  bool     `json:"unread,omitempty"`
+	Star    bool     `json:"star,omitempty"`
+	Unstar  bool     `json:"unstar,omitempty"`
+}
+
+// batchResult reports the outcome of a single operation.
+type batchResult struct {
+	Op      string `json:"op"`
+	Success bool   `json:"success"`
+	Error   string `json:"error,omitempty"`
+}
+
+// batchOutput is the top-level JSON response.
+type batchOutput struct {
+	Results   []batchResult `json:"results"`
+	Total     int           `json:"total"`
+	Succeeded int           `json:"succeeded"`
+	Failed    int           `json:"failed"`
+}
+
+var validBatchOps = map[string]bool{
+	"label":   true,
+	"unlabel": true,
+	"archive": true,
+	"move":    true,
+	"flag":    true,
+	"delete":  true,
+}
+
+func (c *MailBatchCmd) Run(ctx *Context) error {
+	if ctx.Config.Bridge.Email == "" {
+		return fmt.Errorf("not configured - run 'pm-cli config init' first")
+	}
+
+	ops, err := readBatchOps(c.File)
+	if err != nil {
+		return err
+	}
+
+	// Validate every operation up front so malformed input fails before we
+	// open a connection or mutate any mailbox.
+	for i, op := range ops {
+		if err := validateBatchOp(i, op); err != nil {
+			return err
+		}
+	}
+
+	client, err := imap.NewClient(ctx.Config)
+	if err != nil {
+		return err
+	}
+	if err := client.Connect(); err != nil {
+		return err
+	}
+	defer client.Close()
+
+	output := batchOutput{
+		Results: make([]batchResult, 0, len(ops)),
+		Total:   len(ops),
+	}
+
+	for _, op := range ops {
+		result := executeBatchOp(client, op)
+		output.Results = append(output.Results, result)
+		if result.Success {
+			output.Succeeded++
+		} else {
+			output.Failed++
+			if c.StopOnError {
+				break
+			}
+		}
+	}
+
+	return ctx.Formatter.PrintJSON(output)
+}
+
+// readBatchOps reads and decodes the batch request from a file or stdin.
+func readBatchOps(file string) ([]batchOp, error) {
+	var r io.Reader = os.Stdin
+	if file != "" {
+		f, err := os.Open(file)
+		if err != nil {
+			return nil, fmt.Errorf("failed to open batch file: %w", err)
+		}
+		defer f.Close()
+		r = f
+	}
+
+	// Read one extra byte so we can detect input that exceeds the cap.
+	data, err := io.ReadAll(io.LimitReader(r, maxBatchInputSize+1))
+	if err != nil {
+		return nil, fmt.Errorf("failed to read input: %w", err)
+	}
+	if len(data) > maxBatchInputSize {
+		return nil, fmt.Errorf("input exceeds maximum size of %d bytes", maxBatchInputSize)
+	}
+
+	return decodeBatchOps(data)
+}
+
+// decodeBatchOps parses a JSON array of operations and rejects empty input.
+func decodeBatchOps(data []byte) ([]batchOp, error) {
+	var ops []batchOp
+	if err := json.Unmarshal(data, &ops); err != nil {
+		return nil, fmt.Errorf("invalid JSON input: %w", err)
+	}
+	if len(ops) == 0 {
+		return nil, fmt.Errorf("no operations in input")
+	}
+	return ops, nil
+}
+
+// validateBatchOp checks required fields and rejects names containing IMAP
+// special characters before any IMAP command is issued.
+func validateBatchOp(index int, op batchOp) error {
+	if !validBatchOps[op.Op] {
+		return fmt.Errorf("operation %d: unknown op %q (valid: label, unlabel, archive, move, flag, delete)", index, op.Op)
+	}
+	if len(op.UIDs) == 0 {
+		return fmt.Errorf("operation %d (%s): uids is required", index, op.Op)
+	}
+	if err := validateMailboxName(op.Mailbox); err != nil {
+		return fmt.Errorf("operation %d (%s): source %w", index, op.Op, err)
+	}
+
+	switch op.Op {
+	case "label", "unlabel":
+		if op.Label == "" {
+			return fmt.Errorf("operation %d (%s): label is required", index, op.Op)
+		}
+		if err := validateMailboxName(op.Label); err != nil {
+			return fmt.Errorf("operation %d (%s): %w", index, op.Op, err)
+		}
+	case "move":
+		if op.To == "" {
+			return fmt.Errorf("operation %d (move): to is required", index)
+		}
+		if err := validateMailboxName(op.To); err != nil {
+			return fmt.Errorf("operation %d (move): %w", index, err)
+		}
+	case "flag":
+		if !op.Read && !op.Unread && !op.Star && !op.Unstar {
+			return fmt.Errorf("operation %d (flag): at least one of read, unread, star, unstar is required", index)
+		}
+	}
+	return nil
+}
+
+// validateMailboxName rejects names containing IMAP wildcards or CR/LF. An
+// empty name is allowed (callers default it to INBOX).
+func validateMailboxName(name string) error {
+	if strings.ContainsAny(name, "{*%\r\n") {
+		return fmt.Errorf("invalid mailbox/label name %q: contains IMAP special characters", name)
+	}
+	return nil
+}
+
+func executeBatchOp(client *imap.Client, op batchOp) batchResult {
+	mailbox := op.Mailbox
+	if mailbox == "" {
+		mailbox = "INBOX"
+	}
+
+	var err error
+	switch op.Op {
+	case "label":
+		err = client.CopyMessages(mailbox, op.UIDs, "Labels/"+op.Label)
+	case "unlabel":
+		err = client.DeleteMessages("Labels/"+op.Label, op.UIDs, true)
+	case "archive":
+		err = client.MoveMessages(mailbox, op.UIDs, "Archive")
+	case "move":
+		err = client.MoveMessages(mailbox, op.UIDs, op.To)
+	case "flag":
+		err = client.SetFlagsMultiple(mailbox, op.UIDs, op.Read, op.Unread, op.Star, op.Unstar)
+	case "delete":
+		err = client.DeleteMessages(mailbox, op.UIDs, false)
+	}
+
+	if err != nil {
+		return batchResult{Op: op.Op, Error: safetext.SanitizeForTerminal(err.Error())}
+	}
+	return batchResult{Op: op.Op, Success: true}
+}
diff --git a/internal/cli/batch_test.go b/internal/cli/batch_test.go
new file mode 100644
index 0000000..4d00ab3
--- /dev/null
+++ b/internal/cli/batch_test.go
@@ -0,0 +1,129 @@
+package cli
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateBatchOp(t *testing.T) {
+	tests := []struct {
+		name    string
+		op      batchOp
+		wantErr string // substring expected in error, "" means no error
+	}{
+		{
+			name: "valid label",
+			op:   batchOp{Op: "label", UIDs: []string{"uid:1"}, Label: "Work"},
+		},
+		{
+			name: "valid move",
+			op:   batchOp{Op: "move", UIDs: []string{"uid:1"}, To: "Archive"},
+		},
+		{
+			name: "valid flag read",
+			op:   batchOp{Op: "flag", UIDs: []string{"uid:1"}, Read: true},
+		},
+		{
+			name: "valid delete",
+			op:   batchOp{Op: "delete", UIDs: []string{"1"}},
+		},
+		{
+			name:    "unknown op",
+			op:      batchOp{Op: "frobnicate", UIDs: []string{"1"}},
+			wantErr: "unknown op",
+		},
+		{
+			name:    "missing uids",
+			op:      batchOp{Op: "delete"},
+			wantErr: "uids is required",
+		},
+		{
+			name:    "label missing label name",
+			op:      batchOp{Op: "label", UIDs: []string{"1"}},
+			wantErr: "label is required",
+		},
+		{
+			name:    "move missing destination",
+			op:      batchOp{Op: "move", UIDs: []string{"1"}},
+			wantErr: "to is required",
+		},
+		{
+			name:    "flag with no flag set",
+			op:      batchOp{Op: "flag", UIDs: []string{"1"}},
+			wantErr: "at least one of",
+		},
+		{
+			name:    "label name with IMAP wildcard",
+			op:      batchOp{Op: "label", UIDs: []string{"1"}, Label: "bad*name"},
+			wantErr: "IMAP special characters",
+		},
+		{
+			name:    "move destination with CRLF",
+			op:      batchOp{Op: "move", UIDs: []string{"1"}, To: "Archive\r\nEVIL"},
+			wantErr: "IMAP special characters",
+		},
+		{
+			name:    "source mailbox with CRLF rejected",
+			op:      batchOp{Op: "delete", UIDs: []string{"1"}, Mailbox: "INBOX\r\nEVIL"},
+			wantErr: "IMAP special characters",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateBatchOp(0, tt.op)
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Fatalf("unexpected error: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("expected error containing %q, got nil", tt.wantErr)
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("error %q does not contain %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestValidateMailboxName(t *testing.T) {
+	valid := []string{"", "INBOX", "Labels/Work", "Some Folder", "📚 Learning"}
+	for _, name := range valid {
+		if err := validateMailboxName(name); err != nil {
+			t.Errorf("expected %q to be valid, got %v", name, err)
+		}
+	}
+
+	invalid := []string{"a*b", "a%b", "a{b", "a\rb", "a\nb"}
+	for _, name := range invalid {
+		if err := validateMailboxName(name); err == nil {
+			t.Errorf("expected %q to be rejected", name)
+		}
+	}
+}
+
+func TestReadBatchOps(t *testing.T) {
+	t.Run("valid array", func(t *testing.T) {
+		ops, err := decodeBatchOps([]byte(`[{"op":"delete","uids":["1"]}]`))
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(ops) != 1 || ops[0].Op != "delete" {
+			t.Fatalf("unexpected ops: %+v", ops)
+		}
+	})
+
+	t.Run("empty array", func(t *testing.T) {
+		if _, err := decodeBatchOps([]byte(`[]`)); err == nil {
+			t.Error("expected error for empty array")
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		if _, err := decodeBatchOps([]byte(`{not json`)); err == nil {
+			t.Error("expected error for invalid json")
+		}
+	})
+}
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index a97b915..f265f50 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -5,7 +5,7 @@ import (
 	"github.com/bscott/pm-cli/internal/output"
 )
 
-var Version = "0.2.5"
+var Version = "0.2.6"
 
 type Globals struct {
 	JSON     bool   `help:"Output as JSON" name:"json"`
@@ -99,6 +99,12 @@ type MailCmd struct {
 	Label     LabelCmd         `cmd:"" help:"Manage message labels"`
 	Summarize MailSummarizeCmd `cmd:"" help:"Summarize message for AI processing"`
 	Extract   MailExtractCmd   `cmd:"" help:"Extract structured data from message"`
+	Batch     MailBatchCmd     `cmd:"" help:"Run multiple operations in one IMAP session (JSON from stdin)"`
+}
+
+type MailBatchCmd struct {
+	File        string `help:"Read operations from a file instead of stdin" short:"f" type:"existingfile"`
+	StopOnError bool   `help:"Stop after the first failed operation" name:"stop-on-error"`
 }
 
 type MailSummarizeCmd struct {
diff --git a/internal/cli/help.go b/internal/cli/help.go
index 5429d96..2cfcacb 100644
--- a/internal/cli/help.go
+++ b/internal/cli/help.go
@@ -251,6 +251,19 @@ func extractMailCommands() CommandSchema {
 					"pm-cli mail search '' --since 2024-01-01 --json",
 				},
 			},
+			{
+				Name:        "mail batch",
+				Description: "Run multiple operations in one IMAP session (JSON array on stdin)",
+				Flags: []FlagSchema{
+					{Name: "--file", Short: "-f", Type: "string", Description: "Read operations from a file instead of stdin"},
+					{Name: "--stop-on-error", Type: "bool", Description: "Stop after the first failed operation"},
+				},
+				Examples: []string{
+					`echo '[{"op":"flag","uids":["uid:123"],"read":true}]' | pm-cli mail batch --json`,
+					`echo '[{"op":"label","uids":["uid:1"],"label":"Work"},{"op":"archive","uids":["uid:2"]}]' | pm-cli mail batch --json`,
+					"pm-cli mail batch --file ops.json --json --stop-on-error",
+				},
+			},
 		},
 	}
 }