@samva/cli 0.12.0 → 0.14.0

package/AGENTS.md

@@ -8,6 +8,29 @@ Machine-readable results go to stdout; warnings and typed errors go to stderr. E
 fields. Follow `next` and fix `details.fields` before retrying. API 401 and 403 exit with code `4`;
 other operational failures exit with code `1`. Human mode prints the same message and recovery step.
 
+`samva api <path>` is the floor under every command: it calls any public endpoint with the CLI's
+credentials (`SAMVA_API_KEY`, or the signed-in profile and its organization) and prints the API
+response as returned, not the `{schemaVersion,...}` envelope, so `--json` and `--jsonl` are refused
+(exit `2`). The path is relative to the API URL (`email/domains` and `/v1/email/domains` are the same
+request); a full URL is refused so credentials reach only the selected API URL, and redirects are not
+followed. The method is `GET`, or `POST` once a field or `--input` is given. `-f` adds a string field,
+`-F` a typed one (`true`, `false`, `null`, integers, `@file`, `@-`), `a[b]=v` nests, `a[]=v` appends;
+on a `GET` or with `--input` fields go to the query string. `--paginate` follows `nextCursor` through
+the `cursor` query parameter and prints one page per line, `--slurp` one JSON array. A non-2xx
+response writes its body to stderr and exits `4` for 401 and 403, otherwise `1`. Pipe to `jq`; there
+is no built-in filter.
+
+`samva api-keys` manages the organization's keys: `list`, `get`, `create`, `update`, `rotate`, and
+`revoke`. `create` takes `--name` and exactly one of `--full-access` or repeatable `--grant
+<resource>=read|write` (neither or both exits `2`), plus optional `--description` and `--expires-at`;
+mailbox and namespace scope go through `samva api`. The API refuses a key with more access than the
+caller holds. `create` and `rotate` return the secret once: `--json` carries `{apiKey, key,
+displayOnce, warning}`, so `samva api-keys create ... --json | jq -r .data.key` yields the key, and
+human mode prints it to stdout with the warning on stderr. `rotate` and `revoke` require
+confirmation (`--yes` outside a terminal), and every mutation supports `--dry-run`. Under
+`SAMVA_API_KEY`, `samva org current` asks the API who the key is (`GET /v1/whoami`) and reports its
+organization and key; with OAuth it reports the profile's selected organization.
+
 `samva templates export --out <dir>` renders every local template's fixtures to HTML
 and text with the asset manifest, needing a Samva credential only to resolve a live `samva:brand`; `--asset-base <origin>` is for an
 export that will be delivered, which cannot carry a relative reference.
@@ -109,10 +132,11 @@ 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`. `create --address <address> --name <name>` makes a mailbox with one address; the
+and `--before`. `create --address <address> --name <name>` makes a mailbox with one email endpoint; 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>`
+`name` or `metadata` (merges by key, `null` deletes a key); a mailbox's endpoints, their
+sender names, and its default are `endpoints add|update|remove`. `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
@@ -124,8 +148,8 @@ held; `release` and `discard` take the held message's `id` and require a person
 `--all --jsonl`. `actions approve <action-id> --mailbox <id>` and `actions deny <action-id>
 --mailbox <id> [--reason <text>]` require a person different from the proposer, confirmation
 (`--yes` outside a terminal), and offer `--dry-run`.
-Human mailbox and extension results retain the same facts as JSON: mailbox addresses and sending
-identity, thread state and activity, message bodies, attachments, authentication and actor,
+Human mailbox and extension results retain the same facts as JSON: mailbox endpoints (channel, address,
+sender name, default), thread state and activity, message bodies, attachments, authentication and actor,
 receipt waits and skipped recipients, held-mail results, and installation/run details.
 `samva mailboxes events` reads the SDK event stream with reconnects off and prints
 one record per event, `{cursor, id, event}` (`--jsonl` wraps each in a result envelope, `--quiet`