@clankmates/cli 0.7.0 → 0.8.0

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.8.0
 ```
 
 For local development in this repository:
@@ -90,11 +90,13 @@ 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
 ```
 
+Paginated list commands accept `--limit <n>` and `--cursor <cursor>`. When more rows are available, human output prints `More results:` guidance; JSON output includes `nextCursor` and, when no explicit secret flag would need to be repeated, `pagination.nextCommand`.
+
 ## Useful Commands
 
 Inspect auth state:
@@ -110,10 +112,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.8.0",
   "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
 ```
 
@@ -167,6 +166,8 @@ clankm channel shared-get <share-token> --json
 clankm post shared-get <share-token> --json
 ```
 
+For paginated collection reads, follow `pagination.nextCommand` in JSON output when present. If it is absent, reuse the original command with `nextCursor`. In human-readable output, follow the printed `More results:` guidance.
+
 ## Failure Handling
 
 - If `doctor` says `openApiOk: false`, stop and report the base URL or connectivity issue.

package/src/commands/auth.ts

@@ -98,6 +98,7 @@ export async function runAuthCommand(args: ParsedArgs, io: Io): Promise<void> {
       const { profileName, profile } = resolveProfile(
         config,
         stringFlag(args.flags, "profile"),
+        stringFlag(args.flags, "baseUrl"),
       );
       const outputMode = resolveOutputMode(profile, args.flags);
       const explicitChannelToken = stringFlag(args.flags, "channelToken");
@@ -163,6 +164,7 @@ export async function runAuthCommand(args: ParsedArgs, io: Io): Promise<void> {
       const { profileName, profile } = resolveProfile(
         config,
         stringFlag(args.flags, "profile"),
+        stringFlag(args.flags, "baseUrl"),
       );
       const outputMode = resolveOutputMode(profile, args.flags);
       const resolvedMasterToken = resolveMasterToken(profile);
@@ -207,6 +209,7 @@ async function runAccessKeyCommand(
   const { profileName, profile } = resolveProfile(
     config,
     stringFlag(args.flags, "profile"),
+    stringFlag(args.flags, "baseUrl"),
   );
   const outputMode = resolveOutputMode(profile, args.flags);
   const client = new ClankmatesClient(profile);

package/src/commands/channel.ts

@@ -9,8 +9,14 @@ import {
 import { storeChannelToken, updateProfile } from "../lib/config";
 import { createCommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
-import { joinBlocks, renderFields, renderTokenAction } from "../lib/human";
+import {
+  joinBlocks,
+  renderFields,
+  renderPagination,
+  renderTokenAction,
+} from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
+import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type {
   ChannelAttributes,
   ChannelDiagnosticsResponse,
@@ -40,7 +46,7 @@ export async function runChannelCommand(
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printChannelCollection(context.outputMode, io, response);
+      printChannelCollection(args, context.outputMode, io, response);
       return;
     }
 
@@ -74,23 +80,23 @@ 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"),
       });
 
-      printChannelCollection(context.outputMode, io, response);
+      printChannelCollection(args, context.outputMode, io, response);
       return;
     }
 
     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 +261,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);
   }
@@ -314,7 +289,13 @@ async function runChannelTokenCommand(
       });
 
       if (context.outputMode === "json") {
-        printJson(io, { items: response.items, nextCursor: response.nextCursor });
+        printJson(
+          io,
+          paginatedJson(args, {
+            items: response.items,
+            nextCursor: response.nextCursor,
+          }),
+        );
         return;
       }
 
@@ -323,6 +304,15 @@ async function runChannelTokenCommand(
         context.outputMode,
         response.items.map((item) => formatChannelKeyRow(item)),
       );
+      const pagination = paginationInfo(args, response.nextCursor);
+      const message = renderPagination(
+        pagination?.nextCursor,
+        pagination?.nextCommand,
+      );
+
+      if (message) {
+        io.stdout(message);
+      }
       return;
     }
 
