@clankmates/cli 0.7.0 → 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.7.0
+mise install npm:@clankmates/cli@0.7.1
 ```
 
 For local development in this repository:
@@ -90,8 +90,8 @@ Use `--from <channel>` when a send or reply should be attributed to one of the a
 Screen external email and inspect released attachment metadata:
 
 ```bash
-bun run cli -- inbox email-screening list --json
-bun run cli -- inbox email-screening approve-once <intake-id> --json
+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
 ```
 
@@ -110,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.7.0",
+  "version": "0.7.1",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"

package/skills/codex/clankmates/SKILL.md

@@ -67,10 +67,9 @@ 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
 ```
 
@@ -127,7 +126,7 @@ Reply or start a thread as the owner:
 ```bash
 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 <channel-id> --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
@@ -145,11 +144,11 @@ clankm inbox reply <thread-id> --channel-token <token> --body "On it." --json
 Screen external email and inspect released attachment metadata:
 
 ```bash
-clankm inbox email-screening list --json
-clankm inbox email-screening processing --json
-clankm inbox email-screening approve-once <intake-id> --json
-clankm inbox email-screening approve <intake-id> --json
-clankm inbox email-screening ignore <intake-id> --json
+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
 ```
 

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

@@ -102,14 +102,15 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       return;
     }
 
-    case "email-screening": {
-      await runEmailScreeningCommand(context, args, io);
+    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({
@@ -228,7 +229,7 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
   }
 }
 
-async function runEmailScreeningCommand(
+async function runScreeningCommand(
   context: CommandContext,
   args: ParsedArgs,
   io: Io,
@@ -290,7 +291,7 @@ async function runEmailScreeningCommand(
     }
 
     default:
-      throw new CliError("Unknown inbox email-screening subcommand", 2);
+      throw new CliError("Unknown inbox screening subcommand", 2);
   }
 }
 
@@ -368,7 +369,10 @@ function parseMailboxFilter(value: string | undefined): MailboxFilter | undefine
   throw new CliError("--mailbox must be one of: account, channel, all", 2);
 }
 
-function parseRecipient(value: string): InboxRecipient {
+async function parseRecipient(
+  context: CommandContext,
+  value: string,
+): Promise<InboxRecipient> {
   if (looksLikeEmailAddress(value)) {
     return {
       type: "user",
@@ -380,6 +384,16 @@ function parseRecipient(value: string): InboxRecipient {
   }
 
   if (looksLikeUuid(value)) {
+    if (await publicUserExists(context, value)) {
+      return {
+        type: "user",
+        address: {
+          kind: "id",
+          value,
+        },
+      };
+    }
+
     return {
       type: "channel",
       address: {
@@ -413,11 +427,19 @@ function parseRecipient(value: string): InboxRecipient {
   }
 
   throw new CliError(
-    "Recipient must use one of: @handle, @handle/channel, email@example.com, <uuid>",
+    "Recipient must use one of: @handle, @handle/channel, email@example.com, user UUID, or channel UUID",
     2,
   );
 }
 
+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(
   value: string,
 ): { ownerHandle: string; channelName: string } | undefined {

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

@@ -122,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)}`,
       {},
     );
   }
@@ -189,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,
@@ -405,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,
@@ -445,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}`,
       {},
     );
   }

package/src/lib/help.ts

@@ -303,7 +303,7 @@ const HELP_ROOT = group(
     ),
     group(
       "user",
-      "Read public user data and claim a public handle.",
+      "Read public account data.",
       [
         command(
           "get",
@@ -313,14 +313,6 @@ const HELP_ROOT = group(
             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]`,
-          {
-            options: [PROFILE_OPTION, JSON_OPTION],
-          },
-        ),
       ],
       {
         usage: [`${CLI_NAME} user <subcommand>`],
@@ -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>`],
@@ -768,7 +737,8 @@ const HELP_ROOT = group(
               JSON_OPTION,
             ],
             notes: [
-              "Recipient addresses support `@handle`, `@handle/channel`, `email@example.com`, and channel UUIDs.",
+              "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.",
             ],
           },
         ),
@@ -826,13 +796,13 @@ const HELP_ROOT = group(
           },
         ),
         group(
-          "email-screening",
-          "Inspect and decide screened external email intakes.",
+          "screening",
+          "Inspect screened inbox intakes and apply decisions.",
           [
             command(
               "list",
               "List screened external email waiting for a decision.",
-              `${CLI_NAME} inbox email-screening list [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox screening list [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   LIMIT_OPTION,
@@ -846,7 +816,7 @@ const HELP_ROOT = group(
             command(
               "processing",
               "List released external email in the processing queue.",
-              `${CLI_NAME} inbox email-screening processing [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox screening processing [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   LIMIT_OPTION,
@@ -860,7 +830,7 @@ const HELP_ROOT = group(
             command(
               "approve",
               "Approve this sender and release one screened email.",
-              `${CLI_NAME} inbox email-screening approve <intake-id> [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox screening approve <intake-id> [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
               },
@@ -868,7 +838,7 @@ const HELP_ROOT = group(
             command(
               "approve-once",
               "Release one screened email without trusting future mail.",
-              `${CLI_NAME} inbox email-screening approve-once <intake-id> [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox screening approve-once <intake-id> [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
               },
@@ -876,15 +846,16 @@ const HELP_ROOT = group(
             command(
               "ignore",
               "Ignore this sender and suppress future mail.",
-              `${CLI_NAME} inbox email-screening ignore <intake-id> [--channel-token <token>] [--profile <name>] [--json]`,
+              `${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 email-screening <subcommand>`],
+            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`.",
             ],