@@ -1,5 +1,20 @@
 # @opensea/cli
 
+## 2.12.0
+
+### Minor Changes
+
+- 92926ec: Add the collection group NFT search and facets endpoints (`GET /api/v2/nfts/group/{group}` and `GET /api/v2/nfts/group/{group}/facets`), which search NFTs across every collection in a group, such as `trading_cards`, by normalized attributes (franchise, grader, grade, subject, year, set, language, edition, product type).
+
+  In the SDK, `api.nfts.getNFTsByGroup(group, args?)` and `api.nfts.getNFTGroupFacets(group, args?)` take `GetNFTsByGroupArgs` and `GetNFTGroupFacetsArgs` and return `GetNFTsByGroupResponse` and `GetNFTGroupFacetsResponse`. Attribute filters are string arrays sent as repeated query parameters, since a comma-joined value is matched as one literal.
+
+  In the CLI, `opensea nfts list-by-group <group>` and `opensea nfts group-facets <group>` take repeatable attribute flags (`--grader PSA --grader CGC`), and the programmatic client gains `nfts.listByGroup` and `nfts.groupFacets`. The CLI HTTP client now sends an array query value as repeated parameters instead of `String(array)`. No existing command passed an array; they join comma-separated values themselves.
+
+### Patch Changes
+
+- Updated dependencies [92926ec]
+  - @opensea/sdk@12.12.0
+
 ## 2.11.3
 
 ### Patch Changes
 
@@ -175,12 +175,21 @@ opensea nfts get <chain> <contract> <token-id>
 opensea nfts list-by-collection <slug> [--limit <n>] [--next <cursor>]
 opensea nfts list-by-contract <chain> <contract> [--limit <n>] [--next <cursor>]
 opensea nfts list-by-account <chain> <address> [--limit <n>] [--next <cursor>] [--include-auto-hidden]
+opensea nfts list-by-group <group> [--franchise <v>] [--grader <v>] [--grade <v>] [--subject <v>] [--year <v>] [--set <v>] [--language <v>] [--edition <v>] [--product-type <v>] [--collection-slug <slug>] [--query <text>] [--is-listed <true|false>] [--min-estimated-value-usd <usd>] [--max-estimated-value-usd <usd>] [--sort-by <field>] [--sort-direction <dir>] [--limit <n>] [--next <cursor>]
+opensea nfts group-facets <group> [--facet-type <type>] [--collection-slug <slug>] [attribute filters]
 opensea nfts refresh <chain> <contract> <token-id>
 opensea nfts contract <chain> <address>
 ```
 
 `--include-auto-hidden` also returns NFTs hidden automatically because a third party minted or sent them to the account. NFTs the holder hid themselves stay hidden, and NFTs removed for policy violations are not returned.
 
+`list-by-group` searches every collection in a group, such as `trading_cards`, by normalized attributes. The attribute flags, `--collection-slug` and `--facet-type` are repeatable: values of one flag match any of them, and different flags are AND-combined. Use `group-facets` to discover the values and their counts.
+
+```bash
+opensea nfts group-facets trading_cards --facet-type grader --franchise Pokemon
+opensea nfts list-by-group trading_cards --franchise Pokemon --grader PSA --grader CGC --grade 10 --is-listed true --sort-by price --sort-direction asc
+```
+
 ## Listings
 
 ```bash
 
@@ -57,6 +57,17 @@ const { nfts, next } = await client.nfts.listByAccount("ethereum", "0x123...", {
   limit: 10,
 })
 
+const { nfts, next } = await client.nfts.listByGroup("trading_cards", {
+  franchise: ["Pokemon"],
+  grader: ["PSA", "CGC"],
+  isListed: true,
+  limit: 10,
+})
+
+const { facets } = await client.nfts.groupFacets("trading_cards", {
+  facetTypes: ["grader"],
+})
+
 await client.nfts.refresh("ethereum", "0x123...", "1")
 
 const contract = await client.nfts.getContract("ethereum", "0x123...")
 