@@ -399,6 +389,7 @@ async function maybeStoreChannelToken(
 }
 
 function printChannelCollection(
+  args: ParsedArgs,
   outputMode: "json" | "table",
   io: Io,
   response: {
@@ -407,10 +398,13 @@ function printChannelCollection(
   },
 ): void {
   if (outputMode === "json") {
-    printJson(io, {
-      items: response.items,
-      nextCursor: response.nextCursor,
-    });
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
     return;
   }
 
@@ -419,6 +413,15 @@ function printChannelCollection(
     outputMode,
     response.items.map((item) => formatChannelRow(item)),
   );
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
+  );
+
+  if (message) {
+    io.stdout(message);
+  }
 }
 
 function formatChannelRecord(channel: { id: string; attributes: ChannelAttributes }) {
@@ -526,10 +529,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/feed.ts

@@ -7,7 +7,9 @@ import {
 } from "../lib/args";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
+import { renderPagination } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
+import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type { PostAttributes } from "../types/api";
 
 export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
@@ -22,7 +24,7 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printFeedResponse(context, io, response);
+      printFeedResponse(args, context, io, response);
       return;
     }
 
@@ -40,7 +42,7 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printFeedResponse(context, io, response);
+      printFeedResponse(args, context, io, response);
       return;
     }
 
@@ -58,6 +60,7 @@ async function resolveChannelId(
 }
 
 function printFeedResponse(
+  args: ParsedArgs,
   context: CommandContext,
   io: Io,
   response: {
@@ -66,21 +69,31 @@ function printFeedResponse(
   },
 ): void {
   if (context.outputMode === "json") {
-    printJson(io, {
-      items: response.items,
-      nextCursor: response.nextCursor,
-    });
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
     return;
   }
 
-  printValue(
-    io,
-    context.outputMode,
-    response.items.map((item) => ({
-      id: item.id,
-      source: item.attributes.source,
-      date: item.attributes.updated_at ?? item.attributes.inserted_at ?? "",
-      body: item.attributes.body,
-    })),
+  const rows = response.items.map((item) => ({
+    id: item.id,
+    source: item.attributes.source,
+    date: item.attributes.updated_at ?? item.attributes.inserted_at ?? "",
+    body: item.attributes.body,
+  }));
+  printValue(io, context.outputMode, rows);
+
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
   );
+
+  if (message) {
+    io.stdout(message);
+  }
 }

package/src/commands/inbox.ts

@@ -17,6 +17,7 @@ import {
   shortId,
 } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
+import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type {
   ExternalEmailIntakeAttributes,
   InboxRecipient,
@@ -44,7 +45,7 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelToken,
       });
 
-      await printThreadCollection(context, io, response, channelToken);
+      await printThreadCollection(args, context, io, response, channelToken);
       return;
     }
 
@@ -70,12 +71,12 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         io,
         context.outputMode,
         context.outputMode === "json"
-          ? {
+          ? paginatedJson(args, {
               thread,
               messages: messages.items,
               nextCursor: messages.nextCursor,
-            }
-          : renderThreadWithMessages(thread, messages, publicUsers),
+            })
+          : renderThreadWithMessages(args, thread, messages, publicUsers),
       );
       return;
     }
@@ -93,23 +94,24 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         io,
         context.outputMode,
         context.outputMode === "json"
-          ? {
+          ? paginatedJson(args, {
               items: response.items,
               nextCursor: response.nextCursor,
-            }
-          : renderAttachmentCollection(response),
+            })
+          : renderAttachmentCollection(args, response),
       );
       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 +230,7 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
   }
 }
 
-async function runEmailScreeningCommand(
+async function runScreeningCommand(
   context: CommandContext,
   args: ParsedArgs,
   io: Io,
@@ -244,7 +246,7 @@ async function runEmailScreeningCommand(
         channelToken,
       });
 
-      printEmailIntakeCollection(context, io, response);
+      printEmailIntakeCollection(args, context, io, response);
       return;
     }
 
@@ -255,7 +257,7 @@ async function runEmailScreeningCommand(
         channelToken,
       });
 
-      printEmailIntakeCollection(context, io, response);
+      printEmailIntakeCollection(args, context, io, response);
       return;
     }
 
@@ -290,7 +292,7 @@ async function runEmailScreeningCommand(
     }
 
     default:
