tmdb-kit 1.1.0 → 1.2.0

package/dist/cli.js

@@ -354,17 +354,6 @@ async function runCommand(cmd, opts) {
     throw new Error("Multiple cleanup errors", { cause: cleanupErrors });
   return { result };
 }
-async function resolveSubCommand(cmd, rawArgs, parent) {
-  const subCommands = await resolveValue(cmd.subCommands);
-  if (subCommands && Object.keys(subCommands).length > 0) {
-    const subCommandArgIndex = findSubCommandIndex(rawArgs, await resolveValue(cmd.args || {}));
-    const subCommandName = rawArgs[subCommandArgIndex];
-    const subCommand = await _findSubCommand(subCommands, subCommandName);
-    if (subCommand)
-      return resolveSubCommand(subCommand, rawArgs.slice(subCommandArgIndex + 1), cmd);
-  }
-  return [cmd, parent];
-}
 async function _findSubCommand(subCommands, name) {
   if (name in subCommands)
     return resolveValue(subCommands[name]);
@@ -404,14 +393,6 @@ function _isValueFlag(flag, argsDef) {
   }
   return false;
 }
-async function showUsage(cmd, parent) {
-  try {
-    console.log(await renderUsage(cmd, parent) + `
-`);
-  } catch (error) {
-    console.error(error);
-  }
-}
 var negativePrefixRe = /^no[-A-Z]/;
 async function renderUsage(cmd, parent) {
   const cmdMeta = await resolveValue(cmd.meta || {});
@@ -494,57 +475,11 @@ function renderDescription(arg, required) {
     defaultHint
   ].filter(Boolean).join(" ");
 }
-async function runMain(cmd, opts = {}) {
-  const rawArgs = opts.rawArgs || process.argv.slice(2);
-  const showUsage$1 = opts.showUsage || showUsage;
-  try {
-    const builtinFlags = await _resolveBuiltinFlags(cmd);
-    if (builtinFlags.help.length > 0 && rawArgs.some((arg) => builtinFlags.help.includes(arg))) {
-      await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
-      process.exit(0);
-    } else if (rawArgs.length === 1 && builtinFlags.version.includes(rawArgs[0])) {
-      const meta = typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
-      if (!meta?.version)
-        throw new CLIError("No version specified", "E_NO_VERSION");
-      console.log(meta.version);
-    } else
-      await runCommand(cmd, { rawArgs });
-  } catch (error) {
-    if (error instanceof CLIError) {
-      await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
-      console.error(error.message);
-    } else
-      console.error(error, `
-`);
-    process.exit(1);
-  }
-}
-async function _resolveBuiltinFlags(cmd) {
-  const argsDef = await resolveValue(cmd.args || {});
-  const userNames = /* @__PURE__ */ new Set;
-  const userAliases = /* @__PURE__ */ new Set;
-  for (const [name, def] of Object.entries(argsDef)) {
-    userNames.add(name);
-    for (const alias of toArray(def.alias))
-      userAliases.add(alias);
-  }
-  return {
-    help: _getBuiltinFlags("help", "h", userNames, userAliases),
-    version: _getBuiltinFlags("version", "v", userNames, userAliases)
-  };
-}
-function _getBuiltinFlags(long, short, userNames, userAliases) {
-  if (userNames.has(long) || userAliases.has(long))
-    return [];
-  if (userNames.has(short) || userAliases.has(short))
-    return [`--${long}`];
-  return [`--${long}`, `-${short}`];
-}
 // package.json
 var package_default = {
   name: "tmdb-kit",
   type: "module",
-  version: "1.1.0",
+  version: "1.2.0",
   description: "A tiny, typed, zero-runtime-dependency TMDB SDK and CLI for Node.js, Bun, Deno, and edge runtimes.",
   author: "isaced",
   license: "MIT",
@@ -648,6 +583,15 @@ class TMDBRequestError extends TMDBError {
   }
 }
 
+class TMDBTimeoutError extends TMDBError {
+  timeoutMs;
+  constructor(timeoutMs, message = `TMDB request timed out after ${timeoutMs}ms`) {
+    super(message);
+    this.name = "TMDBTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 class TMDBResponseError extends TMDBError {
   body;
   headers;
@@ -770,6 +714,19 @@ function toId(value, name) {
   }
   return String(value);
 }
+function toSeasonNumber(value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TMDBRequestError("seasonNumber must be a non-negative integer");
+  }
+  return String(value);
+}
+function toGroupId(value) {
+  const groupId = value.trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(groupId)) {
+    throw new TMDBRequestError("groupId must be a non-empty identifier");
+  }
+  return groupId;
+}
 function toSearchQuery(value) {
   const query = value.trim();
   if (query.length === 0) {
@@ -903,23 +860,25 @@ class ConfigurationResource {
   constructor(transport) {
     this.#transport = transport;
   }
-  details() {
-    return this.#transport.get("/configuration");
+  details(options = {}) {
+    return this.#transport.get("/configuration", { signal: options.signal });
   }
-  countries() {
-    return this.#transport.get("/configuration/countries");
+  countries(options = {}) {
+    return this.#transport.get("/configuration/countries", { signal: options.signal });
   }
-  jobs() {
-    return this.#transport.get("/configuration/jobs");
+  jobs(options = {}) {
+    return this.#transport.get("/configuration/jobs", { signal: options.signal });
   }
-  languages() {
-    return this.#transport.get("/configuration/languages");
+  languages(options = {}) {
+    return this.#transport.get("/configuration/languages", { signal: options.signal });
   }
-  primaryTranslations() {
-    return this.#transport.get("/configuration/primary_translations");
+  primaryTranslations(options = {}) {
+    return this.#transport.get("/configuration/primary_translations", {
+      signal: options.signal
+    });
   }
-  timezones() {
-    return this.#transport.get("/configuration/timezones");
+  timezones(options = {}) {
+    return this.#transport.get("/configuration/timezones", { signal: options.signal });
   }
 }
 
@@ -933,14 +892,16 @@ class GenresResource {
     return this.#transport.get("/genre/movie/list", {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   tv(options = {}) {
     return this.#transport.get("/genre/tv/list", {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
 }
@@ -969,22 +930,26 @@ class MoviesResource {
   }
   popular(options = {}) {
     return this.#transport.get("/movie/popular", {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   topRated(options = {}) {
     return this.#transport.get("/movie/top_rated", {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   nowPlaying(options = {}) {
     return this.#transport.get("/movie/now_playing", {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   upcoming(options = {}) {
     return this.#transport.get("/movie/upcoming", {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   details(movieId, options = {}) {
@@ -992,14 +957,16 @@ class MoviesResource {
       query: withLanguage(this.#transport.defaults, {
         append_to_response: toCommaList(options.appendToResponse),
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   credits(movieId, options = {}) {
     return this.#transport.get(`/movie/${toId(movieId, "movieId")}/credits`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   images(movieId, options = {}) {
@@ -1007,24 +974,28 @@ class MoviesResource {
       query: withLanguage(this.#transport.defaults, {
         include_image_language: toCommaList(options.includeImageLanguage),
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   recommendations(movieId, options = {}) {
     return this.#transport.get(`/movie/${toId(movieId, "movieId")}/recommendations`, {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   similar(movieId, options = {}) {
     return this.#transport.get(`/movie/${toId(movieId, "movieId")}/similar`, {
-      query: movieListQuery(this.#transport, options)
+      query: movieListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   videos(movieId, options = {}) {
     return this.#transport.get(`/movie/${toId(movieId, "movieId")}/videos`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
 }
@@ -1044,21 +1015,24 @@ class PeopleResource {
   }
   popular(options = {}) {
     return this.#transport.get("/person/popular", {
-      query: peopleListQuery(this.#transport, options)
+      query: peopleListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   details(personId, options = {}) {
     return this.#transport.get(`/person/${toId(personId, "personId")}`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   combinedCredits(personId, options = {}) {
     return this.#transport.get(`/person/${toId(personId, "personId")}/combined_credits`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
 }
@@ -1077,22 +1051,26 @@ class SearchResource {
   }
   movies(query, options = {}) {
     return this.#transport.get("/search/movie", {
-      query: movieSearchQuery(this.#transport, query, options)
+      query: movieSearchQuery(this.#transport, query, options),
+      signal: options.signal
     });
   }
   tv(query, options = {}) {
     return this.#transport.get("/search/tv", {
-      query: tvSearchQuery(this.#transport, query, options)
+      query: tvSearchQuery(this.#transport, query, options),
+      signal: options.signal
     });
   }
   people(query, options = {}) {
     return this.#transport.get("/search/person", {
-      query: commonSearchQuery(this.#transport, query, options)
+      query: commonSearchQuery(this.#transport, query, options),
+      signal: options.signal
     });
   }
   async multi(query, options = {}) {
     const response = await this.#transport.get("/search/multi", {
-      query: commonSearchQuery(this.#transport, query, options)
+      query: commonSearchQuery(this.#transport, query, options),
+      signal: options.signal
     });
     const excluded = options.exclude;
     if (excluded === undefined || excluded.length === 0) {
@@ -1146,7 +1124,8 @@ class TrendingResource {
       query: withLanguage(this.#transport.defaults, {
         language: options.language,
         page: options.page
-      })
+      }),
+      signal: options.signal
     });
   }
   movies(timeWindow = "day", options = {}) {
@@ -1154,7 +1133,8 @@ class TrendingResource {
       query: withLanguage(this.#transport.defaults, {
         language: options.language,
         page: options.page
-      })
+      }),
+      signal: options.signal
     });
   }
   tv(timeWindow = "day", options = {}) {
@@ -1162,7 +1142,8 @@ class TrendingResource {
       query: withLanguage(this.#transport.defaults, {
         language: options.language,
         page: options.page
-      })
+      }),
+      signal: options.signal
     });
   }
   people(timeWindow = "day", options = {}) {
@@ -1170,7 +1151,8 @@ class TrendingResource {
       query: withLanguage(this.#transport.defaults, {
         language: options.language,
         page: options.page
-      })
+      }),
+      signal: options.signal
     });
   }
 }
