Add automatic pagination support to list and history commands

Author: umair-ably

.claude/skills/ably-new-command/references/patterns.md

@@ -138,6 +138,8 @@ For single-shot publish, REST is preferred (simpler, no connection overhead). Se
 ## History Pattern
 
 ```typescript
+import { collectPaginatedResults } from "../../utils/pagination.js";
+
 async run(): Promise<void> {
   const { args, flags } = await this.parse(MyHistoryCommand);
 
@@ -155,13 +157,22 @@ async run(): Promise<void> {
     };
 
     const history = await channel.history(historyParams);
-    const messages = history.items;
+    const { items: messages, hasMore, pagesConsumed } = await collectPaginatedResults(history, flags.limit);
+
+    if (pagesConsumed > 1 && !this.shouldOutputJson(flags)) {
+      this.log(formatWarning(`Fetched ${pagesConsumed} pages to retrieve ${messages.length} results. Each page incurs additional API requests.`));
+    }
 
     if (this.shouldOutputJson(flags)) {
-      this.logJsonResult({ messages }, flags);
+      this.logJsonResult({ messages, hasMore }, flags);
     } else {
       this.log(formatSuccess(`Found ${messages.length} messages.`));
       // Display each message
+
+      if (hasMore) {
+        const warning = formatLimitWarning(messages.length, flags.limit, "messages");
+        if (warning) this.log(warning);
+      }
     }
   } catch (error) {
     this.fail(error, flags, "history", { channel: args.channel });
@@ -334,11 +345,58 @@ async run(): Promise<void> {
 }
 ```
 
+**Product API list with pagination** (e.g., `push devices list`, `channels list`) — use `collectPaginatedResults` or `collectHttpPaginatedResults`:
+```typescript
+import { collectPaginatedResults, collectHttpPaginatedResults } from "../../utils/pagination.js";
+
+async run(): Promise<void> {
+  const { flags } = await this.parse(MyListCommand);
+
+  try {
+    const rest = await this.createAblyRestClient(flags);
+    if (!rest) return;
+
+    // For SDK methods that return PaginatedResult:
+    const firstPage = await rest.someResource.list({ limit: flags.limit });
+    const { items, hasMore, pagesConsumed } = await collectPaginatedResults(firstPage, flags.limit);
+
+    // For rest.request() that returns HttpPaginatedResponse:
+    // const firstPage = await rest.request("get", "/some/endpoint", 2, { limit: String(flags.limit) });
+    // const { items, hasMore, pagesConsumed } = await collectHttpPaginatedResults(firstPage, flags.limit);
+
+    if (pagesConsumed > 1 && !this.shouldOutputJson(flags)) {
+      this.log(formatWarning(`Fetched ${pagesConsumed} pages to retrieve ${items.length} results. Each page incurs additional API requests.`));
+    }
+
+    if (this.shouldOutputJson(flags)) {
+      this.logJsonResult({ items, hasMore }, flags);
+    } else {
+      this.log(`Found ${items.length} items:\n`);
+      for (const item of items) {
+        this.log(formatHeading(`Item ID: ${item.id}`));
+        this.log(`  ${formatLabel("Type")} ${item.type}`);
+        this.log("");
+      }
+
+      if (hasMore) {
+        const warning = formatLimitWarning(items.length, flags.limit, "items");
+        if (warning) this.log(warning);
+      }
+    }
+  } catch (error) {
+    this.fail(error, flags, "listItems");
+  }
+}
+```
+
 Key conventions for list output:
 - `formatResource()` is for inline resource name references, not for record headings
 - `formatHeading()` is for record heading lines that act as visual separators between multi-field records
 - `formatLabel(text)` for field labels in detail lines (automatically appends `:`)
 - `formatSuccess()` is not used in list commands — it's for confirming an action completed
+- `formatLimitWarning()` should only be shown when `hasMore` is true — it means there are more results beyond the limit
+- Always include `hasMore` in JSON output for paginated commands so consumers know if results are truncated
+- Use `collectPaginatedResults()` for SDK paginated results, `collectHttpPaginatedResults()` for `rest.request()` results, and `collectFilteredPaginatedResults()` when a client-side filter is applied across pages
 
 ---
 

README.md