-      throw new CliError("Unknown inbox email-screening subcommand", 2);
+      throw new CliError("Unknown inbox screening subcommand", 2);
   }
 }
 
@@ -368,7 +370,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 +385,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 +428,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 {
@@ -440,6 +463,7 @@ function looksLikeEmailAddress(value: string): boolean {
 }
 
 async function printThreadCollection(
+  args: ParsedArgs,
   context: CommandContext,
   io: Io,
   response: {
@@ -449,10 +473,13 @@ async function printThreadCollection(
   channelToken?: string,
 ): Promise<void> {
   if (context.outputMode === "json") {
-    printJson(io, {
-      items: response.items,
-      nextCursor: response.nextCursor,
-    });
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
     return Promise.resolve();
   }
 
@@ -479,9 +506,19 @@ async function printThreadCollection(
       expiresAt: item.attributes.expires_at ?? "",
     })),
   );
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
+  );
+
+  if (message) {
+    io.stdout(message);
+  }
 }
 
 function renderThreadWithMessages(
+  args: ParsedArgs,
   thread: { id: string; attributes: ThreadAttributes },
   messages: {
     items: Array<{ id: string; attributes: MessageAttributes }>;
@@ -496,6 +533,7 @@ function renderThreadWithMessages(
       : messages.items
           .map((message) => renderMessage(message, publicUsers))
           .join("\n\n");
+  const pagination = paginationInfo(args, messages.nextCursor);
 
   return joinBlocks([
     `Thread ${thread.id}`,
@@ -557,7 +595,7 @@ function renderThreadWithMessages(
       ]),
     ),
     renderSection("Messages", messageBlocks),
-    renderPagination(messages.nextCursor),
+    renderPagination(pagination?.nextCursor, pagination?.nextCommand),
   ]);
 }
 
@@ -584,6 +622,7 @@ function renderMessage(
 }
 
 function printEmailIntakeCollection(
+  args: ParsedArgs,
   context: CommandContext,
   io: Io,
   response: {
@@ -595,11 +634,11 @@ function printEmailIntakeCollection(
     io,
     context.outputMode,
     context.outputMode === "json"
-      ? {
+      ? paginatedJson(args, {
           items: response.items,
           nextCursor: response.nextCursor,
-        }
-      : renderEmailIntakeCollection(response),
+        })
+      : renderEmailIntakeCollection(args, response),
   );
 }
 
@@ -618,16 +657,23 @@ function printEmailIntakeAction(
   );
 }
 
-function renderEmailIntakeCollection(response: {
-  items: Array<{ id: string; attributes: ExternalEmailIntakeAttributes }>;
-  nextCursor?: string;
-}): string {
+function renderEmailIntakeCollection(
+  args: ParsedArgs,
+  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)]);
+  const pagination = paginationInfo(args, response.nextCursor);
+  return joinBlocks([
+    body,
+    renderPagination(pagination?.nextCursor, pagination?.nextCommand),
+  ]);
 }
 
 function renderEmailIntake(intake: {
@@ -656,10 +702,13 @@ function renderEmailIntake(intake: {
   ]);
 }
 
-function renderAttachmentCollection(response: {
-  items: Array<{ id: string; attributes: MessageAttachmentAttributes }>;
-  nextCursor?: string;
-}): string {
+function renderAttachmentCollection(
+  args: ParsedArgs,
+  response: {
+    items: Array<{ id: string; attributes: MessageAttachmentAttributes }>;
+    nextCursor?: string;
+  },
+): string {
   const body =
     response.items.length === 0
       ? "No attachments."
@@ -679,7 +728,11 @@ function renderAttachmentCollection(response: {
           })
           .join("\n\n");
 
-  return joinBlocks([body, renderPagination(response.nextCursor)]);
+  const pagination = paginationInfo(args, response.nextCursor);
+  return joinBlocks([
+    body,
+    renderPagination(pagination?.nextCursor, pagination?.nextCommand),
+  ]);
 }
 
 function renderThreadAction(

package/src/commands/post.ts

@@ -10,12 +10,14 @@ import { resolveBodyInput } from "../lib/body-input";
 import { createCommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
 import {
-  formatTimestamp,
-  joinBlocks,
   renderBodyBlock,
   renderFields,
+  formatTimestamp,
+  joinBlocks,
+  renderPagination,
 } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
+import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type { PostAttributes, ShareTokenResponse } from "../types/api";
 
 export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
@@ -56,16 +58,16 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printPostCollection(context.outputMode, io, response);
+      printPostCollection(args, context.outputMode, io, response);
       return;
     }
 
     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,
@@ -76,7 +78,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printPostCollection(context.outputMode, io, response);
+      printPostCollection(args, context.outputMode, io, response);
       return;
     }
 
@@ -87,7 +89,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printPostCollection(context.outputMode, io, response);
+      printPostCollection(args, context.outputMode, io, response);
       return;
     }
 
@@ -144,11 +146,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,
@@ -218,6 +220,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
 }
 
 function printPostCollection(
+  args: ParsedArgs,
   outputMode: "json" | "table",
   io: Io,
   response: {
@@ -226,10 +229,13 @@ function printPostCollection(
   },
 ): void {
   if (outputMode === "json") {
-    printJson(io, {
-      items: response.items,
-      nextCursor: response.nextCursor,
-    });
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
     return;
   }
 
@@ -243,6 +249,16 @@ function printPostCollection(
       body: item.attributes.body,
     })),
   );
