shop-cli 0.1.0 → 0.1.2

package/dist/cli/help/registry.js

@@ -103,9 +103,19 @@ const flagAt = flag("--at <iso>", "Publish at a specific ISO timestamp");
 const flagNow = flag("--now", "Publish immediately");
 const flagUrl = flag("--url <url>", "URL (repeatable)");
 const flagFile = flag("--file <path>", "Local file path (repeatable)");
+const flagFilesUploadFilename = flag(
+  "--filename <name>",
+  "Override filename (only with exactly 1 --url, or with --file -)"
+);
 const flagAlt = flag("--alt <string>", "Alt text");
+const flagFilesUploadMimeType = flag("--mime-type <mime>", "Override MIME detection");
+const flagFilesUploadMediaType = flag("--media-type <type>", "FILE|IMAGE|VIDEO|MODEL_3D");
+const flagFilesUploadWait = flag("--wait", "Poll until fileStatus is READY or FAILED");
+const flagPollIntervalMs = flag("--poll-interval-ms <n>", "Poll interval in milliseconds (default: 1000)");
+const flagTimeoutMs = flag("--timeout-ms <n>", "Polling timeout in milliseconds (default: 600000)");
 const flagContentType = flag("--content-type <mime>", "Override detected content type");
 const flagMediaType = flag("--media-type <type>", "IMAGE|VIDEO|MODEL_3D|EXTERNAL_VIDEO");
+const flagMediaContentType = flag("--media-content-type <type>", "IMAGE|VIDEO|MODEL_3D|EXTERNAL_VIDEO");
 const flagAllowPartialUpdates = flag("--allow-partial-updates", "Allow partial updates");
 const flagStrategy = flag("--strategy <value>", "DEFAULT|PRESERVE_STANDALONE_VARIANT|REMOVE_STANDALONE_VARIANT");
 const flagOwnerType = flag("--owner-type <type>", "Owner type filter");
@@ -248,7 +258,7 @@ const flagExpiresAt = flag("--expires-at <iso>", "Expiration timestamp");
 const flagNotify = flag("--notify", "Notify");
 const flagToken = flag("--token <string>", "Access token");
 const flagItems = flag("--items <json>", "Items JSON");
-const flagPositions = flag("--positions <json>", "Positions JSON");
+const flagPositions = flag("--positions <json|@file>", "Positions JSON array (inline or @file.json)");
 const flagMoves = flag("--moves <json>", "Moves JSON array (or @file.json)");
 const flagMove = flag("--move <id>:<newPosition>", "Move entry (repeatable)");
 const flagMediaIds = flag("--media-ids <gid>", "Media IDs (repeatable)");
