Create shopify theme metafields pull command

.changeset/nervous-terms-invite.md

@@ -0,0 +1,8 @@
+---
+'@shopify/theme': minor
+'@shopify/cli': minor
+---
+
+New CLI command under `shopify theme` to pull metafield definitions from the shop
+
+Run command by calling `shopify theme metafields pull`

.changeset/quick-eggs-end.md

@@ -0,0 +1,5 @@
+---
+'@shopify/cli-kit': patch
+---
+
+Introduce method to fetch metafield definitions by ownerType from Admin API

docs-shopify.dev/commands/examples/theme-metafields-pull.example.sh

@@ -0,0 +1 @@
+shopify theme metafields pull [flags]

docs-shopify.dev/commands/interfaces/theme-metafields-pull.interface.ts

@@ -0,0 +1,32 @@
+// This is an autogenerated file. Don't edit this file manually.
+export interface thememetafieldspull {
+  /**
+   * Disable color output.
+   * @environment SHOPIFY_FLAG_NO_COLOR
+   */
+  '--no-color'?: ''
+
+  /**
+   * Password generated from the Theme Access app.
+   * @environment SHOPIFY_CLI_THEME_TOKEN
+   */
+  '--password <value>'?: string
+
+  /**
+   * The path to your theme directory.
+   * @environment SHOPIFY_FLAG_PATH
+   */
+  '--path <value>'?: string
+
+  /**
+   * Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).
+   * @environment SHOPIFY_FLAG_STORE
+   */
+  '-s, --store <value>'?: string
+
+  /**
+   * Increase the verbosity of the output.
+   * @environment SHOPIFY_FLAG_VERBOSE
+   */
+  '--verbose'?: ''
+}

docs-shopify.dev/commands/theme-metafields-pull.doc.ts

@@ -0,0 +1,36 @@
+// This is an autogenerated file. Don't edit this file manually.
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'theme metafields pull',
+  description: `Retrieves metafields from Shopify Admin.
+
+If the metafields file already exists, it will be overwritten.`,
+  overviewPreviewDescription: `Download metafields defined on Shopify Admin into a local file.`,
+  type: 'command',
+  isVisualComponent: false,
+  defaultExample: {
+    codeblock: {
+      tabs: [
+        {
+          title: 'theme metafields pull',
+          code: './examples/theme-metafields-pull.example.sh',
+          language: 'bash',
+        },
+      ],
+      title: 'theme metafields pull',
+    },
+  },
+  definitions: [
+  {
+    title: 'Flags',
+    description: 'The following flags are available for the `theme metafields pull` command:',
+    type: 'thememetafieldspull',
+  },
+  ],
+  category: 'theme',
+  related: [
+  ],
+}
+
+export default data

docs-shopify.dev/generated/generated_docs_data.json

@@ -5332,6 +5332,89 @@
     "category": "theme",
     "related": []
   },