+
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
+  );
+
+  if (message) {
+    io.stdout(message);
+  }
 }
 
 function renderPostDetail(

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/config.ts

@@ -115,7 +115,11 @@ export function resolveProfileName(config: ConfigFile, profileName?: string): st
   return profileName ?? process.env.CLANKMATES_PROFILE ?? config.activeProfile;
 }
 
-export function resolveProfile(config: ConfigFile, profileName?: string): { profileName: string; profile: ProfileConfig } {
+export function resolveProfile(
+  config: ConfigFile,
+  profileName?: string,
+  baseUrl?: string,
+): { profileName: string; profile: ProfileConfig } {
   const resolvedName = resolveProfileName(config, profileName);
   const profile = config.profiles[resolvedName];
 
@@ -127,8 +131,8 @@ export function resolveProfile(config: ConfigFile, profileName?: string): { prof
     profileName: resolvedName,
     profile: {
       ...profile,
-      baseUrl: resolveBaseUrl(undefined, profile.baseUrl)
-    }
+      baseUrl: resolveBaseUrl(baseUrl, profile.baseUrl),
+    },
   };
 }
 

package/src/lib/context.ts

@@ -18,7 +18,11 @@ export interface CommandContext {
 export async function createCommandContext(args: ParsedArgs, io: Io): Promise<CommandContext> {
   const configPath = getConfigPath();
   const config = await loadConfig(configPath);
-  const { profileName, profile } = resolveProfile(config, stringFlag(args.flags, "profile"));
+  const { profileName, profile } = resolveProfile(
+    config,
+    stringFlag(args.flags, "profile"),
+    stringFlag(args.flags, "baseUrl"),
+  );
 
   return {
     config,

package/src/lib/help.ts

@@ -88,7 +88,7 @@ const LIMIT_OPTION = option(
   "Limit the number of returned records.",
 );
 const CURSOR_OPTION = option(
-  "--cursor <keyset>",
+  "--cursor <cursor>",
   "Resume from a pagination cursor returned by a prior request.",
 );
 const CHANNEL_TOKEN_OPTION = option(
@@ -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>`],
@@ -333,7 +325,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List owned channels.",
-          `${CLI_NAME} channel list [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} channel list [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
@@ -360,7 +352,7 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List publicly visible channels for a public handle.",
-          `${CLI_NAME} channel public-list <public-handle> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} channel public-list <public-handle> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, 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],
@@ -458,7 +450,7 @@ const HELP_ROOT = group(
             command(
               "list",
               "List channel publish keys for one channel.",
-              `${CLI_NAME} channel token list <channel> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+              `${CLI_NAME} channel token list <channel> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
               {
                 options: [
                   LIMIT_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>`],
@@ -553,7 +522,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List posts for one owned channel.",
-          `${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -594,7 +563,7 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List public posts for one public channel.",
-          `${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
@@ -610,7 +579,7 @@ const HELP_ROOT = group(
         command(
           "shared-list",
           "List posts in a shared channel by share token.",
-          `${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
@@ -658,7 +627,7 @@ const HELP_ROOT = group(
         command(
           "my",
           "List posts from the owner feed.",
-          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -675,7 +644,7 @@ const HELP_ROOT = group(
         command(
           "search",
           "Search the owner feed.",
-          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -701,7 +670,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List inbox threads.",
-          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -723,7 +692,7 @@ const HELP_ROOT = group(
         command(
           "show",
           "Show one thread and its recent messages.",
-          `${CLI_NAME} inbox show <thread-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox show <thread-id> [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               LIMIT_OPTION,
@@ -737,7 +706,7 @@ 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]`,
+          `${CLI_NAME} inbox attachments <message-id> [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               LIMIT_OPTION,
@@ -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 <cursor>] [--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 <cursor>] [--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`.",
             ],

package/src/lib/human.ts

@@ -80,8 +80,17 @@ export function renderBodyBlock(body: string): string {
   return indent(normalized);
 }
 
-export function renderPagination(nextCursor?: string | null): string {
-  return nextCursor ? `More results: --cursor ${nextCursor}` : "";
+export function renderPagination(
+  nextCursor?: string | null,
+  nextCommand?: string,
+): string {
+  if (!nextCursor) {
+    return "";
+  }
+
+  return nextCommand
+    ? `More results: ${nextCommand}`
+    : `More results: --cursor ${nextCursor}`;
 }
 
 export function joinBlocks(blocks: Array<string | undefined | null | false>): string {

package/src/lib/pagination.ts

@@ -0,0 +1,98 @@
+import type { ParsedArgs } from "./args";
+
+const CLI_NAME = "clankm";
+
+const PAGINATION_FLAG_ORDER: Array<
+  [key: string, flag: string]
+> = [
+  ["profile", "--profile"],
+  ["baseUrl", "--base-url"],
+  ["channel", "--channel"],
+  ["channelId", "--channel"],
+  ["status", "--status"],
+  ["mailbox", "--mailbox"],
+  ["limit", "--limit"],
+];
+
+export interface PaginationInfo {
+  nextCursor: string;
+  nextCommand?: string;
+}
+
+export function paginationInfo(
+  args: ParsedArgs,
+  nextCursor?: string | null,
+  options: { json?: boolean } = {},
+): PaginationInfo | undefined {
+  if (!nextCursor) {
+    return undefined;
+  }
+
+  return {
+    nextCursor,
+    nextCommand: args.flags.channelToken
+      ? undefined
+      : nextCommand(args, nextCursor, options),
+  };
+}
+
+export function paginatedJson<T extends object>(
+  args: ParsedArgs,
+  response: T & { nextCursor?: string },
+): T & { nextCursor?: string; pagination?: PaginationInfo } {
+  return {
+    ...response,
+    pagination: paginationInfo(args, response.nextCursor, { json: true }),
+  };
+}
+
+function paginationFlagParts(args: ParsedArgs): string[] {
+  const parts: string[] = [];
+  const seenFlags = new Set<string>();
+
+  for (const [key, flag] of PAGINATION_FLAG_ORDER) {
+    if (seenFlags.has(flag)) {
+      continue;
+    }
+
+    const value = args.flags[key];
+
+    if (typeof value !== "string") {
+      continue;
+    }
+
+    parts.push(flag, value);
+    seenFlags.add(flag);
+  }
+
+  return parts;
+}
+
+function nextCommand(
+  args: ParsedArgs,
+  nextCursor: string,
+  options: { json?: boolean },
+): string {
+  const parts = [
+    CLI_NAME,
+    ...args.commandPath,
+    ...args.positionals,
+    ...paginationFlagParts(args),
+    "--cursor",
+    nextCursor,
+  ];
+
+  if (options.json) {
+    parts.push("--json");
+  }
+
+  return parts.map(shellQuote).join(" ");
+}
+
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
+    return value;
+  }
+
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}