@samva/cli 0.16.0 → 0.17.0

package/AGENTS.md

@@ -21,9 +21,15 @@ response writes its body to stderr and exits `4` for 401 and 403, otherwise `1`.
 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
+`revoke`. `create` takes `--name` and either `--full-access` or restricted access built from repeatable
+`--grant <resource>=read|write` and mailbox access: repeatable `--mailbox-permission
+read|update|send|quarantine.read`, optionally narrowed to repeatable `--mailbox <id>` (default:
+every mailbox the owner reaches) with `--send-mode approval` (each send waits for a person other
+than the key). `--namespace <id>` confines a restricted key to one namespace. Passing no access, or both
+`--full-access` and restricted access, exits `2`, as does `--mailbox` or `--send-mode` without a
+`--mailbox-permission`. `--description` and `--expires-at` are optional. `update` renames a key,
+sets its description, or changes a mailbox key's `--send-mode` (a person signed in with `samva
+login`); every other part of a key's access is fixed at creation. 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
@@ -136,7 +142,10 @@ calls to you, rather than to an installation. Read what exists with `list`, `ver
 `run <id> <run-id>` (adds the handler's log lines); the list commands page with `--limit`,
 `--cursor`, and `--all --jsonl`.
 
-`samva mailboxes` reads and sends as a mailbox: `list` pages with `--limit`, `--cursor`, `--after`,
+`samva mailboxes` reads and sends as a mailbox. Every command except `list` and `create`
+takes the mailbox ID as its first argument and the message, action, or endpoint ID second,
+as in `read <mailbox-id> <message-id>` and `endpoints update <mailbox-id> <endpoint-id>`; `events`
+takes any number of mailbox IDs, or none for every mailbox the credential reads. `list` pages with `--limit`, `--cursor`, `--after`,
 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
@@ -156,9 +165,9 @@ public SDK describes email only.
 Quarantine `list` pages the same way, bounded by `--after` and `--before` on when a message was
 held; `release` and `discard` take the held message's `id` and require a person signed in with
 `samva login`. Discard requires confirmation (`--yes` outside a terminal) and supports `--dry-run`.
-`actions list --mailbox <id>` filters by `--state` and pages with `--limit`, `--cursor`, and
-`--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
+`actions list <mailbox-id>` filters by `--state` and pages with `--limit`, `--cursor`, and
+`--all --jsonl`. `actions approve <mailbox-id> <action-id>` and `actions deny <mailbox-id>
+<action-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 endpoints (channel, address,
 sender name, default), thread state and activity, message bodies, attachments, authentication and actor,

package/dist/bin.mjs

@@ -14106,7 +14106,7 @@ var layer12 = /* @__PURE__ */ layer.pipe(/* @__PURE__ */ provideMerge(/* @__PURE
 // package.json
 var package_default = {
   name: "@samva/cli",
-  version: "0.16.0",
+  version: "0.17.0",
   description: "Samva CLI \u2014 email and platform operations from your terminal",
   keywords: [
     "cli",
@@ -14168,10 +14168,10 @@ var package_default = {
     vitest: "catalog:"
   },
   optionalDependencies: {
-    "@samva/cli-darwin-arm64": "workspace:0.16.0",
-    "@samva/cli-darwin-x64": "workspace:0.16.0",
-    "@samva/cli-linux-arm64": "workspace:0.16.0",
-    "@samva/cli-linux-x64": "workspace:0.16.0"
+    "@samva/cli-darwin-arm64": "workspace:0.17.0",
+    "@samva/cli-darwin-x64": "workspace:0.17.0",
+    "@samva/cli-linux-arm64": "workspace:0.17.0",
+    "@samva/cli-linux-x64": "workspace:0.17.0"
   },
   engines: {
     node: ">=18"
@@ -19353,6 +19353,7 @@ var Literals4 = (name, choices) => Literals2(argumentKind, name, choices);
 var optional5 = (arg) => optional3(arg);
 var withDescription4 = /* @__PURE__ */ dual(2, (self, description) => withDescription(self, description));
 var withDefault6 = withDefault4;
+var atLeast3 = /* @__PURE__ */ dual(2, (self, min) => atLeast(self, min));
 var withSchema3 = /* @__PURE__ */ dual(2, (self, schema) => withSchema(self, schema));
 var filterMap3 = /* @__PURE__ */ dual(3, (self, f, onNone) => filterMap2(self, f, onNone));
 
@@ -26569,6 +26570,7 @@ var API_KEY_STATEMENT = {
 };
 var API_KEY_RESOURCES = Object.keys(API_KEY_STATEMENT);
 var API_KEY_LEVEL_RESOURCES = API_KEY_RESOURCES.filter((resource) => resource !== "mailboxes");
+var API_KEY_MAILBOX_ACTIONS = mailboxKeyActions;
 function apiKeyAccessLevels(resource) {
   return API_KEY_STATEMENT[resource].some((action) => action !== "read") ? ["read", "write"] : ["read"];
 }
@@ -29066,7 +29068,7 @@ var parseGrant = (raw) => {
   if (resource === "mailboxes") {
     return new CliUsageError({
       code: "invalid_grant",
-      message: "--grant does not cover mailboxes; mailbox and namespace access are set with `samva api`."
+      message: "--grant does not cover mailboxes; use --mailbox-permission <action> (with optional --mailbox and --send-mode) instead."
     });
   }
   if (!isLevelResource(resource) || !isGrantLevel(level)) {
@@ -29083,19 +29085,52 @@ var parseGrant = (raw) => {
   }
   return { resource, level };
 };
-var accessFromFlags = (grants, fullAccess) => gen2(function* () {
-  if (fullAccess && grants.length > 0) {
+var repeated = (values) => values.find((value, index) => values.indexOf(value) !== index);
+var mailboxAccessFromFlags = (flags) => gen2(function* () {
+  if (flags.permissions.length === 0) {
+    if (flags.mailboxIds.length > 0 || isSome2(flags.sendMode)) {
+      return yield* new CliUsageError({
+        code: "mailbox_permission_required",
+        message: `--mailbox and --send-mode narrow mailbox access; also pass --mailbox-permission ${API_KEY_MAILBOX_ACTIONS.join("|")}.`
+      });
+    }
+    return;
+  }
+  const duplicatePermission = repeated(flags.permissions);
+  if (duplicatePermission !== undefined) {
+    return yield* new CliUsageError({
+      code: "invalid_mailbox_access",
+      message: `--mailbox-permission names ${duplicatePermission} more than once.`
+    });
+  }
+  const duplicateMailbox = repeated(flags.mailboxIds);
+  if (duplicateMailbox !== undefined) {
+    return yield* new CliUsageError({
+      code: "invalid_mailbox_access",
+      message: `--mailbox names ${duplicateMailbox} more than once.`
+    });
+  }
+  return {
+    permissions: flags.permissions,
+    ...flags.mailboxIds.length > 0 ? { mailboxIds: flags.mailboxIds } : {},
+    ...isSome2(flags.sendMode) ? { sendMode: flags.sendMode.value } : {}
+  };
+});
+var accessFromFlags = (grants, fullAccess, mailbox, namespace) => gen2(function* () {
+  const restrictedFlags = grants.length > 0 || mailbox.permissions.length > 0 || mailbox.mailboxIds.length > 0 || isSome2(mailbox.sendMode) || isSome2(namespace);
+  if (fullAccess && restrictedFlags) {
     return yield* new CliUsageError({
       code: "access_conflict",
-      message: "Pass either --full-access or --grant <resource>=read|write, not both."
+      message: "Pass either --full-access or restricted access (--grant, --mailbox-permission, --namespace), not both."
     });
   }
   if (fullAccess)
     return { mode: "full" };
-  if (grants.length === 0) {
+  const mailboxes = yield* mailboxAccessFromFlags(mailbox);
+  if (grants.length === 0 && mailboxes === undefined) {
     return yield* new CliUsageError({
       code: "access_required",
-      message: "Choose the key's access: --full-access, or one or more --grant <resource>=read|write."
+      message: "Choose the key's access: --full-access, or one or more --grant <resource>=read|write and/or --mailbox-permission <action>."
     });
   }
   const resources = {};
@@ -29111,7 +29146,12 @@ var accessFromFlags = (grants, fullAccess) => gen2(function* () {
     }
     resources[grant.resource] = grant.level;
   }
-  return { mode: "restricted", resources };
+  return {
+    mode: "restricted",
+    resources,
+    ...mailboxes === undefined ? {} : { mailboxes },
+    ...isSome2(namespace) ? { namespaceId: namespace.value } : {}
+  };
 });
 var parseExpiresAt = (raw) => Number.isNaN(Date.parse(raw)) ? fail6(new CliUsageError({
   code: "invalid_expires_at",
@@ -29125,7 +29165,12 @@ var describeAccess = (access) => {
     return "full";
   const grants = Object.entries(access.resources).filter(([, level]) => level !== undefined).map(([resource, level]) => `${resource}:${level}`);
   if (access.mailboxes !== undefined && access.mailboxes !== null) {
-    grants.push(`mailboxes:${access.mailboxes.permissions.join("+")}`);
+    const { permissions, mailboxIds, sendMode } = access.mailboxes;
+    const scope = [
+      ...mailboxIds === undefined || mailboxIds === null ? [] : [mailboxIds.join("+")],
+      ...sendMode === undefined || sendMode === "send" ? [] : [`${sendMode} sends`]
+    ];
+    grants.push(`mailboxes:${permissions.join("+")}${scope.length === 0 ? "" : ` [${scope.join("; ")}]`}`);
   }
   if (access.namespaceId !== undefined && access.namespaceId !== null)
     grants.push(`namespace:${access.namespaceId}`);
@@ -29204,11 +29249,19 @@ var create2 = make29("create", {
   description: String9("description").pipe(withDescription2("What the key is for"), optional4),
   expiresAt: String9("expires-at").pipe(withDescription2("When the key stops working, an ISO 8601 instant"), optional4),
   grant: String9("grant").pipe(withDescription2(`Give a restricted key a resource at a level, <resource>=read|write (repeatable). Resources: ${GRANTABLE_RESOURCES.join(", ")}`), atLeast2(0)),
-  fullAccess: Boolean6("full-access").pipe(withDescription2("Give the key its owner's full access instead of --grant"), withDefault5(false)),
+  mailboxPermission: Literals3("mailbox-permission", API_KEY_MAILBOX_ACTIONS).pipe(withDescription2(`Let a restricted key work in mailboxes with this action (repeatable): ${API_KEY_MAILBOX_ACTIONS.join(", ")}`), atLeast2(0)),
+  mailbox: String9("mailbox").pipe(withSchema2(MailboxId), withDescription2("Confine the mailbox access to this mailbox (repeatable); omit for every mailbox the owner reaches"), atLeast2(0)),
+  sendMode: Literals3("send-mode", mailboxSendModes).pipe(withDescription2("With approval, each send waits until a person other than the key approves it (default send)"), optional4),
+  namespace: String9("namespace").pipe(withSchema2(NamespaceId), withDescription2("Confine a restricted key to one namespace (ns_...)"), optional4),
+  fullAccess: Boolean6("full-access").pipe(withDescription2("Give the key its owner's full access instead of restricted access"), withDefault5(false)),
   dryRun: dryRunFlag,
   json: jsonFlag
 }).pipe(withDescription3("Create an API key. The secret is shown once; the API refuses access you do not hold."), withExamples([
   { command: "samva api-keys create --name ci --grant email=write --dry-run" },
+  {
+    command: "samva api-keys create --name agent --mailbox-permission read --mailbox-permission send --mailbox mbx_1234567890123456 --send-mode approval",
+    description: "A key that works in one mailbox and needs a person to approve each send"
+  },
   {
     command: "samva api-keys create --name ci --grant email=write --json | jq -r .data.key",
     description: "Pipe the secret into another tool"
@@ -29216,8 +29269,20 @@ var create2 = make29("create", {
   {
     command: "samva api-keys create --name deploy --full-access --expires-at 2027-01-01T00:00:00Z"
   }
-]), withHandler(({ name, description, expiresAt, grant, fullAccess, dryRun, json }) => withJsonQuiet(json, gen2(function* () {
-  const access = yield* accessFromFlags(grant, fullAccess);
+]), withHandler(({
+  name,
+  description,
+  expiresAt,
+  grant,
+  mailboxPermission,
+  mailbox,
+  sendMode,
+  namespace,
+  fullAccess,
+  dryRun,
+  json
+}) => withJsonQuiet(json, gen2(function* () {
+  const access = yield* accessFromFlags(grant, fullAccess, { permissions: mailboxPermission, mailboxIds: mailbox, sendMode }, namespace);
   const expires = yield* match(expiresAt, {
     onNone: () => void_3,
     onSome: parseExpiresAt
@@ -29233,7 +29298,11 @@ var create2 = make29("create", {
   });
   if (dryRun) {
     if (json) {
-      return yield* printJson({ dryRun: true, action: "api-keys.create", request: payload });
+      return yield* printJson({
+        dryRun: true,
+        action: "api-keys.create",
+        request: payload
+      });
     }
     return yield* printFields([
       ["Action", "api-keys.create"],
@@ -29256,13 +29325,17 @@ var update3 = make29("update", {
   id: idArgument,
   name: String9("name").pipe(withDescription2("New key name"), optional4),
   description: String9("description").pipe(withDescription2("New description"), optional4),
+  sendMode: Literals3("send-mode", mailboxSendModes).pipe(withDescription2("Change a mailbox key's send mode: approval holds each send for a person other than the key, send releases them. Takes a person signed in with samva login"), optional4),
   dryRun: dryRunFlag,
   json: jsonFlag
-}).pipe(withDescription3("Rename an API key or change its description. Access is fixed at creation; create a new key to change it."), withExamples([{ command: "samva api-keys update key_abc123 --name ci-prod --dry-run" }]), withHandler(({ id, name, description, dryRun, json }) => withJsonQuiet(json, gen2(function* () {
-  if (isNone2(name) && isNone2(description)) {
+}).pipe(withDescription3("Rename an API key, change its description, or change a mailbox key's send mode. Its other access is fixed at creation; create a new key to change it."), withExamples([
+  { command: "samva api-keys update key_abc123 --name ci-prod --dry-run" },
+  { command: "samva api-keys update key_abc123 --send-mode approval" }
+]), withHandler(({ id, name, description, sendMode, dryRun, json }) => withJsonQuiet(json, gen2(function* () {
+  if (isNone2(name) && isNone2(description) && isNone2(sendMode)) {
     return yield* new CliUsageError({
       code: "update_required",
-      message: "Pass --name, --description, or both."
+      message: "Pass --name, --description, --send-mode, or a combination."
     });
   }
   const payload = yield* decodeRequest(ApiKeysUpdateRequestJson, {
@@ -29270,6 +29343,10 @@ var update3 = make29("update", {
     ...match(description, {
       onNone: () => ({}),
       onSome: (value) => ({ description: value })
+    }),
+    ...match(sendMode, {
+      onNone: () => ({}),
+      onSome: (value) => ({ mailboxes: { sendMode: value } })
     })
   });
   if (dryRun) {
@@ -29285,7 +29362,8 @@ var update3 = make29("update", {
       ["Action", "api-keys.update"],
       ["API key", id],
       ["Name", payload.name],
-      ["Description", payload.description]
+      ["Description", payload.description],
+      ["Send mode", payload.mailboxes?.sendMode]
     ]);
   }
   const client = yield* getClientProvider;
@@ -66402,7 +66480,7 @@ var refusalNext = (failure) => {
     case "ForbiddenError":
       return "Use a credential that may read mailboxes and follow the API message.";
     case "ResourceNotFoundError":
-      return "Run samva mailboxes list to find the mailboxes this credential can read, then retry with those --mailbox ids.";
+      return "Run samva mailboxes list to find the mailboxes this credential can read, then retry with those mailbox ids.";
     case "CursorExpiredError":
       return "Events after your cursor expired. Read current state from the API and reconnect without --cursor.";
     case "ValidationError":
@@ -66529,12 +66607,16 @@ var tailEvents = (options) => gen2(function* () {
   })), mapError4(streamError), options.limit === undefined ? (stream) => stream : take3(options.limit), interruptWhen2(interrupted), runForEach2(options.onEvent), raceFirst2(interrupted.pipe(andThen2(sleep2(HANDLER_DRAIN)))))));
 });
 var mailboxesEventsCommand = make29("events", {
+  mailbox: String10("mailbox-id").pipe(withDescription4("Mailboxes to follow; omit to follow every mailbox the credential reads"), withSchema3(MailboxId), atLeast3(0)),
   cursor: String9("cursor").pipe(withDescription2("Replay events after a cursor from an earlier event frame, then go live"), optional4),
-  mailbox: String9("mailbox").pipe(withSchema2(MailboxId), atLeast2(0)),
   limit: Int5("limit").pipe(optional4),
   noReconnect: Boolean6("no-reconnect").pipe(withDefault5(false), withDescription2("Exit non-zero with the last cursor when the connection drops, instead of reconnecting from it"))
 }).pipe(withDescription3("Tail mailbox events, one record per line; --jsonl wraps each in a result envelope; a dropped connection reconnects from the last cursor; Ctrl+C exits cleanly"), withExamples([
-  { command: "samva mailboxes events --mailbox mbx_1234567890123456 --limit 10" },
+  { command: "samva mailboxes events mbx_1234567890123456 --limit 10" },
+  {
+    command: "samva mailboxes events mbx_1234567890123456 mbx_6543210987654321 --jsonl",
+    description: "Follow several mailboxes"
+  },
   { command: "samva mailboxes events --jsonl", description: "Stream envelopes for automation" },
   { command: "samva mailboxes events --cursor <cursor-from-an-event-frame>" },
   {
@@ -71573,7 +71655,7 @@ var decodeThreadPage = decoder3(WireThreadPage, "thread page");
 var decodeMessage = decoder3(WireMessage, "message");
 
 // src/commands/mailboxes.ts
-var mailboxFlag = String9("mailbox").pipe(withDescription2("Mailbox ID"), withSchema2(MailboxId));
+var mailboxIdArgument = String10("mailbox-id").pipe(withSchema3(MailboxId));
 var messageIdArgument = String10("message-id").pipe(withSchema3(MessageId));
 var optional6 = (name) => String9(name).pipe(optional4);
 var pageFlags2 = {
@@ -71616,7 +71698,7 @@ var chatContent = (channel, flags) => gen2(function* () {
   }
   if (channel !== "whatsapp")
     return yield* usage2("mailbox_chat_template", "A template sends on WhatsApp only.");
-  const templateId = yield* decodeUnknownEffect2(TemplateId)(flags.template.value).pipe(mapError2(() => usage2("mailbox_chat_template", "--template must be an approved template id (tmpl_\u2026).")));
+  const templateId = yield* decodeEffect2(TemplateId)(flags.template.value).pipe(mapError2(() => usage2("mailbox_chat_template", "--template must be an approved template id (tmpl_\u2026).")));
   const dataText = getOrUndefined(flags.data);
   if (dataText === undefined)
     return { templateId };
@@ -71734,7 +71816,6 @@ var create9 = make29("create", {
     return yield* printJson(data);
   yield* printMailbox(data);
 })));
-var mailboxIdArgument = String10("mailbox-id").pipe(withSchema3(MailboxId));
 var get22 = make29("get", { id: mailboxIdArgument, json: jsonFlag }).pipe(withDescription3("Inspect a mailbox's endpoints and settings"), withHandler(({ id, json }) => gen2(function* () {
   const raw = yield* getMailboxJson("Could not read mailbox", `/v1/mailboxes/${id}`);
   const result = yield* decodeMailbox(raw);
@@ -71793,7 +71874,7 @@ var update9 = make29("update", {
   yield* json ? printJson(result) : printMailbox(result);
 })));
 var endpointAdd = make29("add", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   channel: channelFlag2,
   address: String9("address").pipe(withDescription2("The address to add: an email address such as billing@acme.samva.email, or on whatsapp and sms a number you connected, in E.164 form such as +14155550123")),
   displayName: String9("display-name").pipe(withDescription2("The sender name messages from this endpoint carry"), optional4),
@@ -71801,10 +71882,10 @@ var endpointAdd = make29("add", {
   json: jsonFlag
 }).pipe(withDescription3("Add an endpoint on a channel (email by default) to a mailbox"), withExamples([
   {
-    command: "samva mailboxes endpoints add --mailbox mbx_1234567890123456 --address billing@acme.samva.email"
+    command: "samva mailboxes endpoints add mbx_1234567890123456 --address billing@acme.samva.email"
   },
   {
-    command: "samva mailboxes endpoints add --mailbox mbx_1234567890123456 --channel whatsapp --address +14155550123",
+    command: "samva mailboxes endpoints add mbx_1234567890123456 --channel whatsapp --address +14155550123",
     description: "Add a connected WhatsApp number"
   }
 ]), withHandler(({ mailbox, channel, address, displayName, dryRun, json }) => gen2(function* () {
@@ -71836,8 +71917,8 @@ var endpointAdd = make29("add", {
 })));
 var endpointIdArgument = String10("endpoint-id").pipe(withSchema3(MailboxEndpointId));
 var endpointUpdate = make29("update", {
+  mailbox: mailboxIdArgument,
   endpointId: endpointIdArgument,
-  mailbox: mailboxFlag,
   displayName: String9("display-name").pipe(withDescription2("The sender name messages from this endpoint carry"), optional4),
   clearDisplayName: Boolean6("clear-display-name").pipe(withDescription2("Send under the mailbox's name again"), withDefault5(false)),
   makeDefault: Boolean6("default").pipe(withDescription2("Start new conversations from this endpoint on its channel"), withDefault5(false)),
@@ -71845,7 +71926,7 @@ var endpointUpdate = make29("update", {
   json: jsonFlag
 }).pipe(withDescription3("Rename an endpoint's sender or make it the mailbox's default"), withExamples([
   {
-    command: 'samva mailboxes endpoints update mbxep_1234567890123456 --mailbox mbx_1234567890123456 --display-name "Acme Billing" --default'
+    command: 'samva mailboxes endpoints update mbx_1234567890123456 mbxep_1234567890123456 --display-name "Acme Billing" --default'
   }
 ]), withHandler(({ endpointId, mailbox, displayName, clearDisplayName, makeDefault, dryRun, json }) => gen2(function* () {
   if (isSome2(displayName) && clearDisplayName)
@@ -71879,14 +71960,14 @@ var endpointUpdate = make29("update", {
   yield* json ? printJson(result) : printMailbox(result);
 })));
 var endpointRemove = make29("remove", {
+  mailbox: mailboxIdArgument,
   endpointId: endpointIdArgument,
-  mailbox: mailboxFlag,
   dryRun: Boolean6("dry-run").pipe(withDefault5(false)),
   yes: Boolean6("yes").pipe(withDefault5(false)),
   json: jsonFlag
 }).pipe(withDescription3("Remove an endpoint from a mailbox; mail sent to it stops reaching the mailbox"), withExamples([
   {
-    command: "samva mailboxes endpoints remove mbxep_1234567890123456 --mailbox mbx_1234567890123456 --yes"
+    command: "samva mailboxes endpoints remove mbx_1234567890123456 mbxep_1234567890123456 --yes"
   }
 ]), withHandler(({ endpointId, mailbox, dryRun, yes, json }) => gen2(function* () {
   if (dryRun)
@@ -71918,7 +71999,7 @@ var lifecycle = (verb) => make29(verb, {
   yield* json ? printJson(result) : printMailbox(result);
 })));
 var actionsList = make29("list", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   ...pageFlags2,
   state: Literals3("state", MailboxActionState.literals).pipe(optional4),
   after: instantFlag("after", "Only actions created after this ISO 8601 instant"),
@@ -71943,8 +72024,8 @@ var actionsList = make29("list", {
   });
 })));
 var actionDecision = (verb) => make29(verb, {
+  mailbox: mailboxIdArgument,
   actionId: String10("action-id").pipe(withSchema3(MailboxActionId)),
-  mailbox: mailboxFlag,
   ...verb === "deny" ? {
     reason: optional6("reason").pipe(withDescription2("Denial reason; defaults to Denied by reviewer."))
   } : {},
@@ -71999,7 +72080,7 @@ var remove9 = make29("remove", {
   yield* log(`Removed mailbox ${id}. The messages it received stay with the organization.`);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
 var threads = make29("threads", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   ...pageFlags2,
   query: optional6("query"),
   folder: Literals3("folder", MailboxThreadFolder2.literals).pipe(optional4),
@@ -72010,37 +72091,35 @@ var threads = make29("threads", {
   before: instantFlag("before", "Only threads whose last activity is before this ISO 8601 instant"),
   json: jsonFlag
 }).pipe(withDescription3("Search and list mailbox threads"), withExamples([
-  { command: "samva mailboxes threads --mailbox mbx_1234567890123456 --query invoice --json" },
+  { command: "samva mailboxes threads mbx_1234567890123456 --query invoice --json" },
   {
-    command: "samva mailboxes threads --mailbox mbx_1234567890123456 --starred --after 2026-10-01T00:00:00Z"
+    command: "samva mailboxes threads mbx_1234567890123456 --starred --after 2026-10-01T00:00:00Z"
   },
-  { command: "samva mailboxes threads --mailbox mbx_1234567890123456 --all --jsonl" }
-]), withHandler(({ mailbox, limit, cursor, all, query, folder, label, unread, starred, after, before, json }) => gen2(function* () {
-  yield* followPages({
-    all,
-    json,
-    cursor,
-    page: (pageCursor) => getMailboxJson("Could not list threads", `/v1/mailboxes/${mailbox}/threads${searchParams({
-      cursor: pageCursor,
-      limit: pageLimit(limit),
-      q: getOrUndefined(query),
-      folder: getOrUndefined(folder),
-      label: getOrUndefined(label),
-      unread: unread ? "true" : undefined,
-      starred: starred ? "true" : undefined,
-      after: getOrUndefined(after),
-      before: getOrUndefined(before)
-    })}`).pipe(flatMap3(decodeThreadPage)),
-    empty: "No threads found.",
-    human: printThread
-  });
+  { command: "samva mailboxes threads mbx_1234567890123456 --all --jsonl" }
+]), withHandler(({ mailbox, limit, cursor, all, query, folder, label, unread, starred, after, before, json }) => followPages({
+  all,
+  json,
+  cursor,
+  page: (pageCursor) => getMailboxJson("Could not list threads", `/v1/mailboxes/${mailbox}/threads${searchParams({
+    cursor: pageCursor,
+    limit: pageLimit(limit),
+    q: getOrUndefined(query),
+    folder: getOrUndefined(folder),
+    label: getOrUndefined(label),
+    unread: unread ? "true" : undefined,
+    starred: starred ? "true" : undefined,
+    after: getOrUndefined(after),
+    before: getOrUndefined(before)
+  })}`).pipe(flatMap3(decodeThreadPage)),
+  empty: "No threads found.",
+  human: printThread
 })));
 var read2 = make29("read", {
+  mailbox: mailboxIdArgument,
   messageId: messageIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Read a mailbox message"), withExamples([
-  { command: "samva mailboxes read msg_1234567890123456 --mailbox mbx_1234567890123456 --json" }
+  { command: "samva mailboxes read mbx_1234567890123456 msg_1234567890123456 --json" }
 ]), withHandler(({ messageId, mailbox, json }) => gen2(function* () {
   const raw = yield* getMailboxJson("Could not read message", `/v1/mailboxes/${mailbox}/messages/${messageId}`);
   const data = yield* decodeMessage(raw);
@@ -72049,7 +72128,7 @@ var read2 = make29("read", {
   yield* printMessage2(data);
 })));
 var send7 = make29("send", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   channel: channelFlag2,
   to: String9("to").pipe(withDescription2("Recipient email address (repeatable), or one phone number in E.164 form"), atLeast2(1)),
   subject: String9("subject").pipe(withDescription2("Email only"), optional4),
@@ -72060,14 +72139,14 @@ var send7 = make29("send", {
   json: jsonFlag
 }).pipe(withDescription3("Send a message from a mailbox: email by default, or to one phone number with --channel whatsapp or sms"), withExamples([
   {
-    command: 'samva mailboxes send --mailbox mbx_1234567890123456 --to recipient@example.com --subject Hello --text "Hello"'
+    command: 'samva mailboxes send mbx_1234567890123456 --to recipient@example.com --subject Hello --text "Hello"'
   },
   {
-    command: `samva mailboxes send --mailbox mbx_1234567890123456 --channel whatsapp --to +14155550123 --template tmpl_1234567890123456 --data '{"name":"Ada"}'`,
+    command: `samva mailboxes send mbx_1234567890123456 --channel whatsapp --to +14155550123 --template tmpl_1234567890123456 --data '{"name":"Ada"}'`,
     description: "Open a WhatsApp conversation with an approved template"
   },
   {
-    command: 'samva mailboxes send --mailbox mbx_1234567890123456 --channel sms --to +14155550123 --text "Your order shipped."'
+    command: 'samva mailboxes send mbx_1234567890123456 --channel sms --to +14155550123 --text "Your order shipped."'
   }
 ]), withHandler(({
   mailbox,
@@ -72119,18 +72198,18 @@ var send7 = make29("send", {
 })));
 var messageChannel = (mailbox, messageId) => getMailboxJson("Could not read message", `/v1/mailboxes/${mailbox}/messages/${messageId}`).pipe(flatMap3((raw) => decodeUnknownEffect2(Struct({ channel: Literals(["email", "whatsapp", "sms"]) }))(raw).pipe(map7(({ channel }) => channel), mapError2(() => new SamvaCliError({ message: "The API answered with an unreadable message." })))));
 var reply2 = make29("reply", {
+  mailbox: mailboxIdArgument,
   messageId: messageIdArgument,
-  mailbox: mailboxFlag,
   ...bodyFlags,
   ...chatOnlyFlags,
   all: Boolean6("all").pipe(withDefault5(false)),
   json: jsonFlag
 }).pipe(withDescription3("Reply to a message; --all includes the other recipients. A WhatsApp or SMS message is answered on its thread, with --text or a WhatsApp --template"), withExamples([
   {
-    command: 'samva mailboxes reply msg_1234567890123456 --mailbox mbx_1234567890123456 --text "Thanks" --all'
+    command: 'samva mailboxes reply mbx_1234567890123456 msg_1234567890123456 --text "Thanks" --all'
   },
   {
-    command: "samva mailboxes reply msg_1234567890123456 --mailbox mbx_1234567890123456 --template tmpl_1234567890123456",
+    command: "samva mailboxes reply mbx_1234567890123456 msg_1234567890123456 --template tmpl_1234567890123456",
     description: "Answer a WhatsApp thread whose 24-hour service window has closed"
   }
 ]), withHandler(({ messageId, mailbox, text, html, template, data, idempotencyKey, all, json }) => gen2(function* () {
@@ -72158,8 +72237,8 @@ var reply2 = make29("reply", {
 })));
 var actionIdArgument = String10("action-id").pipe(withSchema3(MailboxActionId));
 var actionGet = make29("get", {
+  mailbox: mailboxIdArgument,
   actionId: actionIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Read a mailbox action and its current send progress"), withHandler(({ actionId, mailbox, json }) => gen2(function* () {
   const client = yield* getClientProvider;
@@ -72169,8 +72248,8 @@ var actionGet = make29("get", {
   yield* printAction(data);
 })));
 var actionCancel = make29("cancel", {
+  mailbox: mailboxIdArgument,
   actionId: actionIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Cancel an unaccepted send as a permitted person signed in with samva login"), withHandler(({ actionId, mailbox, json }) => gen2(function* () {
   const client = yield* getClientProvider;
@@ -72184,8 +72263,8 @@ var actionCancel = make29("cancel", {
   ]);
 })));
 var actionRetry = make29("retry", {
+  mailbox: mailboxIdArgument,
   actionId: actionIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Resume an eligible ended execution as a permitted person; preserves content and deadline"), withHandler(({ actionId, mailbox, json }) => gen2(function* () {
   const client = yield* getClientProvider;
@@ -72199,14 +72278,14 @@ var actionRetry = make29("retry", {
   ]);
 })));
 var quarantineList = make29("list", {
-  mailbox: mailboxFlag,
+  mailbox: mailboxIdArgument,
   ...pageFlags2,
   after: instantFlag("after", "Only messages held after this ISO 8601 instant"),
   before: instantFlag("before", "Only messages held before this ISO 8601 instant"),
   json: jsonFlag
 }).pipe(withDescription3("List held messages without their bodies"), withExamples([
-  { command: "samva mailboxes quarantine list --mailbox mbx_1234567890123456 --json" },
-  { command: "samva mailboxes quarantine list --mailbox mbx_1234567890123456 --all --jsonl" }
+  { command: "samva mailboxes quarantine list mbx_1234567890123456 --json" },
+  { command: "samva mailboxes quarantine list mbx_1234567890123456 --all --jsonl" }
 ]), withHandler(({ mailbox, limit, cursor, all, after, before, json }) => gen2(function* () {
   const client = yield* getClientProvider;
   yield* followPages({
@@ -72225,12 +72304,12 @@ var quarantineList = make29("list", {
   });
 })));
 var release2 = make29("release", {
+  mailbox: mailboxIdArgument,
   messageId: messageIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Release a held message as a person signed in with samva login"), withExamples([
   {
-    command: "samva mailboxes quarantine release msg_1234567890123456 --mailbox mbx_1234567890123456"
+    command: "samva mailboxes quarantine release mbx_1234567890123456 msg_1234567890123456"
   }
 ]), withHandler(({ messageId, mailbox, json }) => gen2(function* () {
   const client = yield* getClientProvider;
@@ -72242,12 +72321,12 @@ var release2 = make29("release", {
 var discard = make29("discard", {
   dryRun: Boolean6("dry-run").pipe(withDefault5(false)),
   yes: Boolean6("yes").pipe(withDefault5(false)),
+  mailbox: mailboxIdArgument,
   messageId: messageIdArgument,
-  mailbox: mailboxFlag,
   json: jsonFlag
 }).pipe(withDescription3("Discard a held message for good as a person signed in with samva login"), withExamples([
   {
-    command: "samva mailboxes quarantine discard msg_1234567890123456 --mailbox mbx_1234567890123456"
+    command: "samva mailboxes quarantine discard mbx_1234567890123456 msg_1234567890123456"
   }
 ]), withHandler(({ messageId, mailbox, dryRun, yes, json }) => gen2(function* () {
   if (dryRun)
@@ -75659,7 +75738,7 @@ var TemplatesGroup = class extends make37("Templates").add(get5("templatesList",
     TemplatesPublish500,
     TemplatesPublish504.pipe(status(504))
   ]
-}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "templates.publish").annotate(Summary, "Publish an exact template commit").annotate(Description, "Builds an exact Git commit and entry path, stores the immutable compiled IR and its assets, records the input contract it validates against, and makes that publication current."), get5("templatesGetPublication", "/v1/templates/:id/publications/:publicationId", {
+}).middleware(ApiKeySecurityMiddleware).annotate(Identifier, "templates.publish").annotate(Summary, "Publish an exact template commit").annotate(Description, "Builds an exact Git commit and entry path, stores the immutable compiled IR and its assets, records the input contract it validates against, and makes that publication current. A commit that compiles to the same build as an existing publication makes that publication current again instead of recording another."), get5("templatesGetPublication", "/v1/templates/:id/publications/:publicationId", {
   params: TemplatesGetPublicationPathParams,
   success: TemplatesGetPublication200,
   error: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samva/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Samva CLI — email and platform operations from your terminal",
   "keywords": [
     "cli",
@@ -62,10 +62,10 @@
     "vitest": "^5.0.3"
   },
   "optionalDependencies": {
-    "@samva/cli-darwin-arm64": "0.16.0",
-    "@samva/cli-darwin-x64": "0.16.0",
-    "@samva/cli-linux-arm64": "0.16.0",
-    "@samva/cli-linux-x64": "0.16.0"
+    "@samva/cli-darwin-arm64": "0.17.0",
+    "@samva/cli-darwin-x64": "0.17.0",
+    "@samva/cli-linux-arm64": "0.17.0",
+    "@samva/cli-linux-x64": "0.17.0"
   },
   "engines": {
     "node": ">=18"