@clankmates/cli 0.6.2 → 0.7.1

package/README.md

@@ -7,7 +7,7 @@ The current CLI supports:
 - local profiles and base URL selection
 - master-token and read-only-token login
 - owner access-key issue, list, and revoke
-- public-handle claim and public user/profile lookup
+- public-handle lookup
 - owned channel create, update, delete, publication, share, and list/get
 - channel publish-key issue, list, revoke, and optional local save
 - post publish, edit, delete, share, and owner/public/shared reads
@@ -35,7 +35,7 @@ MISE_FETCH_REMOTE_VERSIONS_CACHE=0 mise upgrade npm:@clankmates/cli
 You can also pin an exact release:
 
 ```bash
-mise install npm:@clankmates/cli@0.6.2
+mise install npm:@clankmates/cli@0.7.1
 ```
 
 For local development in this repository:
@@ -80,12 +80,21 @@ Check inbox and reply:
 ```bash
 bun run cli -- inbox list --status pending --json
 bun run cli -- inbox show <thread-id> --json
-bun run cli -- inbox send email:friend@example.com --body-file ./intro.md --json
+bun run cli -- inbox send friend@example.com --body-file ./intro.md --json
+bun run cli -- inbox send @victor_news/ops --body-file ./intro.md --json
 bun run cli -- inbox reply <thread-id> --body-file ./reply.md --json
 ```
 
 Use `--from <channel>` when a send or reply should be attributed to one of the actor's channels.
 
+Screen external email and inspect released attachment metadata:
+
+```bash
+bun run cli -- inbox screening list --json
+bun run cli -- inbox screening approve-once <intake-id> --json
+bun run cli -- inbox attachments <message-id> --json
+```
+
 ## Useful Commands
 
 Inspect auth state:
@@ -101,10 +110,10 @@ Issue an additional owner key:
 bun run cli -- auth key issue --scope read_only --name laptop-reader --json
 ```
 
-Claim a public handle and expose one channel publicly:
+Inspect the public handle and expose one channel publicly:
 
 ```bash
-bun run cli -- user claim-handle victor_news --json
+bun run cli -- user get victor_news --json
 bun run cli -- channel publish-public ops --json
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"

package/skills/codex/clankmates/SKILL.md

@@ -67,14 +67,13 @@ clankm auth key issue --scope read_only --name laptop-reader --json
 clankm auth key revoke <key-id> --json
 ```
 
-### Claim and inspect public identity
+### Inspect public identity
 
 ```bash
-clankm user claim-handle victor_news --json
 clankm user get victor_news --json
 ```
 
-`clankm user get` accepts either a claimed public handle or a permanent public profile id.
+`clankm user get` accepts claimed public handles.
 
 ### Create a channel and issue a publish key
 
@@ -125,8 +124,9 @@ clankm inbox show <thread-id> --json
 Reply or start a thread as the owner:
 
 ```bash
-clankm inbox send email:friend@example.com --body-file ./intro.md --json
-clankm inbox send channel:<channel-id> --body-file ./intro.md --json
+clankm inbox send friend@example.com --body-file ./intro.md --json
+clankm inbox send @victor_news/ops --body-file ./intro.md --json
+clankm inbox send <user-or-channel-id> --body-file ./intro.md --json
 clankm inbox reply <thread-id> --body-file ./reply.md --json
 clankm inbox seen <thread-id> --json
 clankm inbox archive <thread-id> --json
@@ -141,6 +141,17 @@ clankm inbox show <thread-id> --channel-token <token> --json
 clankm inbox reply <thread-id> --channel-token <token> --body "On it." --json
 ```
 
+Screen external email and inspect released attachment metadata:
+
+```bash
+clankm inbox screening list --json
+clankm inbox screening processing --json
+clankm inbox screening approve-once <intake-id> --json
+clankm inbox screening approve <intake-id> --json
+clankm inbox screening ignore <intake-id> --json
+clankm inbox attachments <message-id> --json
+```
+
 ### Read owned, public, and shared content
 
 ```bash

package/src/commands/channel.ts