@@ -536,12 +536,13 @@ List all apps in the current account
 
 ```
 USAGE
-  $ ably apps list [-v] [--json | --pretty-json]
+  $ ably apps list [-v] [--json | --pretty-json] [--limit <value>]
 
 FLAGS
-  -v, --verbose      Output verbose logs
-      --json         Output in JSON format
-      --pretty-json  Output in colorized JSON format
+  -v, --verbose        Output verbose logs
+      --json           Output in JSON format
+      --limit=<value>  [default: 100] Maximum number of results to return (default: 100)
+      --pretty-json    Output in colorized JSON format
 
 DESCRIPTION
   List all apps in the current account
@@ -669,13 +670,14 @@ List channel rules for an app
 
 ```
 USAGE
-  $ ably apps rules list [-v] [--json | --pretty-json] [--app <value>]
+  $ ably apps rules list [-v] [--json | --pretty-json] [--app <value>] [--limit <value>]
 
 FLAGS
-  -v, --verbose      Output verbose logs
-      --app=<value>  The app ID or name (defaults to current app)
-      --json         Output in JSON format
-      --pretty-json  Output in colorized JSON format
+  -v, --verbose        Output verbose logs
+      --app=<value>    The app ID or name (defaults to current app)
+      --json           Output in JSON format
+      --limit=<value>  [default: 100] Maximum number of results to return (default: 100)
+      --pretty-json    Output in colorized JSON format
 
 DESCRIPTION
   List channel rules for an app
@@ -1056,13 +1058,14 @@ List all keys in the app
 
 ```
 USAGE
-  $ ably auth keys list [-v] [--json | --pretty-json] [--app <value>]
+  $ ably auth keys list [-v] [--json | --pretty-json] [--app <value>] [--limit <value>]
 
 FLAGS
-  -v, --verbose      Output verbose logs
-      --app=<value>  The app ID (defaults to current app)
-      --json         Output in JSON format
-      --pretty-json  Output in colorized JSON format
+  -v, --verbose        Output verbose logs
+      --app=<value>    The app ID (defaults to current app)
+      --json           Output in JSON format
+      --limit=<value>  [default: 100] Maximum number of results to return (default: 100)
+      --pretty-json    Output in colorized JSON format
 
 DESCRIPTION
   List all keys in the app
@@ -2227,13 +2230,14 @@ List all integrations
 
 ```
 USAGE
-  $ ably integrations list [-v] [--json | --pretty-json] [--app <value>]
+  $ ably integrations list [-v] [--json | --pretty-json] [--app <value>] [--limit <value>]
 
 FLAGS
-  -v, --verbose      Output verbose logs
-      --app=<value>  The app ID or name (defaults to current app)
-      --json         Output in JSON format
-      --pretty-json  Output in colorized JSON format
+  -v, --verbose        Output verbose logs
+      --app=<value>    The app ID or name (defaults to current app)
+      --json           Output in JSON format
+      --limit=<value>  [default: 100] Maximum number of results to return (default: 100)
+      --pretty-json    Output in colorized JSON format
 
 DESCRIPTION
   List all integrations