@@ -290,13 +300,28 @@ const flagContextsToAdd = flag("--contexts-to-add <json|@file>", "Catalog contex
 const flagContextsToRemove = flag("--contexts-to-remove <json|@file>", "Catalog contexts to remove (JSON)");
 const flagUpdatedAtSince = flag("--updated-at-since <iso>", "Only updated since timestamp");
 const flagBeforeUpdatedAt = flag("--before-updated-at <iso>", "Only updated before timestamp");
-const flagOptions = flag("--options <json|@file>", "Options JSON array (inline or @file.json)");
-const flagOption = flag("--option <json|@file>", "Option JSON object (inline or @file.json)");
-const flagOptionIds = flag("--option-ids <id,id,...>", "Option IDs (comma-separated or repeatable)");
+const flagOption = flag(
+  "--option <name=value1,value2,...>",
+  'Option spec (repeatable). Example: "Size=Small,Medium,Large".'
+);
+const flagOptionsJson = flag("--options-json <json|@file>", "Options JSON array (inline or @file.json)");
+const flagOptionJson = flag("--option-json <json|@file>", "Option JSON object (inline or @file.json)");
+const flagOptionId = flag("--option-id <gid>", "Option ID (repeatable or comma-separated)");
+const flagOptionName = flag("--option-name <string>", "Option name (repeatable or comma-separated)");
 const flagVariantStrategy = flag("--variant-strategy <value>", "Variant strategy");
-const flagOptionValuesToAdd = flag("--option-values-to-add <json|@file>", "Option values to add (JSON)");
-const flagOptionValuesToDelete = flag("--option-values-to-delete <json|@file>", "Option value IDs to delete (JSON)");
-const flagOptionValuesToUpdate = flag("--option-values-to-update <json|@file>", "Option values to update (JSON)");
+const flagAddValue = flag("--add-value <string>", "Add an option value (repeatable)");
+const flagDeleteValue = flag("--delete-value <string>", "Delete an option value by name (repeatable)");
+const flagRenameValue = flag("--rename-value <from=to>", "Rename an option value by name (repeatable)");
+const flagDeleteValueId = flag("--delete-value-id <gid>", "Delete an option value by ID (repeatable)");
+const flagRenameValueId = flag("--rename-value-id <gid=newName>", "Rename an option value by ID (repeatable)");
+const flagAddValuesJson = flag("--add-values-json <json|@file>", "Option values to add (JSON array)");
+const flagDeleteValueIdsJson = flag("--delete-value-ids-json <json|@file>", "Option value IDs to delete (JSON array)");
+const flagUpdateValuesJson = flag("--update-values-json <json|@file>", "Option values to update (JSON array)");
+const flagOrder = flag(
+  "--order <option[=value1,value2,...]>",
+  'Option order spec (repeatable). Example: "Size" or "Color=Green,Red,Blue".'
+);
+const flagPosition = flag("--position <n>", "1-based position");
 const flagParentProductId = flag("--parent-product-id <gid>", "Parent product ID");
 const flagProductsAdded = flag("--products-added <json|@file>", "Child products to add (JSON)");
 const flagProductsEdited = flag("--products-edited <json|@file>", "Child products to edit (JSON)");
@@ -343,63 +368,77 @@ const updateVerb = ({
 const getVerb = ({
   operation,
   description,
-  notes
+  notes,
+  examples,
+  flags
 }) => ({
   verb: "get",
   description,
   operation: { type: "query", name: operation },
   requiredFlags: [flagId],
   output: { view: true, selection: true },
-  notes
+  flags,
+  notes,
+  examples
 });
 const listVerb = ({
   operation,
   description,
   notes,
-  flags
+  flags,
+  examples
 }) => ({
   verb: "list",
   description,
   operation: { type: "query", name: operation },
   output: { view: true, selection: true, pagination: true },
   notes,
-  flags
+  flags,
+  examples
 });
 const deleteVerb = ({
   operation,
   description,
   requiredFlags = [],
-  notes
+  flags,
+  notes,
+  examples
 }) => ({
   verb: "delete",
   description,
   operation: { type: "mutation", name: operation },
   requiredFlags: [flagId, flagYes, ...requiredFlags],
-  notes
+  flags,
+  notes,
+  examples
 });
 const duplicateVerb = ({
   operation,
   description,
   requiredFlags = [],
   flags,
-  notes
+  notes,
+  examples
 }) => ({
   verb: "duplicate",
   description,
   operation: { type: "mutation", name: operation },
   requiredFlags: [flagId, ...requiredFlags],
   flags,
-  notes
+  notes,
+  examples
 });
 const countVerb = ({
   operation,
   description,
-  flags
+  flags,
+  examples
 }) => ({
   verb: "count",
   description,
   operation: { type: "query", name: operation },
-  flags
+  flags,
+  examples
 });
 const inputVerb = ({
   verb,
@@ -409,6 +448,7 @@ const inputVerb = ({
   requiredFlags = [],
   flags,
   notes,
+  examples,
   inputRequired = true,
   output
 }) => ({
@@ -419,6 +459,7 @@ const inputVerb = ({
   requiredFlags,
   flags,
   notes,
+  examples,
   output
 });
 const fieldsVerb = {
@@ -430,156 +471,295 @@ const baseCommandRegistry = [
   {
     resource: "products",
     description: "Manage products.",
+    notes: [
+      "To list products in a collection, use `shop collections list-products --id <collectionId>` or `shop collections list-products --handle <handle>`."
+    ],
     verbs: [
-      createVerb({ operation: "productCreate", description: "Create a new product." }),
-      getVerb({ operation: "product", description: "Fetch a product by ID." }),
+      createVerb({
+        operation: "productCreate",
+        description: "Create a new product.",
+        examples: [
+          'shop products create --set title="Summer Hat" --set status=DRAFT',
+          "shop products create --input @product.json"
+        ]
+      }),
+      getVerb({
+        operation: "product",
+        description: "Fetch a product by ID.",
+        flags: [flagProductId],
+        notes: [
+          "To list products in a collection, use `shop collections list-products --id <collectionId>` or `shop collections list-products --handle <handle>`."
+        ],
+        examples: [
+          "shop products get --id 123",
+          "shop products get --product-id 123",
+          "shop products get --id gid://shopify/Product/123 --view full"
+        ]
+      }),
       {
         verb: "by-handle",
         description: "Fetch a product by handle.",
         operation: { type: "query", name: "productByHandle" },
         requiredFlags: [flagHandle],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: [
+          'shop products by-handle --handle "summer-hat"'
+        ]
       },
       {
         verb: "by-identifier",
         description: "Fetch a product by identifier.",
         operation: { type: "query", name: "productByIdentifier" },
         requiredFlags: [flagIdentifierJsonFile],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: [
+          `shop products by-identifier --identifier '{"handle":"summer-hat"}'`
+        ]
       },
       listVerb({
         operation: "products",
         description: "List products.",
-        flags: [flagPublished]
+        flags: [flagPublished],
+        notes: [
+          "To list products in a collection, use `shop collections list-products --id <collectionId>` or `shop collections list-products --handle <handle>`."
+        ],
+        examples: [
+          "shop products list",
+          'shop products list --query "status:active"',
+          "shop products list --published --first 50"
+        ]
       }),
       countVerb({
         operation: "productsCount",
         description: "Count products.",
-        flags: [flagQuery, flagLimit, flagSavedSearchId]
+        flags: [flagQuery, flagLimit, flagSavedSearchId],
+        examples: [
+          "shop products count",
+          'shop products count --query "status:active"'
+        ]
       }),
       {
         verb: "tags",
         description: "List product tags in the shop.",
         operation: { type: "query", name: "productTags" },
-        output: { pagination: true }
+        output: { pagination: true },
+        examples: ["shop products tags"]
       },
       {
         verb: "types",
         description: "List product types in the shop.",
         operation: { type: "query", name: "productTypes" },
-        output: { pagination: true }
+        output: { pagination: true },
+        examples: ["shop products types"]
       },
       {
         verb: "vendors",
         description: "List product vendors in the shop.",
         operation: { type: "query", name: "productVendors" },
-        output: { pagination: true }
+        output: { pagination: true },
+        examples: ["shop products vendors"]
       },
-      updateVerb({ operation: "productUpdate", description: "Update a product." }),
-      deleteVerb({ operation: "productDelete", description: "Delete a product." }),
+      updateVerb({
+        operation: "productUpdate",
+        description: "Update a product.",
+        flags: [flagProductId],
+        examples: [
+          'shop products update --id 123 --set title="New Title"',
+          'shop products update --product-id 123 --set title="New Title"',
+          "shop products update --id 123 --input @updates.json"
+        ]
+      }),
+      deleteVerb({
+        operation: "productDelete",
+        description: "Delete a product.",
+        flags: [flagProductId],
+        examples: ["shop products delete --id 123 --yes"]
+      }),
       duplicateVerb({
         operation: "productDuplicate",
         description: "Duplicate a product.",
         flags: [
+          flagProductId,
           flagNewTitle,
           flagSet,
           flagSetJson
         ],
-        notes: ['You can also pass --set newTitle="..." to override the duplicate title.']
+        notes: ['You can also pass --set newTitle="..." to override the duplicate title.'],
+        examples: [
+          "shop products duplicate --id 123",
+          "shop products duplicate --product-id 123",
+          'shop products duplicate --id 123 --set newTitle="Copy of Product"'
+        ]
       }),
       {
         verb: "archive",
         description: "Archive a product (sets status=ARCHIVED).",
         operation: { type: "mutation", name: "productUpdate" },
         requiredFlags: [flagId],
-        output: { view: true, selection: true }
+        flags: [flagProductId],
+        output: { view: true, selection: true },
+        examples: ["shop products archive --id 123"]
       },
       {
         verb: "unarchive",
         description: "Unarchive a product (sets status=DRAFT by default).",
         operation: { type: "mutation", name: "productUpdate" },
         requiredFlags: [flagId],
-        flags: [flagStatus],
+        flags: [flagProductId, flagStatus],
         notes: ["Use --status to set the post-unarchive status (default: DRAFT)."],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: [
+          "shop products unarchive --id 123",
+          "shop products unarchive --product-id 123",
+          "shop products unarchive --id 123 --status ACTIVE"
+        ]
       },
       {
         verb: "set-status",
         description: "Set product status.",
         operation: { type: "mutation", name: "productUpdate" },
-        requiredFlags: [flagId, flagStatus]
+        requiredFlags: [flagId, flagStatus],
+        flags: [flagProductId],
+        examples: ["shop products set-status --id 123 --status ACTIVE"]
       },
       {
         verb: "change-status",
         description: "Change product status (deprecated).",
         operation: { type: "mutation", name: "productChangeStatus" },
         requiredFlags: [flagId, flagStatus],
-        notes: ["Prefer `shop products set-status` (productUpdate)."]
+        flags: [flagProductId],
+        notes: ["Prefer `shop products set-status` (productUpdate)."],
+        examples: ["shop products change-status --id 123 --status DRAFT"]
       },
       {
         verb: "set",
         description: "Create or update products via productSet.",
         operation: { type: "mutation", name: "productSet", inputArg: "input" },
         input: { mode: "set", arg: "input", required: true },
-        flags: [...inputFlags, flagIdentifierJsonFile, flagSynchronous]
+        flags: [...inputFlags, flagIdentifierJsonFile, flagSynchronous],
+        examples: [
+          "shop products set --input @product.json",
+          'shop products set --set title="Hat" --set productType="Accessories"'
+        ]
       },
       {
         verb: "operation",
         description: "Fetch a product operation by ID.",
         operation: { type: "query", name: "productOperation" },
         requiredFlags: [flagId],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: ["shop products operation --id gid://shopify/ProductSetOperation/123"]
       },
       {
         verb: "duplicate-job",
         description: "Fetch a product duplicate job by ID.",
         operation: { type: "query", name: "productDuplicateJob" },
         requiredFlags: [flagId],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: ["shop products duplicate-job --id gid://shopify/ProductDuplicateJob/123"]
       },
       {
         verb: "join-selling-plan-groups",
         description: "Join selling plan groups.",
         operation: { type: "mutation", name: "productJoinSellingPlanGroups" },
-        requiredFlags: [flagId, flagGroupIds]
+        requiredFlags: [flagId, flagGroupIds],
+        flags: [flagProductId],
+        examples: ["shop products join-selling-plan-groups --id 123 --group-ids 456"]
       },
       {
         verb: "leave-selling-plan-groups",
         description: "Leave selling plan groups.",
         operation: { type: "mutation", name: "productLeaveSellingPlanGroups" },
-        requiredFlags: [flagId, flagGroupIds]
+        requiredFlags: [flagId, flagGroupIds],
+        flags: [flagProductId],
+        examples: ["shop products leave-selling-plan-groups --id 123 --group-ids 456"]
       },
       {
-        verb: "option-update",
-        description: "Update a product option.",
-        operation: { type: "mutation", name: "productOptionUpdate" },
-        requiredFlags: [flagProductId, flagOption],
-        flags: [
-          flagOptionValuesToAdd,
-          flagOptionValuesToDelete,
-          flagOptionValuesToUpdate,
-          flagVariantStrategy
+        verb: "options list",
+        description: "List options for a product.",
+        operation: { type: "query", name: "product" },
+        requiredFlags: [flagProductId],
+        output: { view: true, selection: true },
+        notes: ["Product options are not paginated (no --after / Next page)."],
+        examples: [
+          "shop products options list --product-id 123",
+          "shop products options list --product-id 123 --view full"
         ]
       },
       {
-        verb: "options-create",
+        verb: "options create",
         description: "Create product options.",
         operation: { type: "mutation", name: "productOptionsCreate" },
-        requiredFlags: [flagProductId, flagOptions],
-        flags: [flagVariantStrategy]
+        requiredFlags: [flagProductId],
+        flags: [
+          flagVariantStrategy,
+          flagOption,
+          flagOptionsJson
+        ],
+        notes: ["Pass one or more --option entries, or use --options-json for advanced inputs."],
+        output: { view: true, selection: true },
+        examples: [
+          'shop products options create --product-id 123 --option "Size=Small,Medium,Large"',
+          'shop products options create --product-id 123 --option "Size=S,M,L" --option "Color=Red,Blue" --variant-strategy CREATE'
+        ]
       },
       {
-        verb: "options-delete",
+        verb: "options update",
+        description: "Update a product option.",
+        operation: { type: "mutation", name: "productOptionUpdate" },
+        requiredFlags: [flagProductId, flagOptionId],
+        flags: [
+          flagName,
+          flagPosition,
+          flagVariantStrategy,
+          flagAddValue,
+          flagDeleteValue,
+          flagRenameValue,
+          flagDeleteValueId,
+          flagRenameValueId,
+          flagOptionJson,
+          flagAddValuesJson,
+          flagDeleteValueIdsJson,
+          flagUpdateValuesJson
+        ],
+        notes: [
+          "Name-based value changes require fetching current option value IDs.",
+          "In --dry-run mode, prefer ID-based flags (e.g. --delete-value-id) or JSON flags."
+        ],
+        output: { view: true, selection: true },
+        examples: [
+          'shop products options update --product-id 123 --option-id 456 --name "Size"',
+          "shop products options update --product-id 123 --option-id 456 --add-value XL",
+          'shop products options update --product-id 123 --option-id 456 --rename-value "Medium=Med"'
+        ]
+      },
+      {
+        verb: "options delete",
         description: "Delete product options.",
         operation: { type: "mutation", name: "productOptionsDelete" },
-        requiredFlags: [flagProductId, flagOptionIds],
-        flags: [flagStrategy]
+        requiredFlags: [flagProductId],
+        flags: [flagOptionId, flagOptionName, flagStrategy],
+        notes: ["Pass one or more --option-id and/or --option-name entries."],
+        examples: [
+          'shop products options delete --product-id 123 --option-name "Color"',
+          "shop products options delete --product-id 123 --option-id gid://shopify/ProductOption/456"
+        ]
       },
       {
-        verb: "options-reorder",
+        verb: "options reorder",
         description: "Reorder product options and values.",
         operation: { type: "mutation", name: "productOptionsReorder" },
-        requiredFlags: [flagProductId, flagOptions]
+        requiredFlags: [flagProductId],
+        flags: [flagOrder, flagOptionsJson],
+        notes: [
+          'If you specify values (e.g. --order "Color=Green,Red,Blue"), you must include the full value order for that option.',
+          "In --dry-run mode, value reordering via --order is not supported (use --options-json)."
+        ],
+        output: { view: true, selection: true },
+        examples: [
+          'shop products options reorder --product-id 123 --order "Size" --order "Color"',
+          'shop products options reorder --product-id 123 --order "Color=Green,Red,Blue"'
+        ]
       },
       {
         verb: "combined-listing-update",
@@ -592,19 +772,93 @@ const baseCommandRegistry = [
           flagProductsEdited,
           flagProductsRemovedIds,
           flagOptionsAndValues
+        ],
+        examples: [
+          'shop products combined-listing-update --parent-product-id 123 --title "Combined Product"'
         ]
       },
       {
         verb: "add-tags",
         description: "Add tags to a product.",
         operation: { type: "mutation", name: "tagsAdd" },
-        requiredFlags: [flagId, flagTags]
+        requiredFlags: [flagId, flagTags],
+        flags: [flagProductId],
+        examples: ['shop products add-tags --id 123 --tags "sale,featured"']
       },
       {
         verb: "remove-tags",
         description: "Remove tags from a product.",
         operation: { type: "mutation", name: "tagsRemove" },
-        requiredFlags: [flagId, flagTags]
+        requiredFlags: [flagId, flagTags],
+        flags: [flagProductId],
+        examples: ['shop products remove-tags --id 123 --tags "clearance"']
+      },
+      {
+        verb: "variants list",
+        description: "List variants for a product.",
+        operation: { type: "query", name: "product" },
+        requiredFlags: [flagProductId],
+        flags: [flagFirst, flagAfter, flagSort, flagReverse],
+        output: { view: true, selection: true, pagination: true },
+        notes: ["This is product-scoped (no --query). For global search, use `shop product-variants list --query ...`."],
+        examples: ["shop products variants list --product-id 123"]
+      },
+      {
+        verb: "variants create",
+        description: "Create a single variant for a product.",
+        operation: { type: "mutation", name: "productVariantsBulkCreate" },
+        requiredFlags: [flagProductId, flag("--variant-option <name=value>", "Variant option value (repeatable)")],
+        flags: [
+          flag("--sku <string>", "SKU (sets inventoryItem.sku)"),
+          flag("--barcode <string>", "Barcode"),
+          flag("--price <amount>", "Price amount"),
+          flag("--compare-at-price <amount>", "Compare-at price amount"),
+          flag("--inventory-policy <value>", "DENY|CONTINUE"),
+          flagStrategy
+        ],
+        output: { view: true, selection: true },
+        notes: ["Uses productVariantsBulkCreate with a single-item variants array."],
+        examples: [
+          "shop products variants create --product-id 123 --variant-option Size=Large --price 29.99",
+          "shop products variants create --product-id 123 --variant-option Color=Red --variant-option Size=M --sku RED-M-001"
+        ]
+      },
+      {
+        verb: "variants update",
+        description: "Update a single variant for a product.",
+        operation: { type: "mutation", name: "productVariantsBulkUpdate" },
+        requiredFlags: [flagProductId, flagVariantId],
+        flags: [
+          flag("--variant-option <name=value>", "Variant option value (repeatable)"),
+          flag("--sku <string>", "SKU (sets inventoryItem.sku)"),
+          flag("--barcode <string>", "Barcode"),
+          flag("--price <amount>", "Price amount"),
+          flag("--compare-at-price <amount>", "Compare-at price amount"),
+          flag("--inventory-policy <value>", "DENY|CONTINUE"),
+          flagAllowPartialUpdates
+        ],
+        output: { view: true, selection: true },
+        notes: ["Uses productVariantsBulkUpdate with a single-item variants array."],
+        examples: [
+          "shop products variants update --product-id 123 --variant-id 456 --price 24.99",
+          "shop products variants update --product-id 123 --variant-id 456 --sku NEW-SKU --barcode 123456789"
+        ]
+      },
+      {
+        verb: "variants delete",
+        description: "Delete a single variant from a product.",
+        operation: { type: "mutation", name: "productVariantsBulkDelete" },
+        requiredFlags: [flagProductId, flagVariantId],
+        notes: ["Uses productVariantsBulkDelete with a single variant ID."],
+        examples: ["shop products variants delete --product-id 123 --variant-id 456"]
+      },
+      {
+        verb: "variants reorder",
+        description: "Move a single variant to a specific 1-based position.",
+        operation: { type: "mutation", name: "productVariantsBulkReorder" },
+        requiredFlags: [flagProductId, flagVariantId, flag("--position <n>", "1-based position")],
+        notes: ["Uses productVariantsBulkReorder with a single position entry."],
+        examples: ["shop products variants reorder --product-id 123 --variant-id 456 --position 1"]
       },
       {
         verb: "set-price",
@@ -615,116 +869,153 @@ const baseCommandRegistry = [
           flag("--compare-at-price <amount>", "Compare-at price amount"),
           flagProductId
         ],
-        notes: ["--product-id is required in --dry-run mode."]
+        notes: ["--product-id is required in --dry-run mode."],
+        examples: [
+          "shop products set-price --variant-id 456 --price 19.99",
+          "shop products set-price --variant-id 456 --price 19.99 --compare-at-price 29.99"
+        ]
       },
       {
         verb: "publish",
         description: "Publish a product to specific publications.",
         operation: { type: "mutation", name: "publishablePublish" },
         requiredFlags: [flagId],
-        flags: [flagPublicationId, flagPublication, flagAt, flagNow],
-        notes: ["Pass either --publication-id or --publication (name)."]
+        flags: [flagProductId, flagPublicationId, flagPublication, flagAt, flagNow],
+        notes: ["Pass either --publication-id or --publication (name)."],
+        examples: [
+          'shop products publish --id 123 --publication "Online Store"',
+          'shop products publish --product-id 123 --publication "Online Store"',
+          "shop products publish --id 123 --publication-id 456 --now"
+        ]
       },
       {
         verb: "unpublish",
         description: "Unpublish a product from specific publications.",
         operation: { type: "mutation", name: "publishableUnpublish" },
         requiredFlags: [flagId],
-        flags: [flagPublicationId, flagPublication],
-        notes: ["Pass either --publication-id or --publication (name)."]
+        flags: [flagProductId, flagPublicationId, flagPublication],
+        notes: ["Pass either --publication-id or --publication (name)."],
+        examples: [
+          'shop products unpublish --id 123 --publication "Online Store"',
+          'shop products unpublish --product-id 123 --publication "Online Store"'
+        ]
       },
       {
         verb: "publish-all",
         description: "Publish a product to all publications.",
         operation: { type: "mutation", name: "publishablePublish" },
         requiredFlags: [flagId],
-        flags: [flagAt, flagNow]
+        flags: [flagProductId, flagAt, flagNow],
+        examples: [
+          "shop products publish-all --id 123",
+          "shop products publish-all --product-id 123"
+        ]
       },
       {
         verb: "metafields upsert",
         description: "Upsert product metafields.",
         operation: { type: "mutation", name: "metafieldsSet", inputArg: "metafields" },
         input: { mode: "set", arg: "metafields", required: true },
-        requiredFlags: [flagId],
-        notes: ["Input can be a single object or { metafields: [...] }."]
+        requiredFlags: [flagProductId],
+        notes: ["Input can be a single object or { metafields: [...] }."],
+        examples: [
+          "shop products metafields upsert --product-id 123 --set namespace=custom --set key=color --set value=red --set type=single_line_text_field"
+        ]
       },
       {
         verb: "media add",
         description: "Attach remote media URLs to a product.",
         operation: { type: "mutation", name: "productUpdate" },
-        requiredFlags: [flagId, flagUrl],
-        flags: [flagAlt, flagMediaType]
+        requiredFlags: [flagProductId, flagUrl],
+        flags: [
+          flagAlt,
+          flagMediaType,
+          flagFilesUploadWait,
+          flagPollIntervalMs,
+          flagTimeoutMs
+        ],
+        notes: [
+          "Alias: --media-content-type is accepted as --media-type."
+        ],
+        examples: [
+          'shop products media add --product-id 123 --url "https://example.com/image.jpg"',
+          'shop products media add --product-id 123 --url "https://example.com/a.jpg" --url "https://example.com/b.jpg" --wait'
+        ]
       },
       {
         verb: "media upload",
         description: "Upload local files as product media.",
         operation: { type: "mutation", name: "productUpdate" },
-        requiredFlags: [flagId, flagFile],
-        flags: [flagAlt, flagContentType, flagMediaType]
+        requiredFlags: [flagProductId, flagFile],
+        flags: [
+          flagAlt,
+          flagFilesUploadFilename,
+          flagFilesUploadMimeType,
+          flagMediaType,
+          flagFilesUploadWait,
+          flagPollIntervalMs,
+          flagTimeoutMs
+        ],
+        notes: [
+          "To attach by URL, use `shop products media add --url ...`.",
+          "Use --file - to read from stdin; requires --filename.",
+          "Aliases: --content-type is accepted as --mime-type; --media-content-type is accepted as --media-type."
+        ],
+        examples: [
+          "shop products media upload --product-id 123 --file ./photo.jpg",
+          "shop products media upload --product-id 123 --file ./a.jpg --file ./b.jpg --wait",
+          "cat image.png | shop products media upload --product-id 123 --file - --filename image.png"
+        ]
       },
       {
         verb: "media list",
         description: "List media for a product.",
         operation: { type: "query", name: "product" },
-        requiredFlags: [flagId],
-        output: { pagination: true }
+        requiredFlags: [flagProductId],
+        output: { pagination: true },
+        examples: ["shop products media list --product-id 123"]
       },
       {
         verb: "media remove",
         description: "Remove media references from a product.",
         operation: { type: "mutation", name: "fileUpdate" },
-        requiredFlags: [flagId, flagMediaId],
-        notes: ["Repeat --media-id to remove multiple items."]
+        requiredFlags: [flagProductId, flagMediaId],
+        notes: ["Repeat --media-id to remove multiple items."],
+        examples: [
+          "shop products media remove --product-id 123 --media-id gid://shopify/MediaImage/1",
+          "shop products media remove --product-id 123 --media-id gid://shopify/MediaImage/1 --media-id gid://shopify/MediaImage/2"
+        ]
       },
       {
         verb: "media update",
         description: "Update media metadata (alt text).",
         operation: { type: "mutation", name: "fileUpdate" },
-        requiredFlags: [flagMediaId, flagAlt]
+        requiredFlags: [flagMediaId, flagAlt],
+        examples: ['shop products media update --media-id gid://shopify/MediaImage/1 --alt "Product photo"']
       },
       {
         verb: "media reorder",
-        description: "Reorder a product\u2019s media.",
+        description: "Reorder a product's media.",
         operation: { type: "mutation", name: "productReorderMedia" },
-        requiredFlags: [flagId],
-        flags: [flagMoves, flagMove],
-        notes: ["Pass either --moves or one or more --move entries."]
-      },
-      {
-        verb: "reorder-media",
-        description: "Reorder a product\u2019s media.",
-        operation: { type: "mutation", name: "productReorderMedia" },
-        requiredFlags: [flagId],
+        requiredFlags: [flagProductId],
         flags: [flagMoves, flagMove],
-        notes: ["Alias for `shop products media reorder`."]
-      },
-      {
-        verb: "create-media",
-        description: "Create media for a product (deprecated).",
-        operation: { type: "mutation", name: "productCreateMedia" },
-        requiredFlags: [flagProductId, flagMedia]
-      },
-      {
-        verb: "update-media",
-        description: "Update media for a product (deprecated).",
-        operation: { type: "mutation", name: "productUpdateMedia" },
-        requiredFlags: [flagProductId, flagMedia]
-      },
-      {
-        verb: "delete-media",
-        description: "Delete media from a product (deprecated).",
-        operation: { type: "mutation", name: "productDeleteMedia" },
-        requiredFlags: [flagProductId, flagMediaIds]
+        notes: ["Pass either --moves or one or more --move entries."],
+        examples: [
+          "shop products media reorder --product-id 123 --move gid://shopify/MediaImage/1:0",
+          `shop products media reorder --product-id 123 --moves '[{"id":"gid://shopify/MediaImage/1","newPosition":0}]'`
+        ]
       },
       inputVerb({
         verb: "bundle-create",
         description: "Create a product bundle.",
-        operation: "productBundleCreate"
+        operation: "productBundleCreate",
+        examples: ["shop products bundle-create --input @bundle.json"]
       }),
       inputVerb({
         verb: "bundle-update",
         description: "Update a product bundle.",
-        operation: "productBundleUpdate"
+        operation: "productBundleUpdate",
+        examples: ["shop products bundle-update --input @bundle.json"]
       })
     ]
   },
@@ -738,16 +1029,31 @@ const baseCommandRegistry = [
         input: { mode: "set", required: true },
         requiredFlags: [flagProductId],
         flags: [flagAllowPartialUpdates, flagStrategy],
-        notes: ["Input can be an array or { variants: [...] }."]
+        notes: ["Input can be an array or { variants: [...] }."],
+        examples: [
+          "shop product-variants upsert --product-id 123 --input @variants.json",
+          "shop product-variants upsert --product-id 123 --input @variants.json --allow-partial-updates --strategy PRESERVE_STANDALONE_VARIANT"
+        ]
       },
-      getVerb({ operation: "productVariant", description: "Fetch a variant by ID." }),
+      getVerb({
+        operation: "productVariant",
+        description: "Fetch a variant by ID.",
+        examples: [
+          "shop product-variants get --id 123",
+          "shop product-variants get --id 123 --view full"
+        ]
+      }),
       {
         verb: "get-by-identifier",
         description: "Fetch a variant by identifier (product + sku/barcode).",
         operation: { type: "query", name: "productVariantByIdentifier" },
         flags: [flagProductId, flag("--sku <string>", "SKU"), flag("--barcode <string>", "Barcode")],
         output: { view: true, selection: true },
-        notes: ["Provide --product-id plus --sku or --barcode, or pass --input."]
+        notes: ["Provide --product-id plus --sku or --barcode, or pass --input."],
+        examples: [
+          'shop product-variants get-by-identifier --product-id 123 --sku "SKU-123"',
+          "shop product-variants get-by-identifier --input @variant-identifier.json"
+        ]
       },
       {
         verb: "by-identifier",
@@ -755,23 +1061,49 @@ const baseCommandRegistry = [
         operation: { type: "query", name: "productVariantByIdentifier" },
         flags: [flagProductId, flag("--sku <string>", "SKU"), flag("--barcode <string>", "Barcode")],
         output: { view: true, selection: true },
-        notes: ["Alias for `shop product-variants get-by-identifier`."]
+        notes: ["Alias for `shop product-variants get-by-identifier`."],
+        examples: [
+          'shop product-variants by-identifier --product-id 123 --barcode "0123456789012"'
+        ]
       },
-      listVerb({ operation: "productVariants", description: "List product variants." }),
-      countVerb({ operation: "productVariantsCount", description: "Count product variants.", flags: [flagQuery] }),
+      listVerb({
+        operation: "productVariants",
+        description: "List product variants.",
+        examples: [
+          "shop product-variants list --first 10 --format table",
+          'shop product-variants list --query "sku:SKU-*" --first 50'
+        ]
+      }),
+      countVerb({
+        operation: "productVariantsCount",
+        description: "Count product variants.",
+        flags: [flagQuery],
+        examples: [
+          "shop product-variants count",
+          'shop product-variants count --query "sku:SKU-*"'
+        ]
+      }),
       inputVerb({
         verb: "bulk-create",
         description: "Bulk create variants for a product.",
         operation: "productVariantsBulkCreate",
         requiredFlags: [flagProductId],
-        flags: [flagAllowPartialUpdates]
+        flags: [flagAllowPartialUpdates],
+        output: { view: true, selection: true },
+        examples: [
+          "shop product-variants bulk-create --product-id 123 --input @variants.json"
+        ]
       }),
       inputVerb({
         verb: "bulk-update",
         description: "Bulk update variants for a product.",
         operation: "productVariantsBulkUpdate",
         requiredFlags: [flagProductId],
-        flags: [flagAllowPartialUpdates]
+        flags: [flagAllowPartialUpdates],
+        output: { view: true, selection: true },
+        examples: [
+          "shop product-variants bulk-update --product-id 123 --input @variants.json"
+        ]
       }),
       {
         verb: "bulk-delete",
@@ -779,44 +1111,72 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "productVariantsBulkDelete" },
         requiredFlags: [flagProductId, flagVariantIds],
         flags: [flagIds],
-        notes: ["Use --variant-ids or --ids."]
+        notes: ["Use --variant-ids or --ids."],
+        examples: [
+          "shop product-variants bulk-delete --product-id 123 --variant-ids 456,789",
+          "shop product-variants bulk-delete --product-id 123 --ids 456,789"
+        ]
       },
       {
         verb: "bulk-reorder",
         description: "Reorder variants for a product.",
         operation: { type: "mutation", name: "productVariantsBulkReorder" },
-        requiredFlags: [flagProductId, flagPositions]
+        requiredFlags: [flagProductId, flagPositions],
+        notes: ["Positions format: [{ id: <variant gid>, position: <int> }, ...]. Position is 1-based (first is 1)."],
+        examples: [
+          `shop product-variants bulk-reorder --product-id 123 --positions '[{"id":"gid://shopify/ProductVariant/1","position":1}]'`,
+          "shop product-variants bulk-reorder --product-id 123 --positions @positions.json"
+        ]
       },
       {
         verb: "append-media",
         description: "Append media to a variant.",
         operation: { type: "mutation", name: "productVariantAppendMedia" },
         requiredFlags: [flagId],
-        flags: [flagProductId, flagMediaIds, flagVariantMedia]
+        flags: [flagProductId, flagMediaIds, flagVariantMedia],
+        output: { view: true, selection: true },
+        examples: [
+          "shop product-variants append-media --id 123 --media-ids gid://shopify/MediaImage/1",
+          "shop product-variants append-media --id 123 --product-id 456 --variant-media @variant-media.json"
+        ]
       },
       {
         verb: "detach-media",
         description: "Detach media from a variant.",
         operation: { type: "mutation", name: "productVariantDetachMedia" },
         requiredFlags: [flagId],
-        flags: [flagProductId, flagMediaIds, flagVariantMedia]
+        flags: [flagProductId, flagMediaIds, flagVariantMedia],
+        output: { view: true, selection: true },
+        examples: [
+          "shop product-variants detach-media --id 123 --media-ids gid://shopify/MediaImage/1",
+          "shop product-variants detach-media --id 123 --product-id 456 --variant-media @variant-media.json"
+        ]
       },
       {
         verb: "join-selling-plans",
         description: "Join selling plan groups.",
         operation: { type: "mutation", name: "productVariantJoinSellingPlanGroups" },
-        requiredFlags: [flagId, flagGroupIds]
+        requiredFlags: [flagId, flagGroupIds],
+        examples: [
+          "shop product-variants join-selling-plans --id 123 --group-ids 456,789"
+        ]
       },
       {
         verb: "leave-selling-plans",
         description: "Leave selling plan groups.",
         operation: { type: "mutation", name: "productVariantLeaveSellingPlanGroups" },
-        requiredFlags: [flagId, flagGroupIds]
+        requiredFlags: [flagId, flagGroupIds],
+        examples: [
+          "shop product-variants leave-selling-plans --id 123 --group-ids 456,789"
+        ]
       },
       inputVerb({
         verb: "update-relationships",
         description: "Bulk update variant relationships.",
-        operation: "productVariantRelationshipBulkUpdate"
+        operation: "productVariantRelationshipBulkUpdate",
+        examples: [
+          "shop product-variants update-relationships --input @variant-relationships.json"
+        ]
       })
     ]
   },
@@ -887,52 +1247,102 @@ const baseCommandRegistry = [
     resource: "collections",
     description: "Manage collections.",
     verbs: [
-      createVerb({ operation: "collectionCreate", description: "Create a collection." }),
-      getVerb({ operation: "collection", description: "Fetch a collection by ID." }),
+      createVerb({
+        operation: "collectionCreate",
+        description: "Create a collection.",
+        examples: [
+          'shop collections create --set title="Summer collection"',
+          "shop collections create --input @collection.json"
+        ]
+      }),
+      getVerb({
+        operation: "collection",
+        description: "Fetch a collection by ID.",
+        examples: [
+          "shop collections get --id 123",
+          "shop collections get --id 123 --view full"
+        ]
+      }),
       {
         verb: "by-handle",
         description: "Fetch a collection by handle.",
         operation: { type: "query", name: "collectionByHandle" },
         requiredFlags: [flagHandle],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: ["shop collections by-handle --handle frontpage"]
       },
       {
         verb: "by-identifier",
         description: "Fetch a collection by identifier.",
         operation: { type: "query", name: "collectionByIdentifier" },
         requiredFlags: [flagIdentifierJsonFile],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: [`shop collections by-identifier --identifier '{"handle":"frontpage"}'`]
       },
       {
         verb: "rules-conditions",
         description: "List available smart collection rule conditions.",
         operation: { type: "query", name: "collectionRulesConditions" },
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: ["shop collections rules-conditions"]
       },
-      listVerb({ operation: "collections", description: "List collections." }),
+      listVerb({
+        operation: "collections",
+        description: "List collections.",
+        examples: [
+          "shop collections list --first 10 --format table",
+          'shop collections list --query "title:Summer"'
+        ]
+      }),
       countVerb({
         operation: "collectionsCount",
         description: "Count collections.",
-        flags: [flagQuery, flagLimit]
+        flags: [flagQuery, flagLimit],
+        examples: [
+          "shop collections count",
+          'shop collections count --query "title:Summer"'
+        ]
+      }),
+      updateVerb({
+        operation: "collectionUpdate",
+        description: "Update a collection.",
+        examples: [
+          'shop collections update --id 123 --set title="Updated collection title"',
+          "shop collections update --id 123 --input @collection-update.json"
+        ]
+      }),
+      deleteVerb({
+        operation: "collectionDelete",
+        description: "Delete a collection.",
+        examples: ["shop collections delete --id 123 --yes"]
       }),
-      updateVerb({ operation: "collectionUpdate", description: "Update a collection." }),
-      deleteVerb({ operation: "collectionDelete", description: "Delete a collection." }),
       duplicateVerb({
         operation: "collectionDuplicate",
         description: "Duplicate a collection.",
-        flags: [flag("--copy-publications", "Copy publication settings to the duplicate")]
+        flags: [flag("--copy-publications", "Copy publication settings to the duplicate")],
+        examples: [
+          "shop collections duplicate --id 123",
+          "shop collections duplicate --id 123 --copy-publications"
+        ]
       }),
       {
         verb: "add-products",
         description: "Add products to a collection.",
         operation: { type: "mutation", name: "collectionAddProductsV2" },
-        requiredFlags: [flagId, flag("--product-id <gid>", "Product IDs (repeatable or comma-separated)")]
+        requiredFlags: [flagId, flag("--product-id <gid>", "Product IDs (repeatable or comma-separated)")],
+        examples: [
+          "shop collections add-products --id 123 --product-id 456 --product-id 789",
+          "shop collections add-products --id 123 --product-id 456,789"
+        ]
       },
       {
         verb: "remove-products",
         description: "Remove products from a collection.",
         operation: { type: "mutation", name: "collectionRemoveProducts" },
-        requiredFlags: [flagId, flag("--product-id <gid>", "Product IDs (repeatable or comma-separated)")]
+        requiredFlags: [flagId, flag("--product-id <gid>", "Product IDs (repeatable or comma-separated)")],
+        examples: [
+          "shop collections remove-products --id 123 --product-id 456,789"
+        ]
       },
       {
         verb: "reorder-products",
@@ -940,7 +1350,26 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "collectionReorderProducts" },
         requiredFlags: [flagId],
         flags: [flagMoves, flagMove],
-        notes: ["Pass either --moves or one or more --move entries."]
+        notes: ["Pass either --moves or one or more --move entries."],
+        examples: [
+          "shop collections reorder-products --id 123 --move 456:0 --move 789:1",
+          `shop collections reorder-products --id 123 --moves '[{"id":"gid://shopify/Product/456","newPosition":0}]'`
+        ]
+      },
+      {
+        verb: "list-products",
+        description: "List products in a collection.",
+        operation: { type: "query", name: "products" },
+        flags: [flagId, flagHandle, flagPublished],
+        notes: [
+          "Pass exactly one of --id or --handle.",
+          "Supports the same flags as `shop products list`."
+        ],
+        output: { view: true, selection: true, pagination: true },
+        examples: [
+          "shop collections list-products --id 123",
+          "shop collections list-products --handle frontpage --published --format table"
+        ]
       },
       {
         verb: "publish",
@@ -948,7 +1377,11 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "collectionPublish" },
         requiredFlags: [flagId],
         flags: [flagPublicationId, flagPublication],
-        notes: ["Pass either --publication-id or --publication (name)."]
+        notes: ["Pass either --publication-id or --publication (name)."],
+        examples: [
+          'shop collections publish --id 123 --publication "Online Store"',
+          "shop collections publish --id 123 --publication-id gid://shopify/Publication/1"
+        ]
       },
       {
         verb: "unpublish",
@@ -956,7 +1389,11 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "collectionUnpublish" },
         requiredFlags: [flagId],
         flags: [flagPublicationId, flagPublication],
-        notes: ["Pass either --publication-id or --publication (name)."]
+        notes: ["Pass either --publication-id or --publication (name)."],
+        examples: [
+          'shop collections unpublish --id 123 --publication "Online Store"',
+          "shop collections unpublish --id 123 --publication-id gid://shopify/Publication/1"
+        ]
       }
     ]
   },
@@ -964,21 +1401,50 @@ const baseCommandRegistry = [
     resource: "customers",
     description: "Manage customers.",
     verbs: [
-      createVerb({ operation: "customerCreate", description: "Create a customer." }),
-      getVerb({ operation: "customer", description: "Fetch a customer by ID." }),
+      createVerb({
+        operation: "customerCreate",
+        description: "Create a customer.",
+        examples: [
+          'shop customers create --set email="jane.doe@example.com" --set firstName=Jane --set lastName=Doe',
+          "shop customers create --input @customer.json"
+        ]
+      }),
+      getVerb({
+        operation: "customer",
+        description: "Fetch a customer by ID.",
+        examples: [
+          "shop customers get --id 123",
+          "shop customers get --id 123 --view full"
+        ]
+      }),
       {
         verb: "by-identifier",
         description: "Fetch a customer by identifier.",
         operation: { type: "query", name: "customerByIdentifier" },
         flags: [flagEmailAddress, flagPhoneNumber, flagIdentifierId, flagCustomId],
         notes: ["Pass exactly one of --email-address, --phone-number, --identifier-id, --custom-id."],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: [
+          'shop customers by-identifier --email-address "jane.doe@example.com"',
+          'shop customers by-identifier --phone-number "+14155550123"'
+        ]
       },
-      listVerb({ operation: "customers", description: "List customers." }),
+      listVerb({
+        operation: "customers",
+        description: "List customers.",
+        examples: [
+          "shop customers list --first 10 --format table",
+          'shop customers list --query "email:jane.doe@example.com"'
+        ]
+      }),
       countVerb({
         operation: "customersCount",
         description: "Count customers.",
-        flags: [flagQuery, flagLimit]
+        flags: [flagQuery, flagLimit],
+        examples: [
+          "shop customers count",
+          'shop customers count --query "tag:vip" --limit 10000'
+        ]
       }),
       {
         verb: "set",
@@ -986,83 +1452,128 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "customerSet" },
         requiredFlags: [],
         flags: [...inputFlags, flagIdentifier],
-        notes: ["Input is CustomerSetInput JSON. Optionally pass --identifier (CustomerSetIdentifiers JSON)."]
+        notes: ["Input is CustomerSetInput JSON. Optionally pass --identifier (CustomerSetIdentifiers JSON)."],
+        examples: [
+          "shop customers set --input @customer-set.json",
+          "shop customers set --input @customer-set.json --identifier @customer-identifiers.json"
+        ]
       },
-      updateVerb({ operation: "customerUpdate", description: "Update a customer." }),
-      deleteVerb({ operation: "customerDelete", description: "Delete a customer." }),
+      updateVerb({
+        operation: "customerUpdate",
+        description: "Update a customer.",
+        examples: [
+          'shop customers update --id 123 --set note="VIP customer"',
+          "shop customers update --id 123 --input @customer-update.json"
+        ]
+      }),
+      deleteVerb({
+        operation: "customerDelete",
+        description: "Delete a customer.",
+        examples: ["shop customers delete --id 123 --yes"]
+      }),
       {
         verb: "address-create",
         description: "Create a customer address.",
         operation: { type: "mutation", name: "customerAddressCreate" },
         requiredFlags: [flagId, flagAddress],
-        flags: [flagSetAsDefault]
+        flags: [flagSetAsDefault],
+        examples: [
+          "shop customers address-create --id 123 --address @address.json --set-as-default true"
+        ]
       },
       {
         verb: "address-update",
         description: "Update a customer address.",
         operation: { type: "mutation", name: "customerAddressUpdate" },
         requiredFlags: [flagId, flagAddressId, flagAddress],
-        flags: [flagSetAsDefault]
+        flags: [flagSetAsDefault],
+        examples: [
+          "shop customers address-update --id 123 --address-id 456 --address @address.json"
+        ]
       },
       {
         verb: "address-delete",
         description: "Delete a customer address.",
         operation: { type: "mutation", name: "customerAddressDelete" },
-        requiredFlags: [flagId, flagAddressId]
+        requiredFlags: [flagId, flagAddressId],
+        examples: [
+          "shop customers address-delete --id 123 --address-id 456"
+        ]
       },
       {
         verb: "update-default-address",
         description: "Update a customer\u2019s default address.",
         operation: { type: "mutation", name: "customerUpdateDefaultAddress" },
-        requiredFlags: [flagId, flagAddressId]
+        requiredFlags: [flagId, flagAddressId],
+        examples: [
+          "shop customers update-default-address --id 123 --address-id 456"
+        ]
       },
       {
         verb: "email-marketing-consent-update",
         description: "Update a customer\u2019s email marketing consent.",
         operation: { type: "mutation", name: "customerEmailMarketingConsentUpdate" },
-        requiredFlags: [flagId, flagEmailMarketingConsent]
+        requiredFlags: [flagId, flagEmailMarketingConsent],
+        examples: [
+          "shop customers email-marketing-consent-update --id 123 --email-marketing-consent @email-consent.json"
+        ]
       },
       {
         verb: "sms-marketing-consent-update",
         description: "Update a customer\u2019s SMS marketing consent.",
         operation: { type: "mutation", name: "customerSmsMarketingConsentUpdate" },
-        requiredFlags: [flagId, flagSmsMarketingConsent]
+        requiredFlags: [flagId, flagSmsMarketingConsent],
+        examples: [
+          "shop customers sms-marketing-consent-update --id 123 --sms-marketing-consent @sms-consent.json"
+        ]
       },
       {
         verb: "add-tax-exemptions",
         description: "Add tax exemptions to a customer.",
         operation: { type: "mutation", name: "customerAddTaxExemptions" },
-        requiredFlags: [flagId, flagExemptions]
+        requiredFlags: [flagId, flagExemptions],
+        examples: [
+          "shop customers add-tax-exemptions --id 123 --exemptions CA_STATUS_CARD"
+        ]
       },
       {
         verb: "remove-tax-exemptions",
         description: "Remove tax exemptions from a customer.",
         operation: { type: "mutation", name: "customerRemoveTaxExemptions" },
-        requiredFlags: [flagId, flagExemptions]
+        requiredFlags: [flagId, flagExemptions],
+        examples: [
+          "shop customers remove-tax-exemptions --id 123 --exemptions CA_STATUS_CARD"
+        ]
       },
       {
         verb: "replace-tax-exemptions",
         description: "Replace tax exemptions on a customer.",
         operation: { type: "mutation", name: "customerReplaceTaxExemptions" },
-        requiredFlags: [flagId, flagExemptions]
+        requiredFlags: [flagId, flagExemptions],
+        examples: [
+          "shop customers replace-tax-exemptions --id 123 --exemptions CA_STATUS_CARD,CA_BC_RESELLER"
+        ]
       },
       {
         verb: "generate-account-activation-url",
         description: "Generate a one-time account activation URL (legacy accounts).",
         operation: { type: "mutation", name: "customerGenerateAccountActivationUrl" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: ["shop customers generate-account-activation-url --id 123"]
       },
       {
         verb: "request-data-erasure",
         description: "Request erasure of a customer\u2019s data.",
         operation: { type: "mutation", name: "customerRequestDataErasure" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: ["shop customers request-data-erasure --id 123"]
       },
       {
         verb: "cancel-data-erasure",
         description: "Cancel a pending customer data erasure request.",
         operation: { type: "mutation", name: "customerCancelDataErasure" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: ["shop customers cancel-data-erasure --id 123"]
       },
       {
         verb: "metafields upsert",
@@ -1070,46 +1581,65 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "metafieldsSet", inputArg: "metafields" },
         input: { mode: "set", arg: "metafields", required: true },
         requiredFlags: [flagId],
-        notes: ["Input can be a single object or { metafields: [...] }."]
+        notes: ["Input can be a single object or { metafields: [...] }."],
+        examples: [
+          "shop customers metafields upsert --id 123 --set namespace=custom --set key=vip --set type=single_line_text_field --set value=yes",
+          "shop customers metafields upsert --id 123 --input @metafields.json"
+        ]
       },
       {
         verb: "add-tags",
         description: "Add tags to a customer.",
         operation: { type: "mutation", name: "tagsAdd" },
-        requiredFlags: [flagId, flagTags]
+        requiredFlags: [flagId, flagTags],
+        examples: ['shop customers add-tags --id 123 --tags "vip,wholesale"']
       },
       {
         verb: "remove-tags",
         description: "Remove tags from a customer.",
         operation: { type: "mutation", name: "tagsRemove" },
-        requiredFlags: [flagId, flagTags]
+        requiredFlags: [flagId, flagTags],
+        examples: ['shop customers remove-tags --id 123 --tags "vip,wholesale"']
       },
       {
         verb: "merge",
         description: "Merge two customers.",
         operation: { type: "mutation", name: "customerMerge" },
         requiredFlags: [flagId, flag("--other-id <gid>", "Other customer ID to merge into --id")],
-        flags: [flag("--override-fields <json>", "Override fields JSON (optional)")]
+        flags: [flag("--override-fields <json>", "Override fields JSON (optional)")],
+        examples: [
+          "shop customers merge --id 123 --other-id 456",
+          "shop customers merge --id 123 --other-id 456 --override-fields @override-fields.json"
+        ]
       },
       {
         verb: "merge-preview",
         description: "Preview a customer merge request.",
         operation: { type: "query", name: "customerMergePreview" },
         requiredFlags: [flagId, flag("--other-id <gid>", "Other customer ID to merge into --id")],
-        flags: [flag("--override-fields <json>", "Override fields JSON (optional)")]
+        flags: [flag("--override-fields <json>", "Override fields JSON (optional)")],
+        examples: [
+          "shop customers merge-preview --id 123 --other-id 456",
+          "shop customers merge-preview --id 123 --other-id 456 --override-fields @override-fields.json"
+        ]
       },
       {
         verb: "merge-job-status",
         description: "Fetch customer merge job status.",
         operation: { type: "query", name: "customerMergeJobStatus" },
-        requiredFlags: [flagJobId]
+        requiredFlags: [flagJobId],
+        examples: ["shop customers merge-job-status --job-id 123"]
       },
       {
         verb: "send-invite",
         description: "Send a customer account invite email.",
         operation: { type: "mutation", name: "customerSendAccountInviteEmail" },
         requiredFlags: [flagId],
-        flags: [flag("--email <json>", "Email input JSON (optional)")]
+        flags: [flag("--email <json>", "Email input JSON (optional)")],
+        examples: [
+          "shop customers send-invite --id 123",
+          "shop customers send-invite --id 123 --email @invite-email.json"
+        ]
       }
     ]
   },
@@ -1264,27 +1794,65 @@ const baseCommandRegistry = [
     resource: "orders",
     description: "Manage orders.",
     verbs: [
-      createVerb({ operation: "orderCreate", description: "Create an order.", inputArg: "order" }),
-      getVerb({ operation: "order", description: "Fetch an order by ID." }),
-      listVerb({ operation: "orders", description: "List orders." }),
+      createVerb({
+        operation: "orderCreate",
+        description: "Create an order.",
+        inputArg: "order",
+        examples: [
+          "shop orders create --input @order.json"
+        ]
+      }),
+      getVerb({
+        operation: "order",
+        description: "Fetch an order by ID.",
+        examples: [
+          "shop orders get --id 123",
+          "shop orders get --id 123 --view full"
+        ]
+      }),
+      listVerb({
+        operation: "orders",
+        description: "List orders.",
+        examples: [
+          "shop orders list --first 10 --format table",
+          'shop orders list --query "financial_status:paid"'
+        ]
+      }),
       countVerb({
         operation: "ordersCount",
         description: "Count orders.",
-        flags: [flagQuery, flagLimit]
+        flags: [flagQuery, flagLimit],
+        examples: [
+          "shop orders count",
+          'shop orders count --query "status:open"'
+        ]
+      }),
+      updateVerb({
+        operation: "orderUpdate",
+        description: "Update an order.",
+        examples: [
+          'shop orders update --id 123 --set note="Internal note"',
+          "shop orders update --id 123 --input @order-update.json"
+        ]
+      }),
+      deleteVerb({
+        operation: "orderDelete",
+        description: "Delete an order.",
+        examples: ["shop orders delete --id 123 --yes"]
       }),
-      updateVerb({ operation: "orderUpdate", description: "Update an order." }),
-      deleteVerb({ operation: "orderDelete", description: "Delete an order." }),
       {
         verb: "add-tags",
         description: "Add tags to an order.",
         operation: { type: "mutation", name: "tagsAdd" },
-        requiredFlags: [flagId, flagTags]
+        requiredFlags: [flagId, flagTags],
+        examples: ['shop orders add-tags --id 123 --tags "priority,wholesale"']
       },
       {
         verb: "remove-tags",
         description: "Remove tags from an order.",
         operation: { type: "mutation", name: "tagsRemove" },
-        requiredFlags: [flagId, flagTags]
+        requiredFlags: [flagId, flagTags],
+        examples: ['shop orders remove-tags --id 123 --tags "priority,wholesale"']
       },
       {
         verb: "cancel",
@@ -1298,25 +1866,35 @@ const baseCommandRegistry = [
           flagReason,
           flagNotifyCustomer,
           flagStaffNote
+        ],
+        examples: [
+          "shop orders cancel --id 123",
+          "shop orders cancel --id 123 --refund --notify-customer --reason CUSTOMER"
         ]
       },
       {
         verb: "close",
         description: "Close an order.",
         operation: { type: "mutation", name: "orderClose" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: ["shop orders close --id 123"]
       },
       {
         verb: "mark-paid",
         description: "Mark an order as paid.",
         operation: { type: "mutation", name: "orderMarkAsPaid" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: ["shop orders mark-paid --id 123"]
       },
       {
         verb: "add-note",
         description: "Add a note to an order.",
         operation: { type: "mutation", name: "orderUpdate" },
-        requiredFlags: [flagId, flag("--note <string|@file>", "Order note text")]
+        requiredFlags: [flagId, flag("--note <string|@file>", "Order note text")],
+        examples: [
+          'shop orders add-note --id 123 --note "Packed and shipped"',
+          "shop orders add-note --id 123 --note @note.txt"
+        ]
       },
       {
         verb: "fulfill",
@@ -1330,6 +1908,9 @@ const baseCommandRegistry = [
           flagTrackingNumber,
           flagTrackingUrl,
           flagNotifyCustomer
+        ],
+        examples: [
+          "shop orders fulfill --id 123 --tracking-company UPS --tracking-number 1Z999AA10123456784 --notify-customer"
         ]
       },
       {
@@ -1341,13 +1922,18 @@ const baseCommandRegistry = [
           flagPaymentScheduleId,
           flag("--amount <json>", "MoneyInput JSON (optional)"),
           flagAutoCapture
+        ],
+        examples: [
+          'shop orders create-mandate-payment --id 123 --mandate-id gid://shopify/PaymentMandate/1 --idempotency-key "order-123-payment-1"',
+          'shop orders create-mandate-payment --id 123 --mandate-id gid://shopify/PaymentMandate/1 --idempotency-key "order-123-payment-1" --amount @money.json'
         ]
       },
       {
         verb: "transaction-void",
         description: "Void an uncaptured authorization transaction.",
         operation: { type: "mutation", name: "transactionVoid" },
-        requiredFlags: [flagParentTransactionId]
+        requiredFlags: [flagParentTransactionId],
+        examples: ["shop orders transaction-void --parent-transaction-id gid://shopify/OrderTransaction/1"]
       },
       {
         verb: "by-identifier",
@@ -1355,12 +1941,17 @@ const baseCommandRegistry = [
         operation: { type: "query", name: "orderByIdentifier" },
         flags: [flagId, flagCustomIdNamespace, flagCustomIdKey, flagCustomIdValue],
         notes: ["Provide either --id or --custom-id-key/--custom-id-value (optionally with --custom-id-namespace)."],
-        output: { view: true, selection: true }
+        output: { view: true, selection: true },
+        examples: [
+          "shop orders by-identifier --id 123",
+          "shop orders by-identifier --custom-id-namespace external --custom-id-key erp_id --custom-id-value 10001"
+        ]
       },
       {
         verb: "pending-count",
         description: "Get the count of pending orders.",
-        operation: { type: "query", name: "pendingOrdersCount" }
+        operation: { type: "query", name: "pendingOrdersCount" },
+        examples: ["shop orders pending-count"]
       },
       {
         verb: "payment-status",
@@ -1368,14 +1959,21 @@ const baseCommandRegistry = [
         operation: { type: "query", name: "orderPaymentStatus" },
         requiredFlags: [flagPaymentReferenceId],
         flags: [flagId, flagOrderId],
-        notes: ["Use --order-id to specify the order; otherwise uses --id."]
+        notes: ["Use --order-id to specify the order; otherwise uses --id."],
+        examples: [
+          'shop orders payment-status --payment-reference-id "pi_123" --order-id 456'
+        ]
       },
       {
         verb: "capture",
         description: "Capture an authorized payment for an order.",
         operation: { type: "mutation", name: "orderCapture" },
         requiredFlags: [flagId, flagParentTransactionId, flagAmount, flagCurrency],
-        flags: [flagFinalCapture]
+        flags: [flagFinalCapture],
+        examples: [
+          "shop orders capture --id 123 --parent-transaction-id gid://shopify/OrderTransaction/1 --amount 10.00 --currency USD",
+          "shop orders capture --id 123 --parent-transaction-id gid://shopify/OrderTransaction/1 --amount 10.00 --currency USD --final-capture true"
+        ]
       },
       {
         verb: "create-manual-payment",
@@ -1383,38 +1981,51 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "orderCreateManualPayment" },
         requiredFlags: [flagId],
         flags: [flagAmount, flagCurrency, flagPaymentMethodName, flagProcessedAt],
-        notes: ["If you pass --amount, you must also pass --currency."]
+        notes: ["If you pass --amount, you must also pass --currency."],
+        examples: [
+          'shop orders create-manual-payment --id 123 --amount 10.00 --currency USD --payment-method-name "Cash"'
+        ]
       },
       {
         verb: "invoice-send",
         description: "Send an invoice for an order.",
         operation: { type: "mutation", name: "orderInvoiceSend" },
         requiredFlags: [flagId],
-        flags: [flag("--email <json|@file>", "Email input JSON (optional)")]
+        flags: [flag("--email <json|@file>", "Email input JSON (optional)")],
+        examples: [
+          "shop orders invoice-send --id 123",
+          "shop orders invoice-send --id 123 --email @invoice-email.json"
+        ]
       },
       {
         verb: "open",
         description: "Open an order.",
         operation: { type: "mutation", name: "orderOpen" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: ["shop orders open --id 123"]
       },
       {
         verb: "customer-set",
         description: "Set a customer on an order.",
         operation: { type: "mutation", name: "orderCustomerSet" },
-        requiredFlags: [flagId, flagCustomerId]
+        requiredFlags: [flagId, flagCustomerId],
+        examples: ["shop orders customer-set --id 123 --customer-id 456"]
       },
       {
         verb: "customer-remove",
         description: "Remove the customer from an order.",
         operation: { type: "mutation", name: "orderCustomerRemove" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: ["shop orders customer-remove --id 123"]
       },
       {
         verb: "risk-assessment-create",
         description: "Create a risk assessment for an order.",
         operation: { type: "mutation", name: "orderRiskAssessmentCreate" },
-        requiredFlags: [flagId, flagRiskLevel, flagFacts]
+        requiredFlags: [flagId, flagRiskLevel, flagFacts],
+        examples: [
+          "shop orders risk-assessment-create --id 123 --risk-level HIGH --facts @facts.json"
+        ]
       }
     ]
   },
@@ -2097,26 +2708,58 @@ const baseCommandRegistry = [
         verb: "get",
         description: "Fetch a file by ID.",
         operation: { type: "query", name: "files" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: [
+          "shop files get --id 123",
+          "shop files get --id gid://shopify/File/123 --view full"
+        ]
       },
       {
         verb: "list",
         description: "List files.",
         operation: { type: "query", name: "files" },
-        output: { pagination: true }
+        output: { pagination: true },
+        examples: [
+          "shop files list --first 10 --format table",
+          'shop files list --query "file_status:ready"'
+        ]
       },
       {
         verb: "upload",
-        description: "Upload local files to Shopify.",
+        description: "Upload local files or URLs to Shopify.",
         operation: { type: "mutation", name: "fileCreate" },
-        requiredFlags: [flagFile],
-        flags: [flagAlt, flagContentType]
+        requiredFlags: [],
+        flags: [
+          flagFile,
+          flagUrl,
+          flagFilesUploadFilename,
+          flagAlt,
+          flagFilesUploadMimeType,
+          flagFilesUploadMediaType,
+          flagFilesUploadWait,
+          flagPollIntervalMs,
+          flagTimeoutMs
+        ],
+        notes: [
+          "Provide one or more --file or --url (but not both).",
+          "Use --file - to read from stdin; requires --filename.",
+          "Aliases: --resource and --content-type are accepted as --media-type."
+        ],
+        examples: [
+          "shop files upload --file ./cat.png",
+          "shop files upload --url https://example.com/cat.png --wait",
+          "shop files upload --url https://example.com/cat.png --filename kitten.png --mime-type image/png",
+          "cat ./cat.png | shop files upload --file - --filename cat.png --mime-type image/png"
+        ]
       },
       {
         verb: "update",
         description: "Update a file (alt text).",
         operation: { type: "mutation", name: "fileUpdate" },
-        requiredFlags: [flagId, flagAlt]
+        requiredFlags: [flagId, flagAlt],
+        examples: [
+          'shop files update --id 123 --alt "Hero image"'
+        ]
       },
       {
         verb: "acknowledge-update-failed",
@@ -2124,7 +2767,11 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "fileAcknowledgeUpdateFailed" },
         requiredFlags: [flagId],
         flags: [flagId, flagIds],
-        notes: ["Provide --id or --ids."]
+        notes: ["Provide --id or --ids."],
+        examples: [
+          "shop files acknowledge-update-failed --id 123",
+          "shop files acknowledge-update-failed --ids 123,456"
+        ]
       },
       {
         verb: "delete",
@@ -2132,7 +2779,11 @@ const baseCommandRegistry = [
         operation: { type: "mutation", name: "fileDelete" },
         requiredFlags: [flagYes],
         flags: [flagId, flagIds],
-        notes: ["Provide --id or --ids."]
+        notes: ["Provide --id or --ids."],
+        examples: [
+          "shop files delete --id 123 --yes",
+          "shop files delete --ids 123,456 --yes"
+        ]
       }
     ]
   },
@@ -2173,95 +2824,227 @@ const baseCommandRegistry = [
         verb: "authors",
         description: "List article authors.",
         operation: { type: "query", name: "articleAuthors" },
-        output: { pagination: true }
+        output: { pagination: true },
+        examples: [
+          "shop articles authors --first 25 --format table"
+        ]
       },
       {
         verb: "tags",
         description: "List article tags.",
         operation: { type: "query", name: "articleTags" },
         requiredFlags: [flagLimit],
-        flags: [flagSort, flagLimit]
+        flags: [flagSort, flagLimit],
+        examples: [
+          "shop articles tags --limit 50",
+          "shop articles tags --limit 100 --sort ALPHABETICAL"
+        ]
       },
-      createVerb({ operation: "articleCreate", description: "Create an article." }),
-      getVerb({ operation: "article", description: "Fetch an article by ID." }),
-      listVerb({ operation: "articles", description: "List articles." }),
-      updateVerb({ operation: "articleUpdate", description: "Update an article." }),
+      createVerb({
+        operation: "articleCreate",
+        description: "Create an article.",
+        examples: [
+          'shop articles create --set title="Hello world" --set author.name="Shop Admin"',
+          "shop articles create --input @article.json"
+        ]
+      }),
+      getVerb({
+        operation: "article",
+        description: "Fetch an article by ID.",
+        examples: [
+          "shop articles get --id 123",
+          "shop articles get --id 123 --view full"
+        ]
+      }),
+      listVerb({
+        operation: "articles",
+        description: "List articles.",
+        examples: [
+          "shop articles list --first 10 --format table",
+          'shop articles list --query "published_status:published"'
+        ]
+      }),
+      updateVerb({
+        operation: "articleUpdate",
+        description: "Update an article.",
+        examples: [
+          'shop articles update --id 123 --set title="Updated title"',
+          "shop articles update --id 123 --input @article-update.json"
+        ]
+      }),
       {
         verb: "publish",
         description: "Publish an article.",
         operation: { type: "mutation", name: "articleUpdate" },
         requiredFlags: [flagId],
-        flags: [flagAt, flagNow]
+        flags: [flagAt, flagNow],
+        examples: [
+          "shop articles publish --id 123 --now",
+          "shop articles publish --id 123 --at 2026-01-15T12:00:00Z"
+        ]
       },
       {
         verb: "unpublish",
         description: "Unpublish an article.",
         operation: { type: "mutation", name: "articleUpdate" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: [
+          "shop articles unpublish --id 123"
+        ]
       },
-      deleteVerb({ operation: "articleDelete", description: "Delete an article." })
+      deleteVerb({
+        operation: "articleDelete",
+        description: "Delete an article.",
+        examples: ["shop articles delete --id 123 --yes"]
+      })
     ]
   },
   {
     resource: "blogs",
     description: "Manage blogs.",
     verbs: [
-      createVerb({ operation: "blogCreate", description: "Create a blog." }),
-      getVerb({ operation: "blog", description: "Fetch a blog by ID." }),
-      listVerb({ operation: "blogs", description: "List blogs." }),
+      createVerb({
+        operation: "blogCreate",
+        description: "Create a blog.",
+        examples: [
+          'shop blogs create --set title="News"',
+          "shop blogs create --input @blog.json"
+        ]
+      }),
+      getVerb({
+        operation: "blog",
+        description: "Fetch a blog by ID.",
+        examples: [
+          "shop blogs get --id 123",
+          "shop blogs get --id 123 --view full"
+        ]
+      }),
+      listVerb({
+        operation: "blogs",
+        description: "List blogs.",
+        examples: [
+          "shop blogs list --format table",
+          "shop blogs list --first 25"
+        ]
+      }),
       {
         verb: "count",
         description: "Count blogs.",
         operation: { type: "query", name: "blogsCount" },
-        flags: [flagQuery, flagLimit]
+        flags: [flagQuery, flagLimit],
+        examples: [
+          "shop blogs count",
+          'shop blogs count --query "title:News"'
+        ]
       },
-      updateVerb({ operation: "blogUpdate", description: "Update a blog." }),
+      updateVerb({
+        operation: "blogUpdate",
+        description: "Update a blog.",
+        examples: [
+          'shop blogs update --id 123 --set title="Updated blog title"',
+          "shop blogs update --id 123 --input @blog-update.json"
+        ]
+      }),
       {
         verb: "publish",
         description: "Publish all articles in a blog.",
         operation: { type: "mutation", name: "articleUpdate" },
         requiredFlags: [flagId],
         flags: [flagAt, flagNow],
-        notes: ["Not supported in --dry-run mode (requires pagination)."]
+        notes: ["Not supported in --dry-run mode (requires pagination)."],
+        examples: [
+          "shop blogs publish --id 123 --now",
+          "shop blogs publish --id 123 --at 2026-01-15T12:00:00Z"
+        ]
       },
       {
         verb: "unpublish",
         description: "Unpublish all articles in a blog.",
         operation: { type: "mutation", name: "articleUpdate" },
         requiredFlags: [flagId],
-        notes: ["Not supported in --dry-run mode (requires pagination)."]
+        notes: ["Not supported in --dry-run mode (requires pagination)."],
+        examples: [
+          "shop blogs unpublish --id 123"
+        ]
       },
-      deleteVerb({ operation: "blogDelete", description: "Delete a blog." })
+      deleteVerb({
+        operation: "blogDelete",
+        description: "Delete a blog.",
+        examples: ["shop blogs delete --id 123 --yes"]
+      })
     ]
   },
   {
     resource: "pages",
     description: "Manage pages.",
     verbs: [
-      createVerb({ operation: "pageCreate", description: "Create a page." }),
-      getVerb({ operation: "page", description: "Fetch a page by ID." }),
-      listVerb({ operation: "pages", description: "List pages." }),
+      createVerb({
+        operation: "pageCreate",
+        description: "Create a page.",
+        examples: [
+          'shop pages create --set title="About us" --set body="<p>Welcome!</p>"',
+          "shop pages create --input @page.json"
+        ]
+      }),
+      getVerb({
+        operation: "page",
+        description: "Fetch a page by ID.",
+        examples: [
+          "shop pages get --id 123",
+          "shop pages get --id 123 --view full"
+        ]
+      }),
+      listVerb({
+        operation: "pages",
+        description: "List pages.",
+        examples: [
+          "shop pages list --first 10 --format table",
+          'shop pages list --query "title:About"'
+        ]
+      }),
       {
         verb: "count",
         description: "Count pages.",
         operation: { type: "query", name: "pagesCount" },
-        flags: [flagLimit]
+        flags: [flagLimit],
+        examples: [
+          "shop pages count",
+          "shop pages count --limit 1000"
+        ]
       },
-      updateVerb({ operation: "pageUpdate", description: "Update a page." }),
+      updateVerb({
+        operation: "pageUpdate",
+        description: "Update a page.",
+        examples: [
+          'shop pages update --id 123 --set title="Updated page title"',
+          "shop pages update --id 123 --input @page-update.json"
+        ]
+      }),
       {
         verb: "publish",
         description: "Publish a page.",
         operation: { type: "mutation", name: "pageUpdate" },
         requiredFlags: [flagId],
-        flags: [flagAt, flagNow]
+        flags: [flagAt, flagNow],
+        examples: [
+          "shop pages publish --id 123 --now",
+          "shop pages publish --id 123 --at 2026-01-15T12:00:00Z"
+        ]
       },
       {
         verb: "unpublish",
         description: "Unpublish a page.",
         operation: { type: "mutation", name: "pageUpdate" },
-        requiredFlags: [flagId]
+        requiredFlags: [flagId],
+        examples: [
+          "shop pages unpublish --id 123"
+        ]
       },
-      deleteVerb({ operation: "pageDelete", description: "Delete a page." })
+      deleteVerb({
+        operation: "pageDelete",
+        description: "Delete a page.",
+        examples: ["shop pages delete --id 123 --yes"]
+      })
     ]
   },
   {
@@ -2811,7 +3594,12 @@ const baseCommandRegistry = [
         verb: "create",
         description: "Create a subscription contract draft.",
         operation: "subscriptionContractCreate",
-        flags: [flagCustomerId]
+        flags: [flagCustomerId],
+        notes: [
+          "Returns a SubscriptionDraft (not a live contract).",
+          "Commit the draft with `shop subscription-drafts commit --id <draftId>` to apply changes.",
+          "If you want to create a live contract immediately, use `shop subscription-contracts atomic-create`."
+        ]
       }),
       inputVerb({
         verb: "atomic-create",
@@ -2824,7 +3612,11 @@ const baseCommandRegistry = [
         operation: "subscriptionContractUpdate",
         requiredFlags: [flagId],
         inputRequired: false,
-        notes: ["If no input is provided, returns a draft ID."]
+        notes: [
+          "Returns a SubscriptionDraft (not the live contract).",
+          "Changes remain in draft state until you commit with `shop subscription-drafts commit --id <draftId>`.",
+          "If no input is provided, returns a draft ID."
+        ]
       }),
       {
         verb: "activate",
@@ -5636,7 +6428,7 @@ const baseCommandRegistry = [
 const commandRegistry = baseCommandRegistry.map((spec) => {
   if (!resourcesWithFields.has(spec.resource)) return spec;
   if (spec.verbs.some((v) => v.verb === fieldsVerb.verb)) return spec;
-  return { ...spec, verbs: [...spec.verbs, fieldsVerb] };
+  return { ...spec, verbs: [...spec.verbs, { ...fieldsVerb, examples: [`shop ${spec.resource} fields`] }] };
 });
 const commonOutputFlags = [flagFormat, flagView, flagSelect, flagInclude, flagSelection, flagQuiet];
 const paginationFlags = [flagFirst, flagAfter, flagQuery, flagSort, flagReverse];