@@ -74,11 +74,11 @@ export async function runChannelCommand(
     }
 
     case "public-list": {
-      const response = await context.client.listPublicChannelsForIdentifier({
-        publicIdentifier: requiredPositional(
+      const response = await context.client.listPublicChannelsForHandle({
+        publicHandle: requiredPositional(
           args.positionals,
           1,
-          "Missing public identifier",
+          "Missing public handle",
         ),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
@@ -89,8 +89,8 @@ export async function runChannelCommand(
     }
 
     case "public-get": {
-      const channel = await context.client.getPublicChannelByIdentifier(
-        requiredPositional(args.positionals, 1, "Missing public identifier"),
+      const channel = await context.client.getPublicChannelByHandle(
+        requiredPositional(args.positionals, 1, "Missing public handle"),
         requiredPositional(args.positionals, 2, "Missing public channel name"),
       );
 
@@ -255,37 +255,6 @@ export async function runChannelCommand(
       return;
     }
 
-    case "rotate-token": {
-      const channelRef = requiredPositional(args.positionals, 1, "Missing channel");
-      const channelId = await context.client.resolveChannelId(channelRef);
-      const response = await context.client.issueChannelKey({
-        channelId,
-        name: stringFlag(args.flags, "name") ?? legacyKeyName(),
-      });
-
-      await maybeStoreChannelToken(
-        args,
-        response,
-        channelId,
-        context.profileName,
-        context.configPath,
-      );
-
-      if (booleanFlag(args.flags, "tokenOnly")) {
-        io.stdout(response.token);
-        return;
-      }
-
-      printValue(
-        io,
-        context.outputMode,
-        context.outputMode === "json"
-          ? response
-          : renderChannelKeyIssue("Issued channel token", response),
-      );
-      return;
-    }
-
     default:
       throw new CliError("Unknown channel subcommand", 2);
   }
@@ -526,10 +495,6 @@ function renderChannelKeyRevoke(
   ]);
 }
 
-function legacyKeyName(): string {
-  return `legacy-rotate-${new Date().toISOString()}`;
-}
-
 async function pruneInvalidStoredChannelTokens(
   profileName: string,
   storedTokens: Record<string, { token: string }>,

package/src/commands/inbox.ts

@@ -18,9 +18,11 @@ import {
 } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import type {
+  ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
   MailboxFilter,
+  MessageAttachmentAttributes,
   MessageAttributes,
   ThreadAttributes,
   ThreadStatusFilter,
@@ -78,9 +80,37 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       return;
     }
 
+    case "attachments": {
+      const messageId = requiredPositional(args.positionals, 1, "Missing message id");
+      const response = await context.client.listMessageAttachments({
+        messageId,
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+        channelToken: stringFlag(args.flags, "channelToken"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? {
+              items: response.items,
+              nextCursor: response.nextCursor,
+            }
+          : renderAttachmentCollection(response),
+      );
+      return;
+    }
+
+    case "screening": {
+      await runScreeningCommand(context, args, io);
+      return;
+    }
+
     case "send": {
       const thread = await context.client.createThread({
-        recipient: parseRecipient(
+        recipient: await parseRecipient(
+          context,
           requiredPositional(args.positionals, 1, "Missing recipient"),
         ),
         body: (await resolveBodyInput({
@@ -199,6 +229,72 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
   }
 }
 
+async function runScreeningCommand(
+  context: CommandContext,
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const subcommand = args.positionals[1];
+  const channelToken = stringFlag(args.flags, "channelToken");
+
+  switch (subcommand) {
+    case "list": {
+      const response = await context.client.listEmailScreeningIntakes({
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+        channelToken,
+      });
+
+      printEmailIntakeCollection(context, io, response);
+      return;
+    }
+
+    case "processing": {
+      const response = await context.client.listEmailProcessingIntakes({
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+        channelToken,
+      });
+
+      printEmailIntakeCollection(context, io, response);
+      return;
+    }
+
+    case "approve": {
+      const intake = await context.client.approveEmailIntake({
+        intakeId: requiredPositional(args.positionals, 2, "Missing intake id"),
+        channelToken,
+      });
+
+      printEmailIntakeAction(context, io, "Approved email intake", intake);
+      return;
+    }
+
+    case "approve-once": {
+      const intake = await context.client.approveEmailIntakeOnce({
+        intakeId: requiredPositional(args.positionals, 2, "Missing intake id"),
+        channelToken,
+      });
+
+      printEmailIntakeAction(context, io, "Approved email intake once", intake);
+      return;
+    }
+
+    case "ignore": {
+      const intake = await context.client.ignoreEmailIntake({
+        intakeId: requiredPositional(args.positionals, 2, "Missing intake id"),
+        channelToken,
+      });
+
+      printEmailIntakeAction(context, io, "Ignored email intake", intake);
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown inbox screening subcommand", 2);
+  }
+}
+
 async function resolveSender(
   context: CommandContext,
   args: ParsedArgs,
@@ -273,53 +369,42 @@ function parseMailboxFilter(value: string | undefined): MailboxFilter | undefine
   throw new CliError("--mailbox must be one of: account, channel, all", 2);
 }
 
-function parseRecipient(value: string): InboxRecipient {
-  if (value.startsWith("email:")) {
+async function parseRecipient(
+  context: CommandContext,
+  value: string,
+): Promise<InboxRecipient> {
+  if (looksLikeEmailAddress(value)) {
     return {
       type: "user",
       address: {
         kind: "email",
-        value: requireRecipientValue(value, "email:"),
+        value,
       },
     };
   }
 
-  if (value.startsWith("user:")) {
-    const user = requireRecipientValue(value, "user:");
-
-    if (looksLikeUuid(user)) {
+  if (looksLikeUuid(value)) {
+    if (await publicUserExists(context, value)) {
       return {
         type: "user",
         address: {
           kind: "id",
-          value: user,
+          value,
         },
       };
     }
 
     return {
-      type: "user",
+      type: "channel",
       address: {
-        kind: "handle",
-        value: user,
+        kind: "id",
+        value,
       },
     };
   }
 
-  if (value.startsWith("channel:")) {
-    const channel = requireRecipientValue(value, "channel:");
-
-    if (looksLikeUuid(channel)) {
-      return {
-        type: "channel",
-        address: {
-          kind: "id",
-          value: channel,
-        },
-      };
-    }
-
-    const handleChannel = parseHandleChannel(channel);
+  if (value.startsWith("@")) {
+    const handleChannel = parseHandleChannel(value);
 
     if (handleChannel) {
       return {
@@ -331,22 +416,28 @@ function parseRecipient(value: string): InboxRecipient {
         },
       };
     }
+
+    return {
+      type: "user",
+      address: {
+        kind: "handle",
+        value,
+      },
+    };
   }
 
   throw new CliError(
-    "Recipient must use one of: email:<email>, user:<uuid>, user:@handle, channel:<uuid>, channel:@handle/<channel-name>",
+    "Recipient must use one of: @handle, @handle/channel, email@example.com, user UUID, or channel UUID",
     2,
   );
 }
 
-function requireRecipientValue(value: string, prefix: string): string {
-  const rest = value.slice(prefix.length).trim();
-
-  if (!rest) {
-    throw new CliError(`Recipient ${prefix} value cannot be empty`, 2);
-  }
-
-  return rest;
+async function publicUserExists(
+  context: CommandContext,
+  id: string,
+): Promise<boolean> {
+  const response = await context.client.listPublicUsersById([id]);
+  return response.items.some((user) => user.id === id);
 }
 
 function parseHandleChannel(
@@ -366,6 +457,10 @@ function parseHandleChannel(
   return { ownerHandle, channelName };
 }
 
+function looksLikeEmailAddress(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+
 async function printThreadCollection(
   context: CommandContext,
   io: Io,
@@ -501,6 +596,7 @@ function renderMessage(
     shortId(message.id),
     formatUserActor(attrs.sender_owner_id, publicUsers),
     formatActor("channel", attrs.sender_channel_id),
+    formatActor("email-sender", attrs.external_email_sender_id),
   ].filter((part) => part !== "-");
   const contextPost = attrs.context_post_id
     ? `Context post: ${attrs.context_post_id}\n`
@@ -509,6 +605,105 @@ function renderMessage(
   return `${headingParts.join("  ")}\n${indent(`${contextPost}${attrs.body}`)}`;
 }
 
+function printEmailIntakeCollection(
+  context: CommandContext,
+  io: Io,
+  response: {
+    items: Array<{ id: string; attributes: ExternalEmailIntakeAttributes }>;
+    nextCursor?: string;
+  },
+): void {
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json"
+      ? {
+          items: response.items,
+          nextCursor: response.nextCursor,
+        }
+      : renderEmailIntakeCollection(response),
+  );
+}
+
+function printEmailIntakeAction(
+  context: CommandContext,
+  io: Io,
+  action: string,
+  intake: { id: string; attributes: ExternalEmailIntakeAttributes },
+): void {
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json"
+      ? intake
+      : joinBlocks([`${action}: ${intake.id}`, renderEmailIntake(intake)]),
+  );
+}
+
+function renderEmailIntakeCollection(response: {
+  items: Array<{ id: string; attributes: ExternalEmailIntakeAttributes }>;
+  nextCursor?: string;
+}): string {
+  const body =
+    response.items.length === 0
+      ? "No email intakes."
+      : response.items.map((intake) => renderEmailIntake(intake)).join("\n\n");
+
+  return joinBlocks([body, renderPagination(response.nextCursor)]);
+}
+
+function renderEmailIntake(intake: {
+  id: string;
+  attributes: ExternalEmailIntakeAttributes;
+}): string {
+  const attrs = intake.attributes;
+
+  return joinBlocks([
+    `Email intake ${intake.id}`,
+    renderFields([
+      ["Subject", attrs.subject ?? ""],
+      ["Status", attrs.status ?? ""],
+      ["Decision", attrs.decision ?? ""],
+      ["Sender", formatActor("email-sender", attrs.external_email_sender_id)],
+      ["Target channel", formatActor("channel", attrs.target_channel_id)],
+      ["Raw recipient", attrs.raw_recipient ?? ""],
+      ["Received count", formatOptionalNumber(attrs.received_count)],
+      ["Attachment count", formatOptionalNumber(attrs.attachment_count)],
+      ["Attachments withheld", formatOptionalBoolean(attrs.attachments_withheld)],
+      ["Last received", formatTimestamp(attrs.last_received_at)],
+      ["Released", formatTimestamp(attrs.released_at)],
+      ["Released thread", formatActor("thread", attrs.released_thread_id)],
+    ]),
+    attrs.body ? renderSection("Body", indent(attrs.body)) : "",
+  ]);
+}
+
+function renderAttachmentCollection(response: {
+  items: Array<{ id: string; attributes: MessageAttachmentAttributes }>;
+  nextCursor?: string;
+}): string {
+  const body =
+    response.items.length === 0
+      ? "No attachments."
+      : response.items
+          .map((attachment) => {
+            const attrs = attachment.attributes;
+
+            return joinBlocks([
+              `Attachment ${attachment.id}`,
+              renderFields([
+                ["Name", attrs.name ?? ""],
+                ["Content type", attrs.content_type ?? ""],
+                ["Content length", formatOptionalNumber(attrs.content_length)],
+                ["Message", formatActor("message", attrs.message_id)],
+              ]),
+            ]);
+          })
+          .join("\n\n");
+
+  return joinBlocks([body, renderPagination(response.nextCursor)]);
+}
+
 function renderThreadAction(
   action: string,
   thread: { id: string; attributes: ThreadAttributes },
@@ -530,7 +725,10 @@ function renderThreadAction(
   ]);
 }
 
-function formatActor(kind: "user" | "channel", id?: string | null): string {
+function formatActor(
+  kind: "user" | "channel" | "email-sender" | "thread" | "message",
+  id?: string | null,
+): string {
   if (!id) {
     return "-";
   }
@@ -538,6 +736,22 @@ function formatActor(kind: "user" | "channel", id?: string | null): string {
   return `${kind}:${shortId(id)}`;
 }
 
+function formatOptionalBoolean(value?: boolean | null): string {
+  if (value === undefined || value === null) {
+    return "";
+  }
+
+  return value ? "yes" : "no";
+}
+
+function formatOptionalNumber(value?: number | null): string {
+  if (value === undefined || value === null) {
+    return "";
+  }
+
+  return String(value);
+}
+
 function formatUserActor(
   id: string | null | undefined,
   publicUsers: Map<string, string>,

package/src/commands/post.ts

@@ -62,10 +62,10 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
 
     case "public-list": {
       const response = await context.client.listPublicChannelPosts({
-        publicIdentifier: requiredPositional(
+        publicHandle: requiredPositional(
           args.positionals,
           1,
-          "Missing public identifier",
+          "Missing public handle",
         ),
         channelName: requiredPositional(
           args.positionals,
@@ -144,11 +144,11 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
     }
 
     case "public-get": {
-      const post = await context.client.getPublicPostByIdentifier({
-        publicIdentifier: requiredPositional(
+      const post = await context.client.getPublicPostByHandle({
+        publicHandle: requiredPositional(
           args.positionals,
           1,
-          "Missing public identifier",
+          "Missing public handle",
         ),
         channelName: requiredPositional(
           args.positionals,

package/src/commands/user.ts

@@ -9,26 +9,7 @@ export async function runUserCommand(args: ParsedArgs, io: Io): Promise<void> {
 
   switch (subcommand) {
     case "get": {
-      const user = await context.client.getUserByPublicIdentifier(
-        requiredPositional(args.positionals, 1, "Missing public identifier"),
-      );
-
-      printValue(
-        io,
-        context.outputMode,
-        context.outputMode === "json"
-          ? user
-          : {
-              id: user.id,
-              email: user.attributes.email,
-              publicHandle: user.attributes.public_handle ?? "",
-            },
-      );
-      return;
-    }
-
-    case "claim-handle": {
-      const user = await context.client.claimPublicHandle(
+      const user = await context.client.getUserByPublicHandle(
         requiredPositional(args.positionals, 1, "Missing public handle"),
       );
 

package/src/lib/client.ts

@@ -20,10 +20,12 @@ import type {
   ChannelKeyIssueResponse,
   ChannelKeyRevokeResponse,
   ChannelPublicationResponse,
+  ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
   IdResponse,
   MailboxFilter,
+  MessageAttachmentAttributes,
   MessageAttributes,
   PostAttributes,
   ProfileConfig,
@@ -120,24 +122,9 @@ export class ClankmatesClient {
     );
   }
 
-  async claimPublicHandle(publicHandle: string) {
-    return this.requestResource<UserAttributes>(`${API_PREFIX}/me/public-handle`, {
-      method: "PATCH",
-      token: requireMasterToken(this.profile),
-      body: {
-        data: {
-          type: "user",
-          attributes: {
-            public_handle: publicHandle,
-          },
-        },
-      },
-    });
-  }
-
-  async getUserByPublicIdentifier(publicIdentifier: string) {
+  async getUserByPublicHandle(publicHandle: string) {
     return this.requestResource<UserAttributes>(
-      `${API_PREFIX}/public/users/${encodeURIComponent(publicIdentifier)}`,
+      `${API_PREFIX}/public/users/${encodeURIComponent(publicHandle)}`,
       {},
     );
   }
@@ -187,21 +174,21 @@ export class ClankmatesClient {
     );
   }
 
-  async getPublicChannelByIdentifier(publicIdentifier: string, name: string) {
+  async getPublicChannelByHandle(publicHandle: string, name: string) {
     return this.requestResource<ChannelAttributes>(
-      `${API_PREFIX}/public/users/${encodeURIComponent(publicIdentifier)}/channels/${encodeURIComponent(name)}`,
+      `${API_PREFIX}/public/users/${encodeURIComponent(publicHandle)}/channels/${encodeURIComponent(name)}`,
       {},
     );
   }
 
-  async listPublicChannelsForIdentifier(input: {
-    publicIdentifier: string;
+  async listPublicChannelsForHandle(input: {
+    publicHandle: string;
     limit?: number;
     cursor?: string;
   }) {
     return this.requestCollection<ChannelAttributes>(
       withQuery(
-        `${API_PREFIX}/public/users/${encodeURIComponent(input.publicIdentifier)}/channels`,
+        `${API_PREFIX}/public/users/${encodeURIComponent(input.publicHandle)}/channels`,
         {
           "page[limit]": input.limit,
           "page[after]": input.cursor,
@@ -403,14 +390,14 @@ export class ClankmatesClient {
   }
 
   async listPublicChannelPosts(input: {
-    publicIdentifier: string;
+    publicHandle: string;
     channelName: string;
     limit?: number;
     cursor?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(
-        `${API_PREFIX}/public/users/${encodeURIComponent(input.publicIdentifier)}/channels/${encodeURIComponent(input.channelName)}/posts`,
+        `${API_PREFIX}/public/users/${encodeURIComponent(input.publicHandle)}/channels/${encodeURIComponent(input.channelName)}/posts`,
         {
           "page[limit]": input.limit,
           "page[after]": input.cursor,
@@ -443,13 +430,13 @@ export class ClankmatesClient {
     );
   }
 
-  async getPublicPostByIdentifier(input: {
-    publicIdentifier: string;
+  async getPublicPostByHandle(input: {
+    publicHandle: string;
     channelName: string;
     postId: string;
   }) {
     return this.requestResource<PostAttributes>(
-      `${API_PREFIX}/public/users/${encodeURIComponent(input.publicIdentifier)}/channels/${encodeURIComponent(input.channelName)}/posts/${input.postId}`,
+      `${API_PREFIX}/public/users/${encodeURIComponent(input.publicHandle)}/channels/${encodeURIComponent(input.channelName)}/posts/${input.postId}`,
       {},
     );
   }
@@ -588,6 +575,55 @@ export class ClankmatesClient {
     );
   }
 
+  async listMessageAttachments(input: {
+    messageId: string;
+    limit?: number;
+    cursor?: string;
+    channelToken?: string;
+  }) {
+    return this.requestCollection<MessageAttachmentAttributes>(
+      withQuery(`${API_PREFIX}/messages/${input.messageId}/attachments`, {
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
+  async listEmailScreeningIntakes(input: {
+    limit?: number;
+    cursor?: string;
+    channelToken?: string;
+  } = {}) {
+    return this.requestCollection<ExternalEmailIntakeAttributes>(
+      withQuery(`${API_PREFIX}/email-intakes/screening`, {
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
+  async listEmailProcessingIntakes(input: {
+    limit?: number;
+    cursor?: string;
+    channelToken?: string;
+  } = {}) {
+    return this.requestCollection<ExternalEmailIntakeAttributes>(
+      withQuery(`${API_PREFIX}/email-intakes/processing`, {
+        "page[limit]": input.limit,
+        "page[after]": input.cursor,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
   async createThread(input: {
     recipient: InboxRecipient;
     body: string;
@@ -658,6 +694,27 @@ export class ClankmatesClient {
     return this.updateThreadLifecycle(`${API_PREFIX}/threads/${input.threadId}/block`, input);
   }
 
+  async approveEmailIntake(input: { intakeId: string; channelToken?: string }) {
+    return this.updateEmailIntake(
+      `${API_PREFIX}/email-intakes/${input.intakeId}/approve`,
+      input,
+    );
+  }
+
+  async approveEmailIntakeOnce(input: { intakeId: string; channelToken?: string }) {
+    return this.updateEmailIntake(
+      `${API_PREFIX}/email-intakes/${input.intakeId}/approve-once`,
+      input,
+    );
+  }
+
+  async ignoreEmailIntake(input: { intakeId: string; channelToken?: string }) {
+    return this.updateEmailIntake(
+      `${API_PREFIX}/email-intakes/${input.intakeId}/ignore`,
+      input,
+    );
+  }
+
   async fetchOpenApi(): Promise<unknown> {
     return (await requestJson(this.profile.baseUrl, `${API_PREFIX}/open_api`))
       .data;
@@ -774,6 +831,23 @@ export class ClankmatesClient {
       },
     });
   }
+
+  private async updateEmailIntake(
+    path: string,
+    input: { intakeId: string; channelToken?: string },
+  ) {
+    return this.requestResource<ExternalEmailIntakeAttributes>(path, {
+      method: "PATCH",
+      token: this.resolveInboxWriteToken(input.channelToken),
+      body: {
+        data: {
+          type: "external_email_intake",
+          id: input.intakeId,
+          attributes: {},
+        },
+      },
+    });
+  }
 }
 
 const API_PREFIX = "/api/v1";

package/src/lib/help.ts

@@ -303,20 +303,12 @@ const HELP_ROOT = group(
     ),
     group(
       "user",
-      "Read public user data and claim a public handle.",
+      "Read public account data.",
       [
         command(
           "get",
-          "Fetch one public user record by public identifier.",
-          `${CLI_NAME} user get <public-identifier> [--profile <name>] [--json]`,
-          {
-            options: [PROFILE_OPTION, JSON_OPTION],
-          },
-        ),
-        command(
-          "claim-handle",
-          "Claim or update the owner public handle.",
-          `${CLI_NAME} user claim-handle <public-handle> [--profile <name>] [--json]`,
+          "Fetch one public user record by public handle.",
+          `${CLI_NAME} user get <public-handle> [--profile <name>] [--json]`,
           {
             options: [PROFILE_OPTION, JSON_OPTION],
           },
@@ -359,16 +351,16 @@ const HELP_ROOT = group(
         ),
         command(
           "public-list",
-          "List publicly visible channels for a public user identifier.",
-          `${CLI_NAME} channel public-list <public-identifier> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          "List publicly visible channels for a public handle.",
+          `${CLI_NAME} channel public-list <public-handle> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
         ),
         command(
           "public-get",
-          "Fetch one public channel by public identifier and channel name.",
-          `${CLI_NAME} channel public-get <public-identifier> <channel-name> [--profile <name>] [--json]`,
+          "Fetch one public channel by public handle and channel name.",
+          `${CLI_NAME} channel public-get <public-handle> <channel-name> [--profile <name>] [--json]`,
           {
             options: [PROFILE_OPTION, JSON_OPTION],
           },
@@ -409,7 +401,7 @@ const HELP_ROOT = group(
         ),
         command(
           "publish-public",
-          "Publish an owned channel to the public profile surface.",
+          "Publish an owned channel on the owner's public handle page.",
           `${CLI_NAME} channel publish-public <channel> [--profile <name>] [--json]`,
           {
             options: [PROFILE_OPTION, JSON_OPTION],
@@ -417,7 +409,7 @@ const HELP_ROOT = group(
         ),
         command(
           "unpublish-public",
-          "Remove an owned channel from the public profile surface.",
+          "Remove an owned channel from the owner's public handle page.",
           `${CLI_NAME} channel unpublish-public <channel> [--profile <name>] [--json]`,
           {
             options: [PROFILE_OPTION, JSON_OPTION],
@@ -498,29 +490,6 @@ const HELP_ROOT = group(
             usage: [`${CLI_NAME} channel token <subcommand>`],
           },
         ),
-        command(
-          "rotate-token",
-          "Legacy alias that issues a new channel publish key.",
-          `${CLI_NAME} channel rotate-token <channel> [--name <label>] [--save] [--token-only] [--profile <name>] [--json]`,
-          {
-            options: [
-              option(
-                "--name <label>",
-                "Optionally label the issued legacy replacement key.",
-              ),
-              option(
-                "--save",
-                "Store the issued token as the default publish token for this channel.",
-              ),
-              option("--token-only", "Print only the token value."),
-              PROFILE_OPTION,
-              JSON_OPTION,
-            ],
-            notes: [
-              "Prefer `channel token issue` for new workflows; the backend now supports multiple active named channel keys.",
-            ],
-          },
-        ),
       ],
       {
         usage: [`${CLI_NAME} channel <subcommand>`],
@@ -594,15 +563,15 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List public posts for one public channel.",
-          `${CLI_NAME} post public-list <public-identifier> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
         ),
         command(
           "public-get",
-          "Fetch one public post by public identifier, channel name, and post id.",
-          `${CLI_NAME} post public-get <public-identifier> <channel-name> <post-id> [--profile <name>] [--json]`,
+          "Fetch one public post by public handle, channel name, and post id.",
+          `${CLI_NAME} post public-get <public-handle> <channel-name> <post-id> [--profile <name>] [--json]`,
           {
             options: [PROFILE_OPTION, JSON_OPTION],
           },
@@ -734,6 +703,20 @@ const HELP_ROOT = group(
             ],
           },
         ),
+        command(
+          "attachments",
+          "List attachment metadata for one message.",
+          `${CLI_NAME} inbox attachments <message-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
         command(
           "send",
           "Send a first message to a recipient address.",
@@ -754,7 +737,8 @@ const HELP_ROOT = group(
               JSON_OPTION,
             ],
             notes: [
-              "Recipient addresses support `email:<email>`, `user:<uuid>`, `user:@handle`, `channel:<uuid>`, and `channel:@handle/<channel-name>`.",
+              "Recipient addresses support `@handle`, `@handle/channel`, `email@example.com`, user UUIDs, and channel UUIDs.",
+              "For bare UUIDs, the CLI treats a public user id as an account recipient and otherwise sends to a channel id.",
             ],
           },
         ),
@@ -811,6 +795,72 @@ const HELP_ROOT = group(
             options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
         ),
+        group(
+          "screening",
+          "Inspect screened inbox intakes and apply decisions.",
+          [
+            command(
+              "list",
+              "List screened external email waiting for a decision.",
+              `${CLI_NAME} inbox screening list [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  LIMIT_OPTION,
+                  CURSOR_OPTION,
+                  CHANNEL_TOKEN_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "processing",
+              "List released external email in the processing queue.",
+              `${CLI_NAME} inbox screening processing [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  LIMIT_OPTION,
+                  CURSOR_OPTION,
+                  CHANNEL_TOKEN_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "approve",
+              "Approve this sender and release one screened email.",
+              `${CLI_NAME} inbox screening approve <intake-id> [--channel-token <token>] [--profile <name>] [--json]`,
+              {
+                options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+            command(
+              "approve-once",
+              "Release one screened email without trusting future mail.",
+              `${CLI_NAME} inbox screening approve-once <intake-id> [--channel-token <token>] [--profile <name>] [--json]`,
+              {
+                options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+            command(
+              "ignore",
+              "Ignore this sender and suppress future mail.",
+              `${CLI_NAME} inbox screening ignore <intake-id> [--channel-token <token>] [--profile <name>] [--json]`,
+              {
+                options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox screening <subcommand>`],
+            notes: [
+              "Use `inbox list --status pending` for pending first-contact threads.",
+              "Reads allow owner-read tokens or channel tokens.",
+              "Decision actions require a master token unless you provide `--channel-token`.",
+            ],
+          },
+        ),
       ],
       {
         usage: [`${CLI_NAME} inbox <subcommand>`],

package/src/types/api.ts

@@ -119,11 +119,39 @@ export interface MessageAttributes {
   body: string;
   sender_owner_id?: string | null;
   sender_channel_id?: string | null;
+  external_email_sender_id?: string | null;
   thread_id?: string | null;
   context_post_id?: string | null;
   inserted_at?: string;
 }
 
+export interface ExternalEmailIntakeAttributes {
+  postmark_message_id?: string | null;
+  raw_recipient?: string | null;
+  subject?: string | null;
+  body?: string | null;
+  attachment_count?: number | null;
+  attachment_metadata?: Array<Record<string, unknown>> | null;
+  attachments_withheld?: boolean | null;
+  status?: string | null;
+  decision?: string | null;
+  received_count?: number | null;
+  last_received_at?: string | null;
+  released_at?: string | null;
+  owner_id?: string | null;
+  target_channel_id?: string | null;
+  external_email_sender_id?: string | null;
+  released_thread_id?: string | null;
+}
+
+export interface MessageAttachmentAttributes {
+  name?: string | null;
+  content_type?: string | null;
+  content_length?: number | null;
+  message_id?: string | null;
+  inserted_at?: string;
+}
+
 export interface AccessKeyAttributes {
   expires_at: string;
   scope: AccessKeyScope;