diff --git a/README.md b/README.md
index 658de3f..215cad5 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,11 @@ bird unbookmark https://x.com/user/status/1234567890123456789
 # Likes
 bird likes -n 5
 
+# Lists
+bird list-timeline 1234567890 -n 20
+bird list-timeline https://x.com/i/lists/1234567890 --all --json
+bird list-timeline 1234567890 --max-pages 3 --json
+
 # Following (who you follow)
 bird following -n 20
 bird following --user 12345678 -n 10  # by user ID
@@ -98,6 +103,7 @@ const result = await client.search('from:steipete', 50);
 - `bird bookmarks [-n count] [--folder-id id] [--all] [--max-pages n] [--json]` — list your bookmarked tweets (or a specific bookmark folder); `--max-pages` requires `--all`.
 - `bird unbookmark <tweet-id-or-url...>` — remove one or more bookmarks by tweet ID or URL.
 - `bird likes [-n count] [--json]` — list your liked tweets.
+- `bird list-timeline <list-id-or-url> [-n count] [--all] [--max-pages n] [--cursor string] [--json]` — get tweets from a list timeline; `--max-pages` implies `--all`.
 - `bird following [--user <userId>] [-n count] [--json]` — list users that you (or another user) follow.
 - `bird followers [--user <userId>] [-n count] [--json]` — list users that follow you (or another user).
 - `bird whoami` — print which Twitter account your cookies belong to.
diff --git a/src/commands/lists.ts b/src/commands/lists.ts
index ed4d650..9ad4273 100644
--- a/src/commands/lists.ts
+++ b/src/commands/lists.ts
@@ -79,7 +79,7 @@ export function registerListsCommand(program: Command, ctx: CliContext): void {
     .description('Get tweets from a list timeline')
     .option('-n, --count <number>', 'Number of tweets to fetch', '20')
     .option('--all', 'Fetch all tweets from list (paged). WARNING: your account might get banned using this flag')
-    .option('--max-pages <number>', 'Stop after N pages when using --all')
+    .option('--max-pages <number>', 'Fetch N pages (implies --all)')
     .option('--cursor <string>', 'Resume pagination from a cursor')
     .option('--json', 'Output as JSON')
     .option('--json-full', 'Output as JSON with full raw API response in _raw field')
@@ -96,11 +96,7 @@ export function registerListsCommand(program: Command, ctx: CliContext): void {
         process.exit(2);
       }
 
-      const usePagination = cmdOpts.all || cmdOpts.cursor;
-      if (maxPages !== undefined && !usePagination) {
-        console.error(`${ctx.p('err')}--max-pages requires --all or --cursor.`);
-        process.exit(1);
-      }
+      const usePagination = cmdOpts.all || cmdOpts.cursor || maxPages !== undefined;
       if (!usePagination && (!Number.isFinite(count) || count <= 0)) {
         console.error(`${ctx.p('err')}Invalid --count. Expected a positive integer.`);
         process.exit(1);