@@ -1183,22 +1165,26 @@ class TVResource {
   }
   popular(options = {}) {
     return this.#transport.get("/tv/popular", {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   topRated(options = {}) {
     return this.#transport.get("/tv/top_rated", {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   airingToday(options = {}) {
     return this.#transport.get("/tv/airing_today", {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   onTheAir(options = {}) {
     return this.#transport.get("/tv/on_the_air", {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   details(seriesId, options = {}) {
@@ -1206,14 +1192,16 @@ class TVResource {
       query: withLanguage(this.#transport.defaults, {
         append_to_response: toCommaList(options.appendToResponse),
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   credits(seriesId, options = {}) {
     return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/credits`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   images(seriesId, options = {}) {
@@ -1221,32 +1209,103 @@ class TVResource {
       query: withLanguage(this.#transport.defaults, {
         include_image_language: toCommaList(options.includeImageLanguage),
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   recommendations(seriesId, options = {}) {
     return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/recommendations`, {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   similar(seriesId, options = {}) {
     return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/similar`, {
-      query: tvListQuery(this.#transport, options)
+      query: tvListQuery(this.#transport, options),
+      signal: options.signal
     });
   }
   videos(seriesId, options = {}) {
     return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/videos`, {
       query: withLanguage(this.#transport.defaults, {
         language: options.language
-      })
+      }),
+      signal: options.signal
     });
   }
   seasonDetails(seriesId, seasonNumber, options = {}) {
-    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toId(seasonNumber, "seasonNumber")}`, {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}`, {
+      query: withLanguage(this.#transport.defaults, {
+        append_to_response: toCommaList(options.appendToResponse),
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  seasonCredits(seriesId, seasonNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/credits`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  seasonAggregateCredits(seriesId, seasonNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/aggregate_credits`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  seasonImages(seriesId, seasonNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/images`, {
+      query: withLanguage(this.#transport.defaults, {
+        include_image_language: toCommaList(options.includeImageLanguage),
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  seasonVideos(seriesId, seasonNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/videos`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  episodeDetails(seriesId, seasonNumber, episodeNumber, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/season/${toSeasonNumber(seasonNumber)}/episode/${toId(episodeNumber, "episodeNumber")}`, {
       query: withLanguage(this.#transport.defaults, {
         append_to_response: toCommaList(options.appendToResponse),
         language: options.language
-      })
+      }),
+      signal: options.signal
+    });
+  }
+  aggregateCredits(seriesId, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/aggregate_credits`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  episodeGroups(seriesId, options = {}) {
+    return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/episode_groups`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
+    });
+  }
+  episodeGroup(groupId, options = {}) {
+    return this.#transport.get(`/tv/episode_group/${toGroupId(groupId)}`, {
+      query: withLanguage(this.#transport.defaults, {
+        language: options.language
+      }),
+      signal: options.signal
     });
   }
 }
@@ -1269,13 +1328,17 @@ class TMDBClient {
   tv;
   #transport;
   constructor(options) {
-    const { transport, images, ...httpOptions } = options;
-    const fallbackTransform = images?.transform;
-    const builtInClient = transport === undefined ? new TMDBHttpClient({ ...httpOptions, images }) : undefined;
-    this.#transport = builtInClient ?? transport;
+    let imageTransform = options.images?.transform;
+    if (options.transport === undefined) {
+      const builtInClient = new TMDBHttpClient(options);
+      this.#transport = builtInClient;
+      imageTransform = builtInClient.imageTransform;
+    } else {
+      this.#transport = options.transport;
+    }
     this.configuration = new ConfigurationResource(this.#transport);
     this.genres = new GenresResource(this.#transport);
-    this.images = new ImagesHelper(this.#transport, builtInClient ? builtInClient.imageTransform : fallbackTransform);
+    this.images = new ImagesHelper(this.#transport, imageTransform);
     this.movies = new MoviesResource(this.#transport);
     this.people = new PeopleResource(this.#transport);
     this.search = new SearchResource(this.#transport);
@@ -1353,14 +1416,50 @@ function errorMessage(error) {
   }
   return String(error);
 }
-async function runSafely(task) {
-  try {
-    await task();
-  } catch (error) {
-    process.stderr.write(`${errorMessage(error)}
-`);
-    process.exitCode = exitCodeFor(error);
+var EXIT_CODE_KINDS = {
+  2: "usage",
+  3: "auth",
+  4: "not_found",
+  5: "rate_limit"
+};
+function errorKind(error) {
+  if (error instanceof CliError) {
+    return EXIT_CODE_KINDS[error.exitCode] ?? "internal";
+  }
+  if (error instanceof TMDBRateLimitError) {
+    return "rate_limit";
+  }
+  if (error instanceof TMDBResponseError) {
+    if (error.status === 401 || error.status === 403)
+      return "auth";
+    if (error.status === 404)
+      return "not_found";
+    if (error.status === 429)
+      return "rate_limit";
+    return "api";
+  }
+  if (error instanceof TMDBRequestError || error instanceof TMDBTimeoutError) {
+    return "network";
+  }
+  return "internal";
+}
+function toErrorRecord(error) {
+  const record = {
+    type: "error",
+    kind: errorKind(error),
+    message: errorMessage(error),
+    exitCode: exitCodeFor(error)
+  };
+  if (error instanceof TMDBResponseError) {
+    record.status = error.status;
+    if (error.requestId !== null) {
+      record.requestId = error.requestId;
+    }
+  }
+  if (error instanceof TMDBRateLimitError) {
+    record.retryAfter = error.retryAfter;
   }
+  return record;
 }
 
 // src/cli/config.ts
@@ -1581,9 +1680,135 @@ function missingCredentialsMessage() {
 `);
 }
 
+// src/cli/options.ts
+var jsonArg = {
+  json: {
+    type: "boolean",
+    description: "Alias for --format json"
+  }
+};
+var formatArg = {
+  format: {
+    type: "string",
+    description: "Output format: text, json, or ndjson (default: text)"
+  },
+  compact: {
+    type: "boolean",
+    description: "Print JSON on a single line"
+  },
+  fields: {
+    type: "string",
+    description: "Comma-separated top-level fields to keep in JSON output"
+  }
+};
+var outputArgs = {
+  ...jsonArg,
+  ...formatArg
+};
+var paginationArgs = {
+  all: {
+    type: "boolean",
+    description: "Fetch every page instead of one (requires --format ndjson)"
+  },
+  "max-items": {
+    type: "string",
+    description: "Stop after this many items (requires --format ndjson)"
+  }
+};
+var commonArgs = {
+  ...outputArgs,
+  lang: {
+    type: "string",
+    description: "TMDB language code (default: en-US)"
+  }
+};
+var SEARCH_TYPES = ["all", "movie", "tv", "person"];
+function parseSearchType(value) {
+  if (!SEARCH_TYPES.includes(value)) {
+    throw new CliError(`Invalid --type "${value}". Expected one of: ${SEARCH_TYPES.join(", ")}.`, 2);
+  }
+  return value;
+}
+function parsePage(value) {
+  if (value === undefined || value === "") {
+    return 1;
+  }
+  const page = Number(value);
+  if (!Number.isInteger(page) || page < 1) {
+    throw new CliError("Invalid --page value: expected a positive integer.", 2);
+  }
+  return page;
+}
+function parseId(value, label) {
+  const id = Number(value);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new CliError(`Invalid ${label}: expected a positive integer.`, 2);
+  }
+  return id;
+}
+function parseSeasonNumber(value) {
+  const season = Number(value);
+  if (!Number.isInteger(season) || season < 0) {
+    throw new CliError("Invalid season number: expected a non-negative integer.", 2);
+  }
+  return season;
+}
+function parseGroupId(value) {
+  const groupId = value.trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(groupId)) {
+    throw new CliError("Invalid group ID: expected a non-empty identifier.", 2);
+  }
+  return groupId;
+}
+function parseLimit(value, fallback = 10) {
+  if (value === undefined || value === "") {
+    return fallback;
+  }
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new CliError("Invalid --limit value: expected a positive integer.", 2);
+  }
+  return limit;
+}
+function parseCommaList(value) {
+  if (value === undefined) {
+    return;
+  }
+  const values = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return values.length > 0 ? values : undefined;
+}
+var TRENDING_WINDOWS = ["day", "week"];
+function parseWindow(value) {
+  if (!TRENDING_WINDOWS.includes(value)) {
+    throw new CliError(`Invalid --window "${value}". Expected one of: ${TRENDING_WINDOWS.join(", ")}.`, 2);
+  }
+  return value;
+}
+var GENRE_TYPES = ["movie", "tv"];
+function parseGenreType(value) {
+  if (!GENRE_TYPES.includes(value)) {
+    throw new CliError(`Invalid --type "${value}". Expected one of: ${GENRE_TYPES.join(", ")}.`, 2);
+  }
+  return value;
+}
+var MOVIE_LIST_CATEGORIES = ["popular", "top-rated", "now-playing", "upcoming"];
+function parseMovieListCategory(value) {
+  if (!MOVIE_LIST_CATEGORIES.includes(value)) {
+    throw new CliError(`Invalid movie list category "${value}". Expected one of: ${MOVIE_LIST_CATEGORIES.join(", ")}.`, 2);
+  }
+  return value;
+}
+var TV_LIST_CATEGORIES = ["popular", "top-rated", "airing-today", "on-the-air"];
+function parseTVListCategory(value) {
+  if (!TV_LIST_CATEGORIES.includes(value)) {
+    throw new CliError(`Invalid TV list category "${value}". Expected one of: ${TV_LIST_CATEGORIES.join(", ")}.`, 2);
+  }
+  return value;
+}
+
 // src/cli/format.ts
-function printJson(value) {
-  process.stdout.write(`${JSON.stringify(value, null, 2)}
+function printJson(value, compact = false) {
+  process.stdout.write(`${compact ? JSON.stringify(value) : JSON.stringify(value, null, 2)}
 `);
 }
 function printSearchResults(response, type) {
@@ -1706,6 +1931,30 @@ function printCredits(credits, limit = 10) {
   }
   writeLines(lines);
 }
+function printAggregateCredits(credits, limit = 10) {
+  const lines = [];
+  if (credits.cast.length > 0) {
+    lines.push("Cast:");
+    for (const member of credits.cast.slice(0, limit)) {
+      const roles = member.roles.map((role) => `${role.character} (${role.episode_count} eps)`).join(", ");
+      lines.push(`  ${member.name} as ${roles}  #${member.id}`);
+    }
+  }
+  if (credits.crew.length > 0) {
+    if (lines.length > 0) {
+      lines.push("");
+    }
+    lines.push("Crew:");
+    for (const member of credits.crew.slice(0, limit)) {
+      const jobs = member.jobs.map((job) => `${job.job} (${job.episode_count} eps)`).join(", ");
+      lines.push(`  ${member.name} — ${jobs} (${member.department})  #${member.id}`);
+    }
+  }
+  if (lines.length === 0) {
+    lines.push("No credits.");
+  }
+  writeLines(lines);
+}
 function printImages(images, tmdb) {
   const lines = [];
   appendImageSection(lines, "Posters", images.posters, "w500", tmdb);
@@ -1716,6 +1965,14 @@ function printImages(images, tmdb) {
   }
   writeLines(lines);
 }
+function printSeasonImages(images, tmdb) {
+  const lines = [];
+  appendImageSection(lines, "Posters", images.posters, "w500", tmdb);
+  if (lines.length === 0) {
+    lines.push("No images.");
+  }
+  writeLines(lines);
+}
 function printVideos(videos) {
   if (videos.results.length === 0) {
     writeLines(["No videos."]);
@@ -1750,6 +2007,49 @@ function printSeason(season, tmdb) {
   }
   writeLines(lines);
 }
+function printEpisode(episode, tmdb, seriesId) {
+  const lines = [`${episodeCode(episode)} · ${episode.name}`];
+  const facts = [
+    episode.air_date,
+    episode.runtime ? `${episode.runtime} min` : undefined,
+    `★ ${episode.vote_average.toFixed(1)}/10 (${episode.vote_count} votes)`
+  ].filter(Boolean);
+  lines.push(facts.join(" · "));
+  lines.push(`TMDB: https://www.themoviedb.org/tv/${seriesId}/season/${episode.season_number}/episode/${episode.episode_number}`);
+  const still = tmdb.images.url(episode.still_path, "w300");
+  if (still) {
+    lines.push(`Still: ${still}`);
+  }
+  if (episode.overview) {
+    lines.push("", episode.overview);
+  }
+  writeLines(lines);
+}
+function printEpisodeGroups(response) {
+  if (response.results.length === 0) {
+    writeLines(["No episode groups."]);
+    return;
+  }
+  writeLines(response.results.map((group) => `${group.id}  ${group.name}  (${group.group_count} groups, ${group.episode_count} episodes)`));
+}
+function printEpisodeGroup(group) {
+  const lines = [group.name];
+  if (group.description) {
+    lines.push(group.description);
+  }
+  if (group.groups.length === 0) {
+    lines.push("", "No episodes.");
+    writeLines(lines);
+    return;
+  }
+  for (const section of group.groups) {
+    lines.push("", section.name);
+    for (const episode of section.episodes) {
+      lines.push(`  ${episode.order}. ${episodeCode(episode)} · ${episode.name}  #${episode.id}`);
+    }
+  }
+  writeLines(lines);
+}
 function printPerson(person, tmdb) {
   const lines = [person.name];
   const facts = [
@@ -1851,6 +2151,9 @@ function writeLines(lines) {
 `)}
 `);
 }
+function episodeCode(episode) {
+  return `S${String(episode.season_number).padStart(2, "0")}E${String(episode.episode_number).padStart(2, "0")}`;
+}
 function formatSearchResult(result, index, fallbackType) {
   const title = "title" in result ? result.title : result.name;
   const date = "release_date" in result ? result.release_date : ("first_air_date" in result) ? result.first_air_date : "";
@@ -1860,95 +2163,211 @@ function formatSearchResult(result, index, fallbackType) {
   return `${String(index + 1).padStart(2)}. ${title}${year}${score}  ${mediaType}  ${result.id}`;
 }
 
-// src/cli/options.ts
-var jsonArg = {
-  json: {
-    type: "boolean",
-    description: "Print the raw TMDB JSON response"
+// src/cli/output.ts
+var OUTPUT_FORMATS = ["text", "json", "ndjson"];
+var MAX_PAGE = 500;
+var FORMAT_ALIASES = { jsonl: "ndjson" };
+function resolveOutput(args, options = {}) {
+  const explicitFormat = args.format !== undefined && args.format.trim() !== "";
+  const format = parseFormat(args.format);
+  const fields = parseFields(args.fields);
+  const all = args.all === true;
+  const maxItems = parseMaxItems(args["max-items"]);
+  if (args.json && explicitFormat && format !== "json") {
+    throw new CliError(`--json cannot be combined with --format ${format}.`, 2);
+  }
+  const resolvedFormat = args.json ? "json" : format;
+  if (fields && resolvedFormat === "text") {
+    throw new CliError("--fields requires --format json or ndjson.", 2);
+  }
+  if (all || maxItems !== undefined) {
+    if (resolvedFormat !== "ndjson") {
+      throw new CliError(`${all ? "--all" : "--max-items"} requires --format ndjson.`, 2);
+    }
+    if (options.paginated !== true) {
+      throw new CliError(`${all ? "--all" : "--max-items"} is only supported by list commands.`, 2);
+    }
   }
-};
-var commonArgs = {
-  ...jsonArg,
-  lang: {
-    type: "string",
-    description: "TMDB language code (default: en-US)"
+  return {
+    ...all ? { all: true } : {},
+    compact: args.compact === true,
+    ...fields ? { fields } : {},
+    format: resolvedFormat,
+    ...maxItems !== undefined ? { maxItems } : {}
+  };
+}
+function printResult(value, output, renderText) {
+  if (output.format === "text") {
+    renderText();
+    return;
   }
-};
-var SEARCH_TYPES = ["all", "movie", "tv", "person"];
-function parseSearchType(value) {
-  if (!SEARCH_TYPES.includes(value)) {
-    throw new CliError(`Invalid --type "${value}". Expected one of: ${SEARCH_TYPES.join(", ")}.`, 2);
+  if (output.format === "json") {
+    printJson(output.fields ? projectPayload(value, output.fields) : value, output.compact);
+    return;
   }
-  return value;
-}
-function parsePage(value) {
-  if (value === undefined || value === "") {
-    return 1;
+  printNdjson(value, output);
+}
+async function printPaged({
+  fetchPage,
+  output,
+  renderText,
+  startPage
+}) {
+  let response = await fetchPage(startPage);
+  if (output.format === "text") {
+    renderText(response);
+    return;
   }
-  const page = Number(value);
-  if (!Number.isInteger(page) || page < 1) {
-    throw new CliError("Invalid --page value: expected a positive integer.", 2);
+  if (output.format === "json") {
+    printJson(output.fields ? projectPayload(response, output.fields) : response, output.compact);
+    return;
   }
-  return page;
+  const maxItems = output.maxItems ?? Number.POSITIVE_INFINITY;
+  let page = startPage;
+  let pages = 0;
+  let count = 0;
+  writeNdjson({ ...envelopeOf(response), type: "meta" });
+  while (true) {
+    pages += 1;
+    for (const item of response.results) {
+      if (count >= maxItems) {
+        break;
+      }
+      writeNdjson({
+        type: "item",
+        index: count,
+        value: output.fields ? projectRecord(item, output.fields, count === 0) : item
+      });
+      count += 1;
+    }
+    if (!output.all || count >= maxItems || response.results.length === 0) {
+      break;
+    }
+    if (page >= Math.min(response.total_pages, MAX_PAGE)) {
+      break;
+    }
+    page += 1;
+    response = await fetchPage(page);
+  }
+  writeNdjson({ type: "summary", count, pages });
 }
-function parseId(value, label) {
-  const id = Number(value);
-  if (!Number.isInteger(id) || id <= 0) {
-    throw new CliError(`Invalid ${label}: expected a positive integer.`, 2);
+async function runSafely(args, task, options = {}) {
+  let output;
+  try {
+    output = resolveOutput(args, options);
+    await task(output);
+  } catch (error) {
+    writeError(error, output ?? fallbackOutput(args));
+    process.exitCode = exitCodeFor(error);
   }
-  return id;
 }
-function parseSeasonNumber(value) {
-  const season = Number(value);
-  if (!Number.isInteger(season) || season < 0) {
-    throw new CliError("Invalid season number: expected a non-negative integer.", 2);
+function writeError(error, output) {
+  if (output.format === "text") {
+    process.stderr.write(`${errorMessage(error)}
+`);
+    return;
   }
-  return season;
+  process.stderr.write(`${JSON.stringify(toErrorRecord(error))}
+`);
 }
-function parseLimit(value, fallback = 10) {
+function fallbackOutput(args) {
+  const format = args.format?.trim().toLowerCase();
+  const wantsJson = args.json === true || format === "json" || format === "jsonl" || format === "ndjson";
+  return {
+    compact: args.compact === true,
+    format: wantsJson ? "json" : "text"
+  };
+}
+function parseFormat(value) {
   if (value === undefined || value === "") {
-    return fallback;
+    return "text";
   }
-  const limit = Number(value);
-  if (!Number.isInteger(limit) || limit < 1) {
-    throw new CliError("Invalid --limit value: expected a positive integer.", 2);
+  const requested = value.trim().toLowerCase();
+  const format = FORMAT_ALIASES[requested] ?? requested;
+  if (!OUTPUT_FORMATS.includes(format)) {
+    throw new CliError(`Invalid --format "${value}". Expected one of: ${OUTPUT_FORMATS.join(", ")}.`, 2);
   }
-  return limit;
+  return format;
 }
-function parseCommaList(value) {
+function parseFields(value) {
   if (value === undefined) {
     return;
   }
-  const values = value.split(",").map((item) => item.trim()).filter(Boolean);
-  return values.length > 0 ? values : undefined;
-}
-var TRENDING_WINDOWS = ["day", "week"];
-function parseWindow(value) {
-  if (!TRENDING_WINDOWS.includes(value)) {
-    throw new CliError(`Invalid --window "${value}". Expected one of: ${TRENDING_WINDOWS.join(", ")}.`, 2);
+  const fields = [
+    ...new Set(value.split(",").map((field) => field.trim()).filter(Boolean))
+  ];
+  if (fields.length === 0) {
+    throw new CliError("--fields requires at least one field name.", 2);
   }
-  return value;
+  return fields;
 }
-var GENRE_TYPES = ["movie", "tv"];
-function parseGenreType(value) {
-  if (!GENRE_TYPES.includes(value)) {
-    throw new CliError(`Invalid --type "${value}". Expected one of: ${GENRE_TYPES.join(", ")}.`, 2);
+function parseMaxItems(value) {
+  if (value === undefined) {
+    return;
   }
-  return value;
+  const maxItems = Number(value);
+  if (!Number.isInteger(maxItems) || maxItems < 1) {
+    throw new CliError("Invalid --max-items value: expected a positive integer.", 2);
+  }
+  return maxItems;
+}
+function printNdjson(value, output) {
+  if (isRecord(value) && Array.isArray(value.results)) {
+    const { results, ...envelope } = value;
+    writeNdjson({ ...envelope, type: "meta" });
+    results.forEach((item, index) => {
+      writeNdjson({
+        type: "item",
+        index,
+        value: output.fields ? projectRecord(item, output.fields, index === 0) : item
+      });
+    });
+    writeNdjson({ type: "summary", count: results.length, pages: 1 });
+    return;
+  }
+  writeNdjson({
+    type: "result",
+    value: output.fields ? projectRecord(value, output.fields, true) : value
+  });
 }
-var MOVIE_LIST_CATEGORIES = ["popular", "top-rated", "now-playing", "upcoming"];
-function parseMovieListCategory(value) {
-  if (!MOVIE_LIST_CATEGORIES.includes(value)) {
-    throw new CliError(`Invalid movie list category "${value}". Expected one of: ${MOVIE_LIST_CATEGORIES.join(", ")}.`, 2);
+function writeNdjson(record) {
+  process.stdout.write(`${JSON.stringify(record)}
+`);
+}
+function envelopeOf(response) {
+  const envelope = { ...response };
+  delete envelope.results;
+  return envelope;
+}
+function projectPayload(value, fields) {
+  if (!isRecord(value)) {
+    throw new CliError("--fields requires an object response.", 2);
   }
-  return value;
+  if (Array.isArray(value.results)) {
+    return {
+      ...value,
+      results: value.results.map((item, index) => projectRecord(item, fields, index === 0))
+    };
+  }
+  return projectRecord(value, fields, true);
 }
-var TV_LIST_CATEGORIES = ["popular", "top-rated", "airing-today", "on-the-air"];
-function parseTVListCategory(value) {
-  if (!TV_LIST_CATEGORIES.includes(value)) {
-    throw new CliError(`Invalid TV list category "${value}". Expected one of: ${TV_LIST_CATEGORIES.join(", ")}.`, 2);
+function projectRecord(record, fields, validate) {
+  if (!isRecord(record)) {
+    throw new CliError("--fields requires object records.", 2);
   }
-  return value;
+  const projected = {};
+  for (const field of fields) {
+    if (Object.hasOwn(record, field)) {
+      projected[field] = record[field];
+    }
+  }
+  if (validate && Object.keys(projected).length === 0) {
+    throw new CliError(`Unknown --fields value(s): ${fields.join(", ")}. Available: ${Object.keys(record).sort().join(", ")}.`, 2);
+  }
+  return projected;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 // src/cli/prompt.ts
@@ -2018,7 +2437,7 @@ var authCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely({}, async () => {
           const existing = resolveCredentials();
           if (!args.force && existing.source !== "none") {
             if (!process.stdin.isTTY) {
@@ -2085,9 +2504,9 @@ Saved ${credential.kind} to ${getConfigPath()}
         name: "status",
         description: "Show credential source, token mask, and config path"
       },
-      args: { ...jsonArg },
+      args: { ...outputArgs },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const credentials = resolveCredentials();
           const path = getConfigPath();
           const configExists = existsSync2(path);
@@ -2101,10 +2520,6 @@ Saved ${credential.kind} to ${getConfigPath()}
             language: credentials.config.language ?? null,
             region: credentials.config.region ?? null
           };
-          if (args.json) {
-            printJson(view);
-            return;
-          }
           const lines = [
             `Credential source: ${describeSource(credentials)}`,
             `Token: ${view.token ?? "(not set)"}`,
@@ -2119,9 +2534,9 @@ Saved ${credential.kind} to ${getConfigPath()}
           if (credentials.source === "none") {
             lines.push("", "Run `tmdb auth login` to set up credentials.");
           }
-          process.stdout.write(`${lines.join(`
+          printResult(view, output, () => process.stdout.write(`${lines.join(`
 `)}
-`);
+`));
         });
       }
     }),
@@ -2131,7 +2546,7 @@ Saved ${credential.kind} to ${getConfigPath()}
         description: "Remove saved API credentials from the config file"
       },
       async run() {
-        await runSafely(async () => {
+        await runSafely({}, async () => {
           const config = readConfig();
           const hadCredentials = Boolean(config.accessToken || config.apiKey);
           if (hadCredentials) {
@@ -2238,9 +2653,9 @@ var configCommand = defineCommand({
         name: "show",
         description: "Show the resolved config with secrets masked"
       },
-      args: { ...jsonArg },
+      args: { ...outputArgs },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const config = readConfig();
           const path = getConfigPath();
           const view = {
@@ -2250,19 +2665,17 @@ var configCommand = defineCommand({
             language: config.language ?? null,
             region: config.region ?? null
           };
-          if (args.json) {
-            printJson(view);
-            return;
-          }
-          process.stdout.write([
-            `Path: ${path}`,
-            `accessToken: ${view.accessToken ?? "(not set)"}`,
-            `apiKey: ${view.apiKey ?? "(not set)"}`,
-            `language: ${view.language ?? "(not set)"}`,
-            `region: ${view.region ?? "(not set)"}`
-          ].join(`
+          printResult(view, output, () => {
+            process.stdout.write([
+              `Path: ${path}`,
+              `accessToken: ${view.accessToken ?? "(not set)"}`,
+              `apiKey: ${view.apiKey ?? "(not set)"}`,
+              `language: ${view.language ?? "(not set)"}`,
+              `region: ${view.region ?? "(not set)"}`
+            ].join(`
 `) + `
 `);
+          });
         });
       }
     }),
@@ -2281,18 +2694,16 @@ var configCommand = defineCommand({
         name: "test",
         description: "Verify credentials with an authenticated TMDB request"
       },
-      args: { ...jsonArg },
+      args: { ...outputArgs },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const client = createClient();
           await client.movies.details(550);
-          if (args.json) {
-            printJson({ ok: true });
-            return;
-          }
-          process.stdout.write(`TMDB connection OK
+          printResult({ ok: true }, output, () => {
+            process.stdout.write(`TMDB connection OK
 Credentials are valid.
 `);
+          });
         });
       }
     }),
@@ -2314,7 +2725,7 @@ Credentials are valid.
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely({}, async () => {
           const field = parseConfigKey(args.key);
           const path = getConfigPath();
           if (field === "accessToken" || field === "apiKey") {
@@ -2354,7 +2765,7 @@ Credentials are valid.
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely({}, async () => {
           const field = parseConfigKey(args.key);
           unsetConfigValue(field);
           process.stdout.write(`Removed ${field} from ${getConfigPath()}
@@ -2386,15 +2797,11 @@ var genresCommand = defineCommand({
     }
   },
   async run({ args }) {
-    await runSafely(async () => {
+    await runSafely(args, async (output) => {
       const type = parseGenreType(args.type);
       const client = createClient({ language: args.lang });
       const response = type === "tv" ? await client.genres.tv() : await client.genres.movies();
-      if (args.json) {
-        printJson(response);
-      } else {
-        printGenres(response);
-      }
+      printResult(response, output, () => printGenres(response));
     });
   }
 });
@@ -2413,6 +2820,7 @@ var movieCommand = defineCommand({
       },
       args: {
         ...commonArgs,
+        ...paginationArgs,
         category: {
           type: "positional",
           description: "popular, top-rated, now-playing, or upcoming",
@@ -2428,17 +2836,20 @@ var movieCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const category = parseMovieListCategory(args.category);
-          const options = { page: parsePage(args.page), region: args.region };
+          const params = { page: parsePage(args.page), region: args.region };
           const client = createClient({ language: args.lang });
-          const response = category === "top-rated" ? await client.movies.topRated(options) : category === "now-playing" ? await client.movies.nowPlaying(options) : category === "upcoming" ? await client.movies.upcoming(options) : await client.movies.popular(options);
-          if (args.json) {
-            printJson(response);
-          } else {
-            printSearchResults(response, "movie");
-          }
-        });
+          await printPaged({
+            fetchPage: (page) => {
+              const options = { ...params, page };
+              return category === "top-rated" ? client.movies.topRated(options) : category === "now-playing" ? client.movies.nowPlaying(options) : category === "upcoming" ? client.movies.upcoming(options) : client.movies.popular(options);
+            },
+            output,
+            renderText: (response) => printSearchResults(response, "movie"),
+            startPage: params.page
+          });
+        }, { paginated: true });
       }
     }),
     get: defineCommand({
@@ -2459,16 +2870,12 @@ var movieCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "movie ID");
           const client = createClient({ language: args.lang });
           const appendToResponse = parseCommaList(args.append);
           const movie = await client.movies.details(id, { appendToResponse });
-          if (args.json) {
-            printJson(movie);
-          } else {
-            printMovie(movie, client);
-          }
+          printResult(movie, output, () => printMovie(movie, client));
         });
       }
     }),
@@ -2490,16 +2897,12 @@ var movieCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "movie ID");
           const limit = parseLimit(args.limit);
           const client = createClient({ language: args.lang });
           const credits = await client.movies.credits(id);
-          if (args.json) {
-            printJson(credits);
-          } else {
-            printCredits(credits, limit);
-          }
+          printResult(credits, output, () => printCredits(credits, limit));
         });
       }
     }),
@@ -2521,16 +2924,12 @@ var movieCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "movie ID");
           const includeImageLanguage = parseCommaList(args["image-language"]);
           const client = createClient({ language: args.lang });
           const images = await client.movies.images(id, { includeImageLanguage });
-          if (args.json) {
-            printJson(images);
-          } else {
-            printImages(images, client);
-          }
+          printResult(images, output, () => printImages(images, client));
         });
       }
     }),
@@ -2548,15 +2947,11 @@ var movieCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "movie ID");
           const client = createClient({ language: args.lang });
           const videos = await client.movies.videos(id);
-          if (args.json) {
-            printJson(videos);
-          } else {
-            printVideos(videos);
-          }
+          printResult(videos, output, () => printVideos(videos));
         });
       }
     }),
@@ -2579,20 +2974,21 @@ var movieCommand = defineCommand({
         region: {
           type: "string",
           description: "ISO 3166-1 region code"
-        }
+        },
+        ...paginationArgs
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "movie ID");
-          const options = { page: parsePage(args.page), region: args.region };
+          const params = { page: parsePage(args.page), region: args.region };
           const client = createClient({ language: args.lang });
-          const response = await client.movies.similar(id, options);
-          if (args.json) {
-            printJson(response);
-          } else {
-            printSearchResults(response, "movie");
-          }
-        });
+          await printPaged({
+            fetchPage: (page) => client.movies.similar(id, { ...params, page }),
+            output,
+            renderText: (response) => printSearchResults(response, "movie"),
+            startPage: params.page
+          });
+        }, { paginated: true });
       }
     }),
     recommendations: defineCommand({
@@ -2614,20 +3010,21 @@ var movieCommand = defineCommand({
         region: {
           type: "string",
           description: "ISO 3166-1 region code"
-        }
+        },
+        ...paginationArgs
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "movie ID");
-          const options = { page: parsePage(args.page), region: args.region };
+          const params = { page: parsePage(args.page), region: args.region };
           const client = createClient({ language: args.lang });
-          const response = await client.movies.recommendations(id, options);
-          if (args.json) {
-            printJson(response);
-          } else {
-            printSearchResults(response, "movie");
-          }
-        });
+          await printPaged({
+            fetchPage: (page) => client.movies.recommendations(id, { ...params, page }),
+            output,
+            renderText: (response) => printSearchResults(response, "movie"),
+            startPage: params.page
+          });
+        }, { paginated: true });
       }
     })
   }
