@samva/cli 0.10.0 → 0.12.0

package/AGENTS.md

@@ -109,8 +109,10 @@ calls to you, rather than to an installation. Read what exists with `list`, `ver
 `--cursor`, and `--all --jsonl`.
 
 `samva mailboxes` reads and sends as a mailbox: `list` pages with `--limit`, `--cursor`, `--after`,
-and `--before`. `get <id>` inspects a mailbox; `update <id> --data <JSON-or-@file>` changes
-`displayName`, `defaultFrom`, or `metadata` (merges by key, `null` deletes a key). `pause <id>`
+and `--before`. `create --address <address> --name <name>` makes a mailbox with one address; the
+slug defaults to the address's local part, and a collision asks for `--slug` rather than suffixing.
+`get <id>` inspects a mailbox; `update <id> --data <JSON-or-@file>` changes
+`name`, `defaultFrom`, or `metadata` (merges by key, `null` deletes a key). `pause <id>`
 stops sending and receiving, and `resume <id>` resumes without backfilling mail received while
 paused. These mutations support `--dry-run`. `remove <id>` deletes a mailbox (`--yes` outside a terminal, `--dry-run` to
 preview), `threads` searches, `read` prints a message (human output marks the body as
@@ -132,3 +134,8 @@ the error `reason`, its `status` and `details`, and a `Try:` line; the last hand
 `--cursor` resumes from, goes to stderr in human mode and into `details.lastCursor` otherwise.
 `samva extensions dev` follows the same output modes. 401 and 403 exit 4. An expired
 cursor exits 1 and the next step is to start without `--cursor`. Ctrl+C exits cleanly.
+
+`samva subscriptions subscribe` requests one email confirmation with `--email`,
+`--contact-group-id`, and `--from`. Optional flags record signup context, select a template, or
+name the unsubscribe group whose opt-out confirmation clears. A successful receipt means the
+request was accepted; group membership waits for recipient confirmation on the hosted page.

package/README.md

@@ -339,6 +339,25 @@ samva campaigns runs recipients <campaign-id> <run-id> --status failed
 scheduled message. Campaign definitions freeze after their first run. Cancelling a scheduled
 message or campaign run requires confirmation, and dispatch already in progress may still finish.
 
+## Contacts
+
+```sh
+samva contacts list --search ada --limit 25
+samva contacts list --fields plan,score --json
+samva contacts list --custom-field plan --custom-field-value '"pro"' --json
+samva contacts list --all --jsonl
+samva contacts get contact_7q2xk9mvt4znw8rh --json
+```
+
+`list` returns a bounded page with a `nextCursor`; pass it as `--cursor` to resume. `--fields`
+selects the custom-field keys included in each summary. Exact custom-field filtering requires
+both `--custom-field` and `--custom-field-value`, with the value encoded as a JSON scalar
+(for example `'"pro"'`, `42`, `true`, or `null`). `--search`, `--status`, `--after`, and `--before`
+combine with that filter. `get` returns the contact's identities, profile, custom fields, and metadata.
+If a list page fails, machine-readable stderr includes `details.cursor`. Retry with that
+`--cursor` and the same filters to resume after the contacts already printed; a null cursor means
+the first page failed, so retry without `--cursor`.
+
 ## Automation contract
 
 Use `--dry-run` on supported mutations to validate input and preview the intended request. `email
@@ -402,7 +421,7 @@ samva email send --help
 ```
 
 Released top-level commands are `login`, `logout`, `org`, `email`, `messages`, `campaigns`,
-`scheduled-messages`, `templates`, `brands`, `webhooks`, `profile`, and `help`. Use `samva <command> --help`
+`contacts`, `scheduled-messages`, `templates`, `brands`, `webhooks`, `profile`, and `help`. Use `samva <command> --help`
 for flags and runnable examples.
 
 Test a configured webhook against its real endpoint with an optional JSON payload. `--data` accepts