@@ -3390,13 +3394,14 @@ List all queues
 
 ```
 USAGE
-  $ ably queues list [-v] [--json | --pretty-json] [--app <value>]
+  $ ably queues list [-v] [--json | --pretty-json] [--app <value>] [--limit <value>]
 
 FLAGS
-  -v, --verbose      Output verbose logs
-      --app=<value>  The app ID or name (defaults to current app)
-      --json         Output in JSON format
-      --pretty-json  Output in colorized JSON format
+  -v, --verbose        Output verbose logs
+      --app=<value>    The app ID or name (defaults to current app)
+      --json           Output in JSON format
+      --limit=<value>  [default: 100] Maximum number of results to return (default: 100)
+      --pretty-json    Output in colorized JSON format
 
 DESCRIPTION
   List all queues

src/commands/apps/list.ts

@@ -1,6 +1,8 @@
+import { Flags } from "@oclif/core";
 import chalk from "chalk";
 
 import { ControlBaseCommand } from "../../control-base-command.js";
+import { formatLimitWarning } from "../../utils/output.js";
 
 export default class AppsList extends ControlBaseCommand {
   static override description = "List all apps in the current account";
@@ -13,6 +15,10 @@ export default class AppsList extends ControlBaseCommand {
 
   static override flags = {
     ...ControlBaseCommand.globalFlags,
+    limit: Flags.integer({
+      default: 100,
+      description: "Maximum number of results to return (default: 100)",
+    }),
   };
 
   async run(): Promise<void> {
@@ -21,7 +27,9 @@ export default class AppsList extends ControlBaseCommand {
     await this.runControlCommand(
       flags,
       async (controlApi) => {
-        const apps = await controlApi.listApps();
+        const allApps = await controlApi.listApps();
+        const hasMore = allApps.length > flags.limit;
+        const apps = allApps.slice(0, flags.limit);
 
         // Get current app ID from config
         const currentAppId = this.configManager.getCurrentAppId();
@@ -33,7 +41,7 @@ export default class AppsList extends ControlBaseCommand {
             isCurrent: app.id === currentAppId,
           }));
 
-          this.logJsonResult({ apps: appsWithCurrentFlag }, flags);
+          this.logJsonResult({ apps: appsWithCurrentFlag, hasMore }, flags);
           return;
         }
 
@@ -77,6 +85,11 @@ export default class AppsList extends ControlBaseCommand {
 
           this.log(""); // Add a blank line between apps
         }
+
+        if (hasMore) {
+          const warning = formatLimitWarning(apps.length, flags.limit, "apps");
+          if (warning) this.log(warning);
+        }
       },
       "Error listing apps",
     );

src/commands/apps/rules/list.ts

@@ -3,7 +3,11 @@ import type { Namespace } from "../../../services/control-api.js";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { formatChannelRuleDetails } from "../../../utils/channel-rule-display.js";
-import { formatCountLabel, formatHeading } from "../../../utils/output.js";
+import {
+  formatCountLabel,
+  formatHeading,
+  formatLimitWarning,
+} from "../../../utils/output.js";
 
 interface ChannelRuleOutput {
   authenticated: boolean;
@@ -40,6 +44,10 @@ export default class RulesListCommand extends ControlBaseCommand {
       description: "The app ID or name (defaults to current app)",
       required: false,
     }),
+    limit: Flags.integer({
+      default: 100,
+      description: "Maximum number of results to return (default: 100)",
+    }),
   };
 
   async run(): Promise<void> {
@@ -48,12 +56,15 @@ export default class RulesListCommand extends ControlBaseCommand {
 
     try {
       const controlApi = this.createControlApi(flags);
-      const namespaces = await controlApi.listNamespaces(appId);
+      const allNamespaces = await controlApi.listNamespaces(appId);
+      const hasMore = allNamespaces.length > flags.limit;
+      const namespaces = allNamespaces.slice(0, flags.limit);
 
       if (this.shouldOutputJson(flags)) {
         this.logJsonResult(
           {
             appId,
+            hasMore,
             rules: namespaces.map(
               (rule: Namespace): ChannelRuleOutput => ({
                 authenticated: rule.authenticated || false,
@@ -102,6 +113,15 @@ export default class RulesListCommand extends ControlBaseCommand {
 
           this.log(""); // Add a blank line between rules
         });
+
+        if (hasMore) {
+          const warning = formatLimitWarning(
+            namespaces.length,
+            flags.limit,
+            "channel rules",
+          );
+          if (warning) this.log(warning);
+        }
       }
     } catch (error) {
       this.fail(error, flags, "ruleList", { appId });

src/commands/auth/keys/list.ts

@@ -3,6 +3,7 @@ import chalk from "chalk";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { formatCapabilities } from "../../../utils/key-display.js";
+import { formatLimitWarning } from "../../../utils/output.js";
 
 export default class KeysListCommand extends ControlBaseCommand {
   static description = "List all keys in the app";
@@ -20,6 +21,10 @@ export default class KeysListCommand extends ControlBaseCommand {
       description: "The app ID (defaults to current app)",
       env: "ABLY_APP_ID",
     }),
+    limit: Flags.integer({
+      default: 100,
+      description: "Maximum number of results to return (default: 100)",
+    }),
   };
 
   async run(): Promise<void> {
@@ -41,7 +46,9 @@ export default class KeysListCommand extends ControlBaseCommand {
 
     try {
       const controlApi = this.createControlApi(flags);
-      const keys = await controlApi.listKeys(appId);
+      const allKeys = await controlApi.listKeys(appId);
+      const hasMore = allKeys.length > flags.limit;
+      const keys = allKeys.slice(0, flags.limit);
 
       // Get the current key name for highlighting (app_id.key_Id)
       const currentKeyId = this.configManager.getKeyId(appId);
@@ -65,6 +72,7 @@ export default class KeysListCommand extends ControlBaseCommand {
         this.logJsonResult(
           {
             appId,
+            hasMore,
             keys: keysWithCurrent,
           },
           flags,
@@ -99,6 +107,11 @@ export default class KeysListCommand extends ControlBaseCommand {
 
           this.log("");
         }
+
+        if (hasMore) {
+          const warning = formatLimitWarning(keys.length, flags.limit, "keys");
+          if (warning) this.log(warning);
+        }
       }
     } catch (error) {
       this.fail(error, flags, "keyList", { appId });