@@ -2654,15 +3051,11 @@ var personCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "person ID");
           const client = createClient({ language: args.lang });
           const person = await client.people.details(id);
-          if (args.json) {
-            printJson(person);
-          } else {
-            printPerson(person, client);
-          }
+          printResult(person, output, () => printPerson(person, client));
         });
       }
     }),
@@ -2684,16 +3077,12 @@ var personCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "person ID");
           const limit = parseLimit(args.limit);
           const client = createClient({ language: args.lang });
           const credits = await client.people.combinedCredits(id);
-          if (args.json) {
-            printJson(credits);
-          } else {
-            printPersonCredits(credits, limit);
-          }
+          printResult(credits, output, () => printPersonCredits(credits, limit));
         });
       }
     })
@@ -2708,6 +3097,7 @@ var searchCommand = defineCommand({
   },
   args: {
     ...commonArgs,
+    ...paginationArgs,
     query: {
       type: "positional",
       description: "Search query",
@@ -2729,7 +3119,7 @@ var searchCommand = defineCommand({
     }
   },
   async run({ args }) {
-    await runSafely(async () => {
+    await runSafely(args, async (output) => {
       const query = args.query.trim();
       if (!query) {
         throw new CliError("Search query must not be empty.", 2);
@@ -2741,14 +3131,16 @@ var searchCommand = defineCommand({
         throw new CliError("--year is only supported with --type movie or tv.", 2);
       }
       const client = createClient({ language: args.lang });
-      const options = { page };
-      const response = type === "movie" ? await client.search.movies(query, { ...options, year }) : type === "tv" ? await client.search.tv(query, { ...options, firstAirDateYear: year }) : type === "person" ? await client.search.people(query, options) : await client.search.multi(query, options);
-      if (args.json) {
-        printJson(response);
-      } else {
-        printSearchResults(response, type);
-      }
-    });
+      await printPaged({
+        fetchPage: (nextPage) => {
+          const options = { page: nextPage };
+          return type === "movie" ? client.search.movies(query, { ...options, year }) : type === "tv" ? client.search.tv(query, { ...options, firstAirDateYear: year }) : type === "person" ? client.search.people(query, options) : client.search.multi(query, options);
+        },
+        output,
+        renderText: (response) => printSearchResults(response, type),
+        startPage: page
+      });
+    }, { paginated: true });
   }
 });
 
@@ -2760,6 +3152,7 @@ var trendingCommand = defineCommand({
   },
   args: {
     ...commonArgs,
+    ...paginationArgs,
     type: {
       type: "positional",
       description: "Media type: all, movie, tv, or person",
@@ -2777,18 +3170,21 @@ var trendingCommand = defineCommand({
     }
   },
   async run({ args }) {
-    await runSafely(async () => {
+    await runSafely(args, async (output) => {
       const type = parseSearchType(args.type);
       const window = parseWindow(args.window);
       const page = parsePage(args.page);
       const client = createClient({ language: args.lang });
-      const response = type === "movie" ? await client.trending.movies(window, { page }) : type === "tv" ? await client.trending.tv(window, { page }) : type === "person" ? await client.trending.people(window, { page }) : await client.trending.all(window, { page });
-      if (args.json) {
-        printJson(response);
-      } else {
-        printSearchResults(response, type);
-      }
-    });
+      await printPaged({
+        fetchPage: (nextPage) => {
+          const options = { page: nextPage };
+          return type === "movie" ? client.trending.movies(window, options) : type === "tv" ? client.trending.tv(window, options) : type === "person" ? client.trending.people(window, options) : client.trending.all(window, options);
+        },
+        output,
+        renderText: (response) => printSearchResults(response, type),
+        startPage: page
+      });
+    }, { paginated: true });
   }
 });
 
@@ -2806,6 +3202,7 @@ var tvCommand = defineCommand({
       },
       args: {
         ...commonArgs,
+        ...paginationArgs,
         category: {
           type: "positional",
           description: "popular, top-rated, airing-today, or on-the-air",
@@ -2817,17 +3214,20 @@ var tvCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const category = parseTVListCategory(args.category);
-          const options = { page: parsePage(args.page) };
+          const params = { page: parsePage(args.page) };
           const client = createClient({ language: args.lang });
-          const response = category === "top-rated" ? await client.tv.topRated(options) : category === "airing-today" ? await client.tv.airingToday(options) : category === "on-the-air" ? await client.tv.onTheAir(options) : await client.tv.popular(options);
-          if (args.json) {
-            printJson(response);
-          } else {
-            printSearchResults(response, "tv");
-          }
-        });
+          await printPaged({
+            fetchPage: (page) => {
+              const options = { ...params, page };
+              return category === "top-rated" ? client.tv.topRated(options) : category === "airing-today" ? client.tv.airingToday(options) : category === "on-the-air" ? client.tv.onTheAir(options) : client.tv.popular(options);
+            },
+            output,
+            renderText: (response) => printSearchResults(response, "tv"),
+            startPage: params.page
+          });
+        }, { paginated: true });
       }
     }),
     get: defineCommand({
@@ -2848,16 +3248,12 @@ var tvCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "TV show ID");
           const client = createClient({ language: args.lang });
           const appendToResponse = parseCommaList(args.append);
           const tv = await client.tv.details(id, { appendToResponse });
-          if (args.json) {
-            printJson(tv);
-          } else {
-            printTV(tv, client);
-          }
+          printResult(tv, output, () => printTV(tv, client));
         });
       }
     }),