@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "2.11.3",
+  "version": "2.12.0",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@opensea/api-types": "^0.16.1",
-    "@opensea/sdk": "^12.11.4",
+    "@opensea/sdk": "^12.12.0",
     "@opensea/wallet-adapters": "^1.2.1",
     "commander": "^14.0.3",
     "zod": "^4.3.6"
 
@@ -74,7 +74,15 @@ function parseRetryAfter(header: string | null): number | undefined {
 function appendParams(url: URL, params?: Record<string, unknown>): void {
   if (!params) return
   for (const [key, value] of Object.entries(params)) {
-    if (value !== undefined && value !== null) {
+    if (Array.isArray(value)) {
+      // Repeated, not comma-joined: `?grader=PSA&grader=CGC`. Endpoints that
+      // want one comma-separated value get a joined string from the caller.
+      for (const item of value) {
+        if (item !== undefined && item !== null) {
+          url.searchParams.append(key, String(item))
+        }
+      }
+    } else if (value !== undefined && value !== null) {
       url.searchParams.set(key, String(value))
     }
   }
 
@@ -8,6 +8,7 @@ import {
   addChainOption,
   addPaginationOptions,
   addSortDirectionOption,
+  parseBooleanOption,
   parseIntOption,
   readJsonBodyOption,
 } from "../parse.js"
@@ -36,13 +37,6 @@ const PAGE_MEDIA_PLACEMENTS = [
   "team",
 ]
 
-function parseBooleanOption(value: string, flag: string): boolean {
-  if (value !== "true" && value !== "false") {
-    throw new Error(`${flag} must be 'true' or 'false'`)
-  }
-  return value === "true"
-}
-
 export function collectionsCommand(
   getClient: () => OpenSeaClient,
   getFormat: () => OutputFormat,
 
@@ -4,7 +4,11 @@ import type { OutputFormat } from "../output.js"
 import { formatOutput, outputGet } from "../output.js"
 import {
   addPaginationOptions,
+  addSortDirectionOption,
   addTraitsOption,
+  collectOption,
+  parseBooleanOption,
+  parseFloatOption,
   parseIntOption,
   parseTraitsOption,
   readJsonBodyOption,
@@ -16,6 +20,44 @@ import type {
   ValidateMetadataResponse,
 } from "../types/index.js"
 
+/** [CLI flag, Commander option key, wire parameter] per normalized attribute. */
+const GROUP_FACET_FILTERS = [
+  ["franchise", "franchise", "franchise"],
+  ["grader", "grader", "grader"],
+  ["grade", "grade", "grade"],
+  ["subject", "subject", "subject"],
+  ["year", "year", "year"],
+  ["set", "set", "set"],
+  ["language", "language", "language"],
+  ["edition", "edition", "edition"],
+  ["product-type", "productType", "product_type"],
+] as const
+
+type GroupFacetFilterOptions = Partial<
+  Record<(typeof GROUP_FACET_FILTERS)[number][1], string[]>
+>
+
+function addGroupFacetFilterOptions(cmd: Command): Command {
+  for (const [flag, , wire] of GROUP_FACET_FILTERS) {
+    cmd.option(
+      `--${flag} <value>`,
+      `Only NFTs whose normalized ${wire.replace("_", " ")} is this value (repeatable, matches any)`,
+      collectOption,
+    )
+  }
+  return cmd
+}
+
+function groupFacetFilterParams(
+  options: GroupFacetFilterOptions,
+): Record<string, string[] | undefined> {
+  const params: Record<string, string[] | undefined> = {}
+  for (const [, key, wire] of GROUP_FACET_FILTERS) {
+    params[wire] = options[key]
+  }
+  return params
+}
+
 export function nftsCommand(
   getClient: () => OpenSeaClient,
   getFormat: () => OutputFormat,
@@ -120,6 +162,122 @@ export function nftsCommand(
       },
     )
 
+  addGroupFacetFilterOptions(
+    addSortDirectionOption(
+      addPaginationOptions(
+        cmd
+          .command("list-by-group")
+          .description(
+            "Search NFTs across a collection group by normalized attributes",
+          )
+          .argument("<group>", "Collection group (e.g. trading_cards)"),
+        "Number of results (max 100)",
+      ),
+    )
+      .option(
+        "--collection-slug <slug>",
+        "Restrict to this collection in the group (repeatable, max 10)",
+        collectOption,
+      )
+      .option("--query <text>", "Full-text match on NFT name")
+      .option("--is-listed <bool>", "Only listed (true) or unlisted (false)")
+      .option(
+        "--min-estimated-value-usd <usd>",
+        "Minimum estimated value in USD, inclusive",
+      )
+      .option(
+        "--max-estimated-value-usd <usd>",
+        "Maximum estimated value in USD, inclusive",
+      )
+      .option(
+        "--sort-by <field>",
+        "Sort field (price, top_offer, last_sale, last_sale_date, created_date, received_date, listing_created_date, best_deal, estimated_value)",
+      ),
+  ).action(
+    async (
+      group: string,
+      options: GroupFacetFilterOptions & {
+        limit: string
+        next?: string
+        collectionSlug?: string[]
+        query?: string
+        isListed?: string
+        minEstimatedValueUsd?: string
+        maxEstimatedValueUsd?: string
+        sortBy?: string
+        sortDirection?: string
+      },
+    ) => {
+      const client = getClient()
+      await outputGet(client, getFormat(), `/api/v2/nfts/group/${group}`, {
+        collection_slugs: options.collectionSlug,
+        query: options.query,
+        is_listed:
+          options.isListed === undefined
+            ? undefined
+            : parseBooleanOption(options.isListed, "--is-listed"),
+        min_estimated_value_usd:
+          options.minEstimatedValueUsd === undefined
+            ? undefined
+            : parseFloatOption(
+                options.minEstimatedValueUsd,
+                "--min-estimated-value-usd",
+              ),
+        max_estimated_value_usd:
+          options.maxEstimatedValueUsd === undefined
+            ? undefined
+            : parseFloatOption(
+                options.maxEstimatedValueUsd,
+                "--max-estimated-value-usd",
+              ),
+        sort_by: options.sortBy,
+        sort_direction: options.sortDirection,
+        limit: parseIntOption(options.limit, "--limit"),
+        next: options.next,
+        ...groupFacetFilterParams(options),
+      })
+    },
+  )
+
+  addGroupFacetFilterOptions(
+    cmd
+      .command("group-facets")
+      .description(
+        "Get normalized attribute values and NFT counts for a collection group",
+      )
+      .argument("<group>", "Collection group (e.g. trading_cards)")
+      .option(
+        "--facet-type <type>",
+        "Only return this facet type, e.g. grader (repeatable)",
+        collectOption,
+      )
+      .option(
+        "--collection-slug <slug>",
+        "Restrict counts to this collection in the group (repeatable, max 10)",
+        collectOption,
+      ),
+  ).action(
+    async (
+      group: string,
+      options: GroupFacetFilterOptions & {
+        facetType?: string[]
+        collectionSlug?: string[]
+      },
+    ) => {
+      const client = getClient()
+      await outputGet(
+        client,
+        getFormat(),
+        `/api/v2/nfts/group/${group}/facets`,
+        {
+          facet_types: options.facetType,
+          collection_slugs: options.collectionSlug,
+          ...groupFacetFilterParams(options),
+        },
+      )
+    },
+  )
+
   cmd
     .command("refresh")
     .description("Refresh NFT metadata")
 
@@ -36,6 +36,18 @@ export function parseIntOption(value: string, name: string): number {
   return parsed
 }
 
+export function parseBooleanOption(value: string, flag: string): boolean {
+  if (value !== "true" && value !== "false") {
+    throw new Error(`${flag} must be 'true' or 'false'`)
+  }
+  return value === "true"
+}
+
+/** Commander argParser for a repeatable option: `--x a --x b` → `["a", "b"]`. */
+export function collectOption(value: string, previous?: string[]): string[] {
+  return [...(previous ?? []), value]
+}
+
 export function parseFloatOption(value: string, name: string): number {
   const parsed = Number(value)
   if (