Make pagination discoverable on list commands

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 This project uses [Semantic Versioning 2.0.0](http://semver.org/), the format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## Unreleased
+
+### Added
+
+- List commands now show a `Showing X of Y` pagination hint and expose `--all`/`--page`/`--per-page` consistently, making it obvious when results span multiple pages and how to retrieve the rest. (dnsimple/cli#51)
+
 ## 0.8.0 - 2026-05-14
 
 ### Changed

internal/cli/ai_context.md

@@ -26,6 +26,15 @@ These flags work with any command:
 
 When scripting or parsing output programmatically, always use `--json`.
 
+## Pagination
+
+List commands are paginated and return only the first page by default (30 items).
+The `--json` response includes a `pagination` object (`current_page`, `per_page`,
+`total_pages`, `total_entries`) — inspect it to decide whether more results exist. In
+the default table output, a `Showing X of Y ...` hint is written to stderr when more
+pages are available. To retrieve everything in one call, pass `--all` (where supported);
+otherwise page through with `--page <n>` and `--per-page <n>`.
+
 ## Common Workflows
 
 ### List all DNS records for a zone

internal/cli/analytics.go

@@ -113,7 +113,7 @@ func newAnalyticsCmd(f *cmdutil.Factory) *cobra.Command {
 
 func newAnalyticsQueryCmd(f *cmdutil.Factory) *cobra.Command {
 	var startDate, endDate, groupings, sort string
-	var page, perPage int
+	lf := &listFlags{}
 
 	cmd := &cobra.Command{
 		Use:   "query",
@@ -151,32 +151,32 @@ func newAnalyticsQueryCmd(f *cmdutil.Factory) *cobra.Command {
 			if sort != "" {
 				opts.Sort = &sort
 			}
-			if page > 0 {
-				opts.Page = &page
-			}
-			if perPage > 0 {
-				opts.PerPage = &perPage
-			}
-
-			resp, err := c.DnsAnalytics.Query(context.Background(), accountID, opts)
-			if err != nil {
-				return err
-			}
 
-			return f.Printer(cmd).Print(&analyticsOutput{
-				Data:       resp.Data,
-				Pagination: resp.Pagination,
-				Groupings:  effectiveGroupings,
-			})
+			return runList(cmd, f, lf, "analytics rows",
+				func(page, perPage int) ([]dnsimple.DnsAnalytics, *dnsimple.Pagination, error) {
+					if page > 0 {
+						opts.Page = &page
+					}
+					if perPage > 0 {
+						opts.PerPage = &perPage
+					}
+					resp, err := c.DnsAnalytics.Query(context.Background(), accountID, opts)
+					if err != nil {
+						return nil, nil, err
+					}
+					return resp.Data, resp.Pagination, nil
+				},
+				func(items []dnsimple.DnsAnalytics, pg *dnsimple.Pagination) *analyticsOutput {
+					return &analyticsOutput{Data: items, Pagination: pg, Groupings: effectiveGroupings}
+				})
 		},
 	}
 
 	cmd.Flags().StringVar(&startDate, "start-date", "", "Start date (ISO8601)")
 	cmd.Flags().StringVar(&endDate, "end-date", "", "End date (ISO8601)")
 	cmd.Flags().StringVar(&groupings, "groupings", "", "Group by (comma-separated). Supported: zone_name, date")
 	cmd.Flags().StringVar(&sort, "sort", "", "Sort order")
-	cmd.Flags().IntVar(&page, "page", 0, "Page number")
-	cmd.Flags().IntVar(&perPage, "per-page", 0, "Number of items per page")
+	lf.register(cmd)
 
 	return cmd
 }

internal/cli/billing.go

@@ -73,7 +73,7 @@ func newBillingChargesCmd(f *cmdutil.Factory) *cobra.Command {
 				return err
 			}
 
-			return f.Printer(cmd).Print(&chargeList{Data: resp.Data, Pagination: resp.Pagination})
+			return f.Printer(cmd).PrintList(&chargeList{Data: resp.Data, Pagination: resp.Pagination}, pageHint(cmd, resp.Pagination, len(resp.Data), "charges"))
 		},
 	}
 

internal/cli/certificates.go

@@ -164,8 +164,8 @@ func newCertificatesCmd(f *cmdutil.Factory) *cobra.Command {
 }
 
 func newCertsListCmd(f *cmdutil.Factory) *cobra.Command {
-	var page, perPage int
 	var sort string
+	lf := &listFlags{}
 
 	cmd := &cobra.Command{
 		Use:   "list <domain>",
@@ -183,28 +183,32 @@ func newCertsListCmd(f *cmdutil.Factory) *cobra.Command {
 			}
 
 			opts := &dnsimple.ListOptions{}
-			if page > 0 {
-				opts.Page = &page
-			}
-			if perPage > 0 {
-				opts.PerPage = &perPage
-			}
 			if sort != "" {
 				opts.Sort = &sort
 			}
 
-			resp, err := c.Certificates.ListCertificates(context.Background(), accountID, args[0], opts)
-			if err != nil {
-				return err
-			}
-
-			return f.Printer(cmd).Print(&certList{Data: resp.Data, Pagination: resp.Pagination})
+			return runList(cmd, f, lf, "certificates",
+				func(page, perPage int) ([]dnsimple.Certificate, *dnsimple.Pagination, error) {
+					if page > 0 {
+						opts.Page = &page
+					}
+					if perPage > 0 {
+						opts.PerPage = &perPage
+					}
+					resp, err := c.Certificates.ListCertificates(context.Background(), accountID, args[0], opts)
+					if err != nil {
+						return nil, nil, err
+					}
+					return resp.Data, resp.Pagination, nil
+				},
+				func(items []dnsimple.Certificate, pg *dnsimple.Pagination) *certList {
+					return &certList{Data: items, Pagination: pg}
+				})
 		},
 	}
 
 	cmd.Flags().StringVar(&sort, "sort", "", "Sort order")
-	cmd.Flags().IntVar(&page, "page", 0, "Page number")
-	cmd.Flags().IntVar(&perPage, "per-page", 0, "Number of items per page")
+	lf.register(cmd)
 
 	return cmd
 }