@@ -2879,16 +3275,12 @@ var tvCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "TV show ID");
           const limit = parseLimit(args.limit);
           const client = createClient({ language: args.lang });
           const credits = await client.tv.credits(id);
-          if (args.json) {
-            printJson(credits);
-          } else {
-            printCredits(credits, limit);
-          }
+          printResult(credits, output, () => printCredits(credits, limit));
         });
       }
     }),
@@ -2910,16 +3302,12 @@ var tvCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "TV show ID");
           const includeImageLanguage = parseCommaList(args["image-language"]);
           const client = createClient({ language: args.lang });
           const images = await client.tv.images(id, { includeImageLanguage });
-          if (args.json) {
-            printJson(images);
-          } else {
-            printImages(images, client);
-          }
+          printResult(images, output, () => printImages(images, client));
         });
       }
     }),
@@ -2937,15 +3325,11 @@ var tvCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "TV show ID");
           const client = createClient({ language: args.lang });
           const videos = await client.tv.videos(id);
-          if (args.json) {
-            printJson(videos);
-          } else {
-            printVideos(videos);
-          }
+          printResult(videos, output, () => printVideos(videos));
         });
       }
     }),
@@ -2956,6 +3340,7 @@ var tvCommand = defineCommand({
       },
       args: {
         ...commonArgs,
+        ...paginationArgs,
         id: {
           type: "positional",
           description: "TMDB TV show ID",
@@ -2967,17 +3352,17 @@ var tvCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "TV show ID");
-          const options = { page: parsePage(args.page) };
+          const params = { page: parsePage(args.page) };
           const client = createClient({ language: args.lang });
-          const response = await client.tv.similar(id, options);
-          if (args.json) {
-            printJson(response);
-          } else {
-            printSearchResults(response, "tv");
-          }
-        });
+          await printPaged({
+            fetchPage: (page) => client.tv.similar(id, { ...params, page }),
+            output,
+            renderText: (response) => printSearchResults(response, "tv"),
+            startPage: params.page
+          });
+        }, { paginated: true });
       }
     }),
     recommendations: defineCommand({
@@ -2987,6 +3372,7 @@ var tvCommand = defineCommand({
       },
       args: {
         ...commonArgs,
+        ...paginationArgs,
         id: {
           type: "positional",
           description: "TMDB TV show ID",
@@ -2998,17 +3384,17 @@ var tvCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "TV show ID");
-          const options = { page: parsePage(args.page) };
+          const params = { page: parsePage(args.page) };
           const client = createClient({ language: args.lang });
-          const response = await client.tv.recommendations(id, options);
-          if (args.json) {
-            printJson(response);
-          } else {
-            printSearchResults(response, "tv");
-          }
-        });
+          await printPaged({
+            fetchPage: (page) => client.tv.recommendations(id, { ...params, page }),
+            output,
+            renderText: (response) => printSearchResults(response, "tv"),
+            startPage: params.page
+          });
+        }, { paginated: true });
       }
     }),
     season: defineCommand({
@@ -3030,16 +3416,251 @@ var tvCommand = defineCommand({
         }
       },
       async run({ args }) {
-        await runSafely(async () => {
+        await runSafely(args, async (output) => {
           const id = parseId(args.id, "TV show ID");
           const seasonNumber = parseSeasonNumber(args.season);
           const client = createClient({ language: args.lang });
           const season = await client.tv.seasonDetails(id, seasonNumber);
-          if (args.json) {
-            printJson(season);
-          } else {
-            printSeason(season, client);
-          }
+          printResult(season, output, () => printSeason(season, client));
+        });
+      }
+    }),
+    episode: defineCommand({
+      meta: {
+        name: "episode",
+        description: "Show a TV episode"
+      },
+      args: {
+        ...commonArgs,
+        id: {
+          type: "positional",
+          description: "TMDB TV show ID",
+          required: true
+        },
+        season: {
+          type: "positional",
+          description: "Season number (0 for specials)",
+          required: true
+        },
+        episode: {
+          type: "positional",
+          description: "Episode number",
+          required: true
+        },
+        append: {
+          type: "string",
+          description: "Comma-separated append_to_response values"
+        }
+      },
+      async run({ args }) {
+        await runSafely(args, async (output) => {
+          const id = parseId(args.id, "TV show ID");
+          const seasonNumber = parseSeasonNumber(args.season);
+          const episodeNumber = parseId(args.episode, "episode number");
+          const appendToResponse = parseCommaList(args.append);
+          const client = createClient({ language: args.lang });
+          const episode = await client.tv.episodeDetails(id, seasonNumber, episodeNumber, {
+            appendToResponse
+          });
+          printResult(episode, output, () => printEpisode(episode, client, id));
+        });
+      }
+    }),
+    "aggregate-credits": defineCommand({
+      meta: {
+        name: "aggregate-credits",
+        description: "Show aggregate cast and crew credits for a TV show"
+      },
+      args: {
+        ...commonArgs,
+        id: {
+          type: "positional",
+          description: "TMDB TV show ID",
+          required: true
+        },
+        limit: {
+          type: "string",
+          description: "Maximum cast/crew rows (default: 10)"
+        }
+      },
+      async run({ args }) {
+        await runSafely(args, async (output) => {
+          const id = parseId(args.id, "TV show ID");
+          const limit = parseLimit(args.limit);
+          const client = createClient({ language: args.lang });
+          const credits = await client.tv.aggregateCredits(id);
+          printResult(credits, output, () => printAggregateCredits(credits, limit));
+        });
+      }
+    }),
+    "season-credits": defineCommand({
+      meta: {
+        name: "season-credits",
+        description: "Show cast and crew credits for a TV season"
+      },
+      args: {
+        ...commonArgs,
+        id: {
+          type: "positional",
+          description: "TMDB TV show ID",
+          required: true
+        },
+        season: {
+          type: "positional",
+          description: "Season number (0 for specials)",
+          required: true
+        },
+        limit: {
+          type: "string",
+          description: "Maximum cast/crew rows (default: 10)"
+        }
+      },
+      async run({ args }) {
+        await runSafely(args, async (output) => {
+          const id = parseId(args.id, "TV show ID");
+          const seasonNumber = parseSeasonNumber(args.season);
+          const limit = parseLimit(args.limit);
+          const client = createClient({ language: args.lang });
+          const credits = await client.tv.seasonCredits(id, seasonNumber);
+          printResult(credits, output, () => printCredits(credits, limit));
+        });
+      }
+    }),
+    "season-aggregate-credits": defineCommand({
+      meta: {
+        name: "season-aggregate-credits",
+        description: "Show aggregate cast and crew credits for a TV season"
+      },
+      args: {
+        ...commonArgs,
+        id: {
+          type: "positional",
+          description: "TMDB TV show ID",
+          required: true
+        },
+        season: {
+          type: "positional",
+          description: "Season number (0 for specials)",
+          required: true
+        },
+        limit: {
+          type: "string",
+          description: "Maximum cast/crew rows (default: 10)"
+        }
+      },
+      async run({ args }) {
+        await runSafely(args, async (output) => {
+          const id = parseId(args.id, "TV show ID");
+          const seasonNumber = parseSeasonNumber(args.season);
+          const limit = parseLimit(args.limit);
+          const client = createClient({ language: args.lang });
+          const credits = await client.tv.seasonAggregateCredits(id, seasonNumber);
+          printResult(credits, output, () => printAggregateCredits(credits, limit));
+        });
+      }
+    }),
+    "season-images": defineCommand({
+      meta: {
+        name: "season-images",
+        description: "Show TV season image URLs"
+      },
+      args: {
+        ...commonArgs,
+        id: {
+          type: "positional",
+          description: "TMDB TV show ID",
+          required: true
+        },
+        season: {
+          type: "positional",
+          description: "Season number (0 for specials)",
+          required: true
+        },
+        "image-language": {
+          type: "string",
+          description: "Comma-separated image language codes"
+        }
+      },
+      async run({ args }) {
+        await runSafely(args, async (output) => {
+          const id = parseId(args.id, "TV show ID");
+          const seasonNumber = parseSeasonNumber(args.season);
+          const includeImageLanguage = parseCommaList(args["image-language"]);
+          const client = createClient({ language: args.lang });
+          const images = await client.tv.seasonImages(id, seasonNumber, { includeImageLanguage });
+          printResult(images, output, () => printSeasonImages(images, client));
+        });
+      }
+    }),
+    "season-videos": defineCommand({
+      meta: {
+        name: "season-videos",
+        description: "Show TV season videos and trailers"
+      },
+      args: {
+        ...commonArgs,
+        id: {
+          type: "positional",
+          description: "TMDB TV show ID",
+          required: true
+        },
+        season: {
+          type: "positional",
+          description: "Season number (0 for specials)",
+          required: true
+        }
+      },
+      async run({ args }) {
+        await runSafely(args, async (output) => {
+          const id = parseId(args.id, "TV show ID");
+          const seasonNumber = parseSeasonNumber(args.season);
+          const client = createClient({ language: args.lang });
+          const videos = await client.tv.seasonVideos(id, seasonNumber);
+          printResult(videos, output, () => printVideos(videos));
+        });
+      }
+    }),
+    "episode-groups": defineCommand({
+      meta: {
+        name: "episode-groups",
+        description: "List alternate episode groupings for a TV show"
+      },
+      args: {
+        ...commonArgs,
+        id: {
+          type: "positional",
+          description: "TMDB TV show ID",
+          required: true
+        }
+      },
+      async run({ args }) {
+        await runSafely(args, async (output) => {
+          const id = parseId(args.id, "TV show ID");
+          const client = createClient({ language: args.lang });
+          const groups = await client.tv.episodeGroups(id);
+          printResult(groups, output, () => printEpisodeGroups(groups));
+        });
+      }
+    }),
+    "episode-group": defineCommand({
+      meta: {
+        name: "episode-group",
+        description: "Show an alternate episode group"
+      },
+      args: {
+        ...commonArgs,
+        "group-id": {
+          type: "positional",
+          description: "TMDB episode group ID",
+          required: true
+        }
+      },
+      async run({ args }) {
+        await runSafely(args, async (output) => {
+          const groupId = parseGroupId(args["group-id"]);
+          const client = createClient({ language: args.lang });
+          const group = await client.tv.episodeGroup(groupId);
+          printResult(group, output, () => printEpisodeGroup(group));
         });
       }
     })
@@ -3082,12 +3703,82 @@ var AUTHENTICATION_HELP = [
 `);
 
 // src/cli/main.ts
-await runMain(mainCommand, { showUsage: showFullUsage });
-async function showFullUsage(cmd, parent) {
-  const path = await findPath(mainCommand, cmd);
-  if (!parent || !path || path.length === 0) {
-    const usage = await renderUsage(cmd);
-    const authentication = cmd === mainCommand ? `
+var rawArgs = process.argv.slice(2);
+if (rawArgs.length === 0) {
+  await showFullUsage(mainCommand);
+  process.exitCode = 1;
+} else if (rawArgs.some((arg) => arg === "--help" || arg === "-h")) {
+  await showFullUsage(await resolveCommand(rawArgs));
+} else if (isVersionRequest(rawArgs)) {
+  process.stdout.write(`${CLI_VERSION}
+`);
+} else {
+  try {
+    await runCommand(mainCommand, { rawArgs });
+  } catch (error) {
+    reportUsageError(error, rawArgs);
+  }
+}
+function reportUsageError(error, args) {
+  const output = outputFromArgs(args);
+  const message = stripAnsi(error instanceof Error ? error.message : String(error));
+  const usageError = new CliError(message, 2);
+  if (output.format === "json") {
+    process.stderr.write(`${JSON.stringify(toErrorRecord(usageError))}
+`);
+  } else {
+    process.stderr.write(`${message}
+`);
+  }
+  process.exitCode = 2;
+}
+function outputFromArgs(args) {
+  const outputArgs = {};
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      outputArgs.json = true;
+    } else if (arg === "--compact") {
+      outputArgs.compact = true;
+    } else if (arg === "--format") {
+      outputArgs.format = args[index + 1];
+      index += 1;
+    } else if (arg.startsWith("--format=")) {
+      outputArgs.format = arg.slice("--format=".length);
+    }
+  }
+  try {
+    return resolveOutput(outputArgs);
+  } catch {
+    return { compact: false, format: "text" };
+  }
+}
+function isVersionRequest(args) {
+  return args.length === 1 && (args[0] === "--version" || args[0] === "-v");
+}
+function stripAnsi(value) {
+  return value.replace(/\u001B\[[0-9;]*m/g, "");
+}
+async function resolveCommand(args) {
+  let command = mainCommand;
+  for (const arg of args) {
+    if (arg.startsWith("-")) {
+      continue;
+    }
+    const subCommands = await resolveValue2(command.subCommands);
+    const next = subCommands?.[arg];
+    if (next === undefined) {
+      break;
+    }
+    command = await resolveValue2(next);
+  }
+  return command;
+}
+async function showFullUsage(command) {
+  const path = await findPath(mainCommand, command);
+  if (!path || path.length === 0) {
+    const usage = await renderUsage(command);
+    const authentication = command === mainCommand ? `
 
 ${AUTHENTICATION_HELP}` : "";
     process.stdout.write(`${usage}${authentication}
@@ -3095,10 +3786,10 @@ ${AUTHENTICATION_HELP}` : "";
     return;
   }
   const parentName = ["tmdb", ...path.slice(0, -1)].join(" ");
-  const usageParent = defineCommand({
+  const parent = defineCommand({
     meta: { name: parentName, version: CLI_VERSION }
   });
-  process.stdout.write(`${await renderUsage(cmd, usageParent)}
+  process.stdout.write(`${await renderUsage(command, parent)}
 `);
 }
 async function findPath(root, target, path = []) {