@clankmates/cli 0.7.1 → 0.8.0

package/README.md

@@ -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.1
+mise install npm:@clankmates/cli@0.8.0
 ```
 
 For local development in this repository:
@@ -95,6 +95,8 @@ 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:

package/package.json

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

package/skills/codex/clankmates/SKILL.md

@@ -166,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;
     }
 
@@ -84,7 +90,7 @@ export async function runChannelCommand(
         cursor: stringFlag(args.flags, "cursor"),
       });
 
-      printChannelCollection(context.outputMode, io, response);
+      printChannelCollection(args, context.outputMode, io, response);
       return;
     }
 
@@ -283,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;
       }
 
@@ -292,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;
     }
 
@@ -368,6 +389,7 @@ async function maybeStoreChannelToken(
 }
 
 function printChannelCollection(
+  args: ParsedArgs,
   outputMode: "json" | "table",
   io: Io,
   response: {
@@ -376,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;
   }
 
@@ -388,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 }) {

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,11 +94,11 @@ 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;
     }
@@ -245,7 +246,7 @@ async function runScreeningCommand(
         channelToken,
       });
 
-      printEmailIntakeCollection(context, io, response);
+      printEmailIntakeCollection(args, context, io, response);
       return;
     }
 
@@ -256,7 +257,7 @@ async function runScreeningCommand(
         channelToken,
       });
 
-      printEmailIntakeCollection(context, io, response);
+      printEmailIntakeCollection(args, context, io, response);
       return;
     }
 
@@ -462,6 +463,7 @@ function looksLikeEmailAddress(value: string): boolean {
 }
 
 async function printThreadCollection(
+  args: ParsedArgs,
   context: CommandContext,
   io: Io,
   response: {
@@ -471,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();
   }
 
@@ -501,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 }>;
@@ -518,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}`,
@@ -579,7 +595,7 @@ function renderThreadWithMessages(
       ]),
     ),
     renderSection("Messages", messageBlocks),
-    renderPagination(messages.nextCursor),
+    renderPagination(pagination?.nextCursor, pagination?.nextCommand),
   ]);
 }
 
@@ -606,6 +622,7 @@ function renderMessage(
 }
 
 function printEmailIntakeCollection(
+  args: ParsedArgs,
   context: CommandContext,
   io: Io,
   response: {
@@ -617,11 +634,11 @@ function printEmailIntakeCollection(
     io,
     context.outputMode,
     context.outputMode === "json"
-      ? {
+      ? paginatedJson(args, {
           items: response.items,
           nextCursor: response.nextCursor,
-        }
-      : renderEmailIntakeCollection(response),
+        })
+      : renderEmailIntakeCollection(args, response),
   );
 }
 
@@ -640,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: {
@@ -678,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."
@@ -701,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,7 +58,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;
     }
 
@@ -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;
     }
 
@@ -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/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(
@@ -325,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],
           },
@@ -352,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],
           },
@@ -450,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,
@@ -522,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(
@@ -563,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],
           },
@@ -579,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],
           },
@@ -627,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(
@@ -644,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(
@@ -670,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(
@@ -692,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,
@@ -706,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,
@@ -802,7 +802,7 @@ const HELP_ROOT = group(
             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]`,
+              `${CLI_NAME} inbox screening list [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   LIMIT_OPTION,
@@ -816,7 +816,7 @@ const HELP_ROOT = group(
             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]`,
+              `${CLI_NAME} inbox screening processing [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   LIMIT_OPTION,

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, "'\\''")}'`;
+}