internal/cli/contacts.go

@@ -6,7 +6,6 @@ import (
 	"strconv"
 
 	"github.com/dnsimple/cli/internal/cmdutil"
-	"github.com/dnsimple/cli/internal/pagination"
 	"github.com/dnsimple/dnsimple-go/v8/dnsimple"
 	"github.com/spf13/cobra"
 )
@@ -94,9 +93,8 @@ func newContactsCmd(f *cmdutil.Factory) *cobra.Command {
 }
 
 func newContactsListCmd(f *cmdutil.Factory) *cobra.Command {
-	var page, perPage int
 	var sort string
-	var all bool
+	lf := &listFlags{}
 
 	cmd := &cobra.Command{
 		Use:   "list",
@@ -117,41 +115,28 @@ func newContactsListCmd(f *cmdutil.Factory) *cobra.Command {
 				opts.Sort = &sort
 			}
 
-			if all {
-				items, err := pagination.All(func(p int) ([]dnsimple.Contact, *dnsimple.Pagination, error) {
-					opts.Page = &p
+			return runList(cmd, f, lf, "contacts",
+				func(page, perPage int) ([]dnsimple.Contact, *dnsimple.Pagination, error) {
+					if page > 0 {
+						opts.Page = &page
+					}
+					if perPage > 0 {
+						opts.PerPage = &perPage
+					}
 					resp, err := c.Contacts.ListContacts(context.Background(), accountID, opts)
 					if err != nil {
 						return nil, nil, err
 					}
 					return resp.Data, resp.Pagination, nil
+				},
+				func(items []dnsimple.Contact, pg *dnsimple.Pagination) *contactList {
+					return &contactList{Data: items, Pagination: pg}
 				})
-				if err != nil {
-					return err
-				}
-				return f.Printer(cmd).Print(&contactList{Data: items})
-			}
-
-			if page > 0 {
-				opts.Page = &page
-			}
-			if perPage > 0 {
-				opts.PerPage = &perPage
-			}
-
-			resp, err := c.Contacts.ListContacts(context.Background(), accountID, opts)
-			if err != nil {
-				return err
-			}
-
-			return f.Printer(cmd).Print(&contactList{Data: resp.Data, Pagination: resp.Pagination})
 		},
 	}
 
-	cmd.Flags().BoolVar(&all, "all", false, "Fetch all pages")
 	cmd.Flags().StringVar(&sort, "sort", "", "Sort order")
-	cmd.Flags().IntVar(&page, "page", 0, "Page number")
-	cmd.Flags().IntVar(&perPage, "per-page", 0, "Number of items per page")
+	lf.register(cmd)
 
 	return cmd
 }

internal/cli/domains.go

@@ -8,7 +8,6 @@ import (
 	"strings"
 
 	"github.com/dnsimple/cli/internal/cmdutil"
-	"github.com/dnsimple/cli/internal/pagination"
 	"github.com/dnsimple/dnsimple-go/v8/dnsimple"
 	"github.com/spf13/cobra"
 )
@@ -97,10 +96,8 @@ func newDomainsCmd(f *cmdutil.Factory) *cobra.Command {
 }
 
 func newDomainsListCmd(f *cmdutil.Factory) *cobra.Command {
-	var nameLike string
-	var page, perPage int
-	var sort string
-	var all bool
+	var nameLike, sort string
+	lf := &listFlags{}
 
 	cmd := &cobra.Command{
 		Use:   "list",
@@ -124,42 +121,29 @@ func newDomainsListCmd(f *cmdutil.Factory) *cobra.Command {
 				opts.Sort = &sort
 			}
 
-			if all {
-				items, err := pagination.All(func(p int) ([]dnsimple.Domain, *dnsimple.Pagination, error) {
-					opts.Page = &p
+			return runList(cmd, f, lf, "domains",
+				func(page, perPage int) ([]dnsimple.Domain, *dnsimple.Pagination, error) {
+					if page > 0 {
+						opts.Page = &page
+					}
+					if perPage > 0 {
+						opts.PerPage = &perPage
+					}
 					resp, err := c.Domains.ListDomains(context.Background(), accountID, opts)
 					if err != nil {
 						return nil, nil, err
 					}
 					return resp.Data, resp.Pagination, nil
+				},
+				func(items []dnsimple.Domain, pg *dnsimple.Pagination) *domainList {
+					return &domainList{Data: items, Pagination: pg}
 				})
-				if err != nil {
-					return err
-				}
-				return f.Printer(cmd).Print(&domainList{Data: items})
-			}
-
-			if page > 0 {
-				opts.Page = &page
-			}
-			if perPage > 0 {
-				opts.PerPage = &perPage
-			}
-
-			resp, err := c.Domains.ListDomains(context.Background(), accountID, opts)
-			if err != nil {
-				return err
-			}
-
-			return f.Printer(cmd).Print(&domainList{Data: resp.Data, Pagination: resp.Pagination})
 		},
 	}
 
 	cmd.Flags().StringVar(&nameLike, "name-like", "", "Filter domains by name (partial match)")
-	cmd.Flags().BoolVar(&all, "all", false, "Fetch all pages")
 	cmd.Flags().StringVar(&sort, "sort", "", "Sort order (e.g., name:asc, expiration:desc)")
-	cmd.Flags().IntVar(&page, "page", 0, "Page number")
-	cmd.Flags().IntVar(&perPage, "per-page", 0, "Number of items per page")
+	lf.register(cmd)
 
 	return cmd
 }

internal/cli/domains_ds_records.go

@@ -80,7 +80,9 @@ func newDomainsDsRecordsCmd(f *cmdutil.Factory) *cobra.Command {
 }
 
 func newDsRecordsListCmd(f *cmdutil.Factory) *cobra.Command {
-	return &cobra.Command{
+	lf := &listFlags{}
+
+	cmd := &cobra.Command{
 		Use:   "list <domain>",
 		Short: "List DS records",
 		Args:  cobra.ExactArgs(1),
@@ -95,14 +97,31 @@ func newDsRecordsListCmd(f *cmdutil.Factory) *cobra.Command {
 				return err
 			}
 
-			resp, err := c.Domains.ListDelegationSignerRecords(context.Background(), accountID, args[0], nil)
-			if err != nil {
-				return err
-			}
-
-			return f.Printer(cmd).Print(&dsRecordList{Data: resp.Data, Pagination: resp.Pagination})
+			opts := &dnsimple.ListOptions{}
+
+			return runList(cmd, f, lf, "DS records",
+				func(page, perPage int) ([]dnsimple.DelegationSignerRecord, *dnsimple.Pagination, error) {
+					if page > 0 {
+						opts.Page = &page
+					}
+					if perPage > 0 {
+						opts.PerPage = &perPage
+					}
+					resp, err := c.Domains.ListDelegationSignerRecords(context.Background(), accountID, args[0], opts)
+					if err != nil {
+						return nil, nil, err
+					}
+					return resp.Data, resp.Pagination, nil
+				},
+				func(items []dnsimple.DelegationSignerRecord, pg *dnsimple.Pagination) *dsRecordList {
+					return &dsRecordList{Data: items, Pagination: pg}
+				})
 		},
 	}
+
+	lf.register(cmd)
+
+	return cmd
 }
 
 func newDsRecordsGetCmd(f *cmdutil.Factory) *cobra.Command {