+  {
+    "name": "theme metafields pull",
+    "description": "Retrieves metafields from Shopify Admin.\n\nIf the metafields file already exists, it will be overwritten.",
+    "overviewPreviewDescription": "Download metafields defined on Shopify Admin into a local file.",
+    "type": "command",
+    "isVisualComponent": false,
+    "defaultExample": {
+      "codeblock": {
+        "tabs": [
+          {
+            "title": "theme metafields pull",
+            "code": "shopify theme metafields pull [flags]",
+            "language": "bash"
+          }
+        ],
+        "title": "theme metafields pull"
+      }
+    },
+    "definitions": [
+      {
+        "title": "Flags",
+        "description": "The following flags are available for the `theme metafields pull` command:",
+        "type": "thememetafieldspull",
+        "typeDefinitions": {
+          "thememetafieldspull": {
+            "filePath": "docs-shopify.dev/commands/interfaces/theme-metafields-pull.interface.ts",
+            "name": "thememetafieldspull",
+            "description": "",
+            "members": [
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/theme-metafields-pull.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--no-color",
+                "value": "\"\"",
+                "description": "Disable color output.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_NO_COLOR"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/theme-metafields-pull.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--password <value>",
+                "value": "string",
+                "description": "Password generated from the Theme Access app.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_CLI_THEME_TOKEN"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/theme-metafields-pull.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--path <value>",
+                "value": "string",
+                "description": "The path to your theme directory.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_PATH"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/theme-metafields-pull.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--verbose",
+                "value": "\"\"",
+                "description": "Increase the verbosity of the output.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_VERBOSE"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/theme-metafields-pull.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "-s, --store <value>",
+                "value": "string",
+                "description": "Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_STORE"
+              }
+            ],
+            "value": "export interface thememetafieldspull {\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Password generated from the Theme Access app.\n   * @environment SHOPIFY_CLI_THEME_TOKEN\n   */\n  '--password <value>'?: string\n\n  /**\n   * The path to your theme directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Store URL. It can be the store prefix (example) or the full myshopify.com URL (example.myshopify.com, https://example.myshopify.com).\n   * @environment SHOPIFY_FLAG_STORE\n   */\n  '-s, --store <value>'?: string\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+          }
+        }
+      }
+    ],
+    "category": "theme",
+    "related": []
+  },
   {
     "name": "theme open",
     "description": "Returns links that let you preview the specified theme. The following links are returned:\n\n  - A link to the [editor](/docs/themes/tools/online-editor) for the theme in the Shopify admin.\n  - A [preview link](https://help.shopify.com/manual/online-store/themes/adding-themes#share-a-theme-preview-with-others) that you can share with other developers.\n\n  If you don't specify a theme, then you're prompted to select the theme to open from the list of the themes in your store.",

packages/cli-kit/src/cli/api/graphql/admin/generated/metafield_definitions_by_owner_type.ts

@@ -0,0 +1,80 @@
+/* eslint-disable @typescript-eslint/consistent-type-definitions */
+import * as Types from './types.js'
+
+import {TypedDocumentNode as DocumentNode} from '@graphql-typed-document-node/core'
+
+export type MetafieldDefinitionsByOwnerTypeQueryVariables = Types.Exact<{
+  ownerType: Types.MetafieldOwnerType
+}>
+
+export type MetafieldDefinitionsByOwnerTypeQuery = {
+  metafieldDefinitions: {
+    nodes: {name: string; namespace: string; description?: string | null; type: {category: string; name: string}}[]
+  }
+}
+
+export const MetafieldDefinitionsByOwnerType = {
+  kind: 'Document',
+  definitions: [
+    {
+      kind: 'OperationDefinition',
+      operation: 'query',
+      name: {kind: 'Name', value: 'metafieldDefinitionsByOwnerType'},
+      variableDefinitions: [
+        {
+          kind: 'VariableDefinition',
+          variable: {kind: 'Variable', name: {kind: 'Name', value: 'ownerType'}},
+          type: {kind: 'NonNullType', type: {kind: 'NamedType', name: {kind: 'Name', value: 'MetafieldOwnerType'}}},
+        },
+      ],
+      selectionSet: {
+        kind: 'SelectionSet',
+        selections: [
+          {
+            kind: 'Field',
+            name: {kind: 'Name', value: 'metafieldDefinitions'},
+            arguments: [
+              {
+                kind: 'Argument',
+                name: {kind: 'Name', value: 'ownerType'},
+                value: {kind: 'Variable', name: {kind: 'Name', value: 'ownerType'}},
+              },
+              {kind: 'Argument', name: {kind: 'Name', value: 'first'}, value: {kind: 'IntValue', value: '250'}},
+            ],
+            selectionSet: {
+              kind: 'SelectionSet',
+              selections: [
+                {
+                  kind: 'Field',
+                  name: {kind: 'Name', value: 'nodes'},
+                  selectionSet: {
+                    kind: 'SelectionSet',
+                    selections: [
+                      {kind: 'Field', name: {kind: 'Name', value: 'name'}},
+                      {kind: 'Field', name: {kind: 'Name', value: 'namespace'}},
+                      {kind: 'Field', name: {kind: 'Name', value: 'description'}},
+                      {
+                        kind: 'Field',
+                        name: {kind: 'Name', value: 'type'},
+                        selectionSet: {
+                          kind: 'SelectionSet',
+                          selections: [
+                            {kind: 'Field', name: {kind: 'Name', value: 'category'}},
+                            {kind: 'Field', name: {kind: 'Name', value: 'name'}},
+                            {kind: 'Field', name: {kind: 'Name', value: '__typename'}},
+                          ],
+                        },
+                      },
+                      {kind: 'Field', name: {kind: 'Name', value: '__typename'}},
+                    ],
+                  },
+                },
+                {kind: 'Field', name: {kind: 'Name', value: '__typename'}},
+              ],
+            },
+          },
+        ],
+      },
+    },
+  ],
+} as unknown as DocumentNode<MetafieldDefinitionsByOwnerTypeQuery, MetafieldDefinitionsByOwnerTypeQueryVariables>

packages/cli-kit/src/cli/api/graphql/admin/generated/types.d.ts

@@ -120,6 +120,67 @@ export type Scalars = {
   UtcOffset: {input: any; output: any}
 }
 
+/** Possible types of a metafield's owner resource. */
+export type MetafieldOwnerType =
+  /** The Api Permission metafield owner type. */
+  | 'API_PERMISSION'
+  /** The Article metafield owner type. */
+  | 'ARTICLE'
+  /** The Blog metafield owner type. */
+  | 'BLOG'
+  /** The Brand metafield owner type. */
+  | 'BRAND'
+  /** The Cart Transform metafield owner type. */
+  | 'CARTTRANSFORM'
+  /** The Collection metafield owner type. */
+  | 'COLLECTION'
+  /** The Company metafield owner type. */
+  | 'COMPANY'
+  /** The Company Location metafield owner type. */
+  | 'COMPANY_LOCATION'
+  /** The Customer metafield owner type. */
+  | 'CUSTOMER'
+  /** The Delivery Customization metafield owner type. */
+  | 'DELIVERY_CUSTOMIZATION'
+  /** The Delivery Method metafield owner type. */
+  | 'DELIVERY_METHOD'
+  /** The Delivery Option Generator metafield owner type. */
+  | 'DELIVERY_OPTION_GENERATOR'
+  /** The Discount metafield owner type. */
+  | 'DISCOUNT'
+  /** The draft order metafield owner type. */
+  | 'DRAFTORDER'
+  /** The Fulfillment Constraint Rule metafield owner type. */
+  | 'FULFILLMENT_CONSTRAINT_RULE'
+  /** The Gate Configuration metafield owner type. */
+  | 'GATE_CONFIGURATION'
+  /** The GiftCardTransaction metafield owner type. */
+  | 'GIFT_CARD_TRANSACTION'
+  /** The Location metafield owner type. */
+  | 'LOCATION'
+  /** The Market metafield owner type. */
+  | 'MARKET'
+  /** The Media Image metafield owner type. */
+  | 'MEDIA_IMAGE'
+  /** The Order metafield owner type. */
+  | 'ORDER'
+  /** The Order Routing Location Rule metafield owner type. */
+  | 'ORDER_ROUTING_LOCATION_RULE'
+  /** The Page metafield owner type. */
+  | 'PAGE'
+  /** The Payment Customization metafield owner type. */
+  | 'PAYMENT_CUSTOMIZATION'
+  /** The Product metafield owner type. */
+  | 'PRODUCT'
+  /** The Product Variant metafield owner type. */
+  | 'PRODUCTVARIANT'
+  /** The Selling Plan metafield owner type. */
+  | 'SELLING_PLAN'
+  /** The Shop metafield owner type. */
+  | 'SHOP'
+  /** The Validation metafield owner type. */
+  | 'VALIDATION'
+
 /** Type of a theme file operation result. */
 export type OnlineStoreThemeFileResultType =
   /** Operation was malformed or invalid. */

packages/cli-kit/src/cli/api/graphql/admin/queries/metafield_definitions_by_owner_type.graphql

@@ -0,0 +1,13 @@
+query metafieldDefinitionsByOwnerType($ownerType: MetafieldOwnerType!) {
+	metafieldDefinitions(ownerType: $ownerType, first: 250) {
+		nodes {
+      name
+      namespace
+      description
+      type {
+        category
+        name
+      }
+		}
+	}
+}

packages/cli-kit/src/public/node/themes/api.ts

@@ -6,6 +6,8 @@ import {ThemeDelete} from '../../../cli/api/graphql/admin/generated/theme_delete
 import {ThemePublish} from '../../../cli/api/graphql/admin/generated/theme_publish.js'
 import {GetThemeFileBodies} from '../../../cli/api/graphql/admin/generated/get_theme_file_bodies.js'
 import {GetThemeFileChecksums} from '../../../cli/api/graphql/admin/generated/get_theme_file_checksums.js'
+import {MetafieldDefinitionsByOwnerType} from '../../../cli/api/graphql/admin/generated/metafield_definitions_by_owner_type.js'
+import {MetafieldOwnerType} from '../../../cli/api/graphql/admin/generated/types.js'
 import {restRequest, RestResponse, adminRequestDoc} from '@shopify/cli-kit/node/api/admin'
 import {AdminSession} from '@shopify/cli-kit/node/session'
 import {AbortError} from '@shopify/cli-kit/node/error'
@@ -209,6 +211,23 @@ export async function themeDelete(id: number, session: AdminSession): Promise<bo
   return true
 }
 
+export async function metafieldDefinitionsByOwnerType(type: MetafieldOwnerType, session: AdminSession) {
+  return adminRequestDoc(MetafieldDefinitionsByOwnerType, session, {
+    ownerType: type,
+  }).then((result) =>
+    // stripping away the __typename field
+    result.metafieldDefinitions.nodes.map((node) => ({
+      name: node.name,
+      namespace: node.namespace,
+      description: node.description,
+      type: {
+        category: node.type.category,
+        name: node.type.name,
+      },
+    })),
+  )
+}
+
 async function request<T>(
   method: string,
   path: string,