introduce --version flag to bulk operations CLI

Author: jordanverasamy

packages/app/src/cli/commands/app/bulk/execute.ts

@@ -52,6 +52,7 @@ export default class BulkExecute extends AppLinkedCommand {
       variableFile: flags['variable-file'],
       watch: flags.watch,
       outputFile: flags['output-file'],
+      ...(flags.version && {version: flags.version}),
     })
 
     return {app: appContextResult.app}

packages/app/src/cli/flags.ts

@@ -72,4 +72,8 @@ export const bulkOperationFlags = {
     description: 'The file path where results should be written. If not specified, results will be written to STDOUT.',
     env: 'SHOPIFY_FLAG_OUTPUT_FILE',
   }),
+  version: Flags.string({
+    description: 'The API version to use for the bulk operation. If not specified, uses the latest stable version.',
+    env: 'SHOPIFY_FLAG_VERSION',
+  }),
 }

packages/app/src/cli/services/bulk-operations/execute-bulk-operation.test.ts

@@ -26,6 +26,13 @@ vi.mock('@shopify/cli-kit/node/session', async () => {
     ensureAuthenticatedAdminAsApp: vi.fn(),
   }
 })
+vi.mock('@shopify/cli-kit/node/api/admin', async () => {
+  const actual = await vi.importActual('@shopify/cli-kit/node/api/admin')
+  return {
+    ...actual,
+    supportedApiVersions: vi.fn(() => Promise.resolve(['2025-01', '2025-04', '2025-07', '2025-10'])),
+  }
+})
 
 describe('executeBulkOperation', () => {
   const mockRemoteApp = {
@@ -482,4 +489,63 @@ describe('executeBulkOperation', () => {
 
     expect(renderSuccess).not.toHaveBeenCalled()
   })
+
+  test('allows executing bulk operations against unstable', async () => {
+    const query = '{ products { edges { node { id } } } }'
+    const mockResponse: BulkOperationRunQueryMutation['bulkOperationRunQuery'] = {
+      bulkOperation: createdBulkOperation,
+      userErrors: [],
+    }
+    vi.mocked(runBulkOperationQuery).mockResolvedValue(mockResponse)
+
+    await executeBulkOperation({
+      remoteApp: mockRemoteApp,
+      storeFqdn,
+      query,
+      version: 'unstable',
+    })
+
+    expect(runBulkOperationQuery).toHaveBeenCalledWith({
+      adminSession: mockAdminSession,
+      query,
+      version: 'unstable',
+    })
+  })
+
+  test('allows executing bulk operations against a specific stable version', async () => {
+    const query = '{ products { edges { node { id } } } }'
+    const mockResponse: BulkOperationRunQueryMutation['bulkOperationRunQuery'] = {
+      bulkOperation: createdBulkOperation,
+      userErrors: [],
+    }
+    vi.mocked(runBulkOperationQuery).mockResolvedValue(mockResponse)
+
+    await executeBulkOperation({
+      remoteApp: mockRemoteApp,
+      storeFqdn,
+      query,
+      version: '2025-01',
+    })
+
+    expect(runBulkOperationQuery).toHaveBeenCalledWith({
+      adminSession: mockAdminSession,
+      query,
+      version: '2025-01',
+    })
+  })
+
+  test('throws error when an API version is specified but is not supported', async () => {
+    const query = '{ products { edges { node { id } } } }'
+
+    await expect(
+      executeBulkOperation({
+        remoteApp: mockRemoteApp,
+        storeFqdn,
+        query,
+        version: '2099-12',
+      }),
+    ).rejects.toThrow('Invalid API version')
+
+    expect(runBulkOperationQuery).not.toHaveBeenCalled()
+  })
 })

packages/app/src/cli/services/bulk-operations/execute-bulk-operation.ts

@@ -7,6 +7,7 @@ import {OrganizationApp} from '../../models/organization.js'
 import {renderSuccess, renderInfo, renderError, renderWarning} from '@shopify/cli-kit/node/ui'
 import {outputContent, outputToken, outputResult} from '@shopify/cli-kit/node/output'
 import {ensureAuthenticatedAdminAsApp} from '@shopify/cli-kit/node/session'
+import {supportedApiVersions} from '@shopify/cli-kit/node/api/admin'
 import {AbortError, BugError} from '@shopify/cli-kit/node/error'
 import {parse} from 'graphql'
 import {readFile, writeFile, fileExists} from '@shopify/cli-kit/node/fs'
@@ -19,6 +20,7 @@ interface ExecuteBulkOperationInput {
   variableFile?: string
   watch?: boolean
   outputFile?: string
+  version?: string
 }
 
 async function parseVariablesToJsonl(variables?: string[], variableFile?: string): Promise<string | undefined> {
@@ -39,7 +41,7 @@ async function parseVariablesToJsonl(variables?: string[], variableFile?: string
 }
 
 export async function executeBulkOperation(input: ExecuteBulkOperationInput): Promise<void> {
-  const {remoteApp, storeFqdn, query, variables, variableFile, outputFile, watch = false} = input
+  const {remoteApp, storeFqdn, query, variables, variableFile, outputFile, watch = false, version} = input
 
   renderInfo({
     headline: 'Starting bulk operation.',
@@ -51,13 +53,15 @@ export async function executeBulkOperation(input: ExecuteBulkOperationInput): Pr
 
   const adminSession = await ensureAuthenticatedAdminAsApp(storeFqdn, remoteApp.apiKey, appSecret)
 
+  if (version) await validateApiVersion(adminSession, version)
+
   const variablesJsonl = await parseVariablesToJsonl(variables, variableFile)
 
   validateGraphQLDocument(query, variablesJsonl)
 
   const bulkOperationResponse = isMutation(query)
-    ? await runBulkOperationMutation({adminSession, query, variablesJsonl})
-    : await runBulkOperationQuery({adminSession, query})
+    ? await runBulkOperationMutation({adminSession, query, variablesJsonl, version})
+    : await runBulkOperationQuery({adminSession, query, version})
 
   if (bulkOperationResponse?.userErrors?.length) {
     const errorMessages = bulkOperationResponse.userErrors
@@ -152,3 +156,19 @@ function isMutation(graphqlOperation: string): boolean {
   const operation = document.definitions.find((def) => def.kind === 'OperationDefinition')
   return operation?.kind === 'OperationDefinition' && operation.operation === 'mutation'
 }
+
+async function validateApiVersion(adminSession: {token: string; storeFqdn: string}, version: string): Promise<void> {
+  if (version === 'unstable') return
+
+  const supportedVersions = await supportedApiVersions(adminSession)
+  if (supportedVersions.includes(version)) return
+
+  const formattedVersions = supportedVersions
+    .map((supportedVersion) => outputContent`${outputToken.green(supportedVersion)}`.value)
+    .join(', ')
+
+  const firstLine = outputContent`Invalid API version: ${outputToken.errorText(version)}`.value
+  const secondLine = outputContent`Supported versions: ${formattedVersions}`.value
+
+  throw new AbortError(`${firstLine}\n${secondLine}`)
+}

packages/app/src/cli/services/bulk-operations/run-mutation.test.ts

@@ -40,4 +40,17 @@ describe('runBulkOperationMutation', () => {
     expect(bulkOperationResult?.bulkOperation).toEqual(successfulBulkOperation)
     expect(bulkOperationResult?.userErrors).toEqual([])
   })
+
+  test('starts bulk mutation with specific API version when provided', async () => {
+    vi.mocked(adminRequestDoc).mockResolvedValue(mockSuccessResponse)
+
+    await runBulkOperationMutation({
+      adminSession: mockSession,
+      query: 'mutation productUpdate($input: ProductInput!) { productUpdate(input: $input) { product { id } } }',
+      variablesJsonl: '{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}',
+      version: '2025-01',
+    })
+
+    expect(adminRequestDoc).toHaveBeenCalledWith(expect.objectContaining({version: '2025-01'}))
+  })
 })

packages/app/src/cli/services/bulk-operations/run-mutation.ts

@@ -11,12 +11,13 @@ interface BulkOperationRunMutationOptions {
   adminSession: AdminSession
   query: string
   variablesJsonl?: string
+  version?: string
 }
 
 export async function runBulkOperationMutation(
   options: BulkOperationRunMutationOptions,
 ): Promise<BulkOperationRunMutationMutation['bulkOperationRunMutation']> {
-  const {adminSession, query: mutation, variablesJsonl} = options
+  const {adminSession, query: mutation, variablesJsonl, version} = options
 
   const stagedUploadPath = await stageFile({
     adminSession,
@@ -30,6 +31,7 @@ export async function runBulkOperationMutation(
       mutation,
       stagedUploadPath,
     },
+    ...(version && {version}),
   })
 
   return response.bulkOperationRunMutation

packages/app/src/cli/services/bulk-operations/run-query.test.ts

@@ -33,4 +33,16 @@ describe('runBulkOperationQuery', () => {
     expect(bulkOperationResult?.bulkOperation).toEqual(successfulBulkOperation)
     expect(bulkOperationResult?.userErrors).toEqual([])
   })
+
+  test('starts bulk query with specific API version when provided', async () => {
+    vi.mocked(adminRequestDoc).mockResolvedValue(mockSuccessResponse)
+
+    await runBulkOperationQuery({
+      adminSession: mockSession,
+      query: 'query { products { edges { node { id } } } }',
+      version: '2025-01',
+    })
+
+    expect(adminRequestDoc).toHaveBeenCalledWith(expect.objectContaining({version: '2025-01'}))
+  })
 })

packages/app/src/cli/services/bulk-operations/run-query.ts

@@ -8,17 +8,19 @@ import {AdminSession} from '@shopify/cli-kit/node/session'
 interface BulkOperationRunQueryOptions {
   adminSession: AdminSession
   query: string
+  version?: string
 }
 
 export async function runBulkOperationQuery(
   options: BulkOperationRunQueryOptions,
 ): Promise<BulkOperationRunQueryMutation['bulkOperationRunQuery']> {
-  const {adminSession, query} = options
+  const {adminSession, query, version} = options
 
   const response = await adminRequestDoc<BulkOperationRunQueryMutation, {query: string}>({
     query: BulkOperationRunQuery,
     session: adminSession,
     variables: {query},
+    ...(version && {version}),
   })
 
   return response.bulkOperationRunQuery

packages/cli/oclif.manifest.json

@@ -202,6 +202,14 @@
           "name": "verbose",
           "type": "boolean"
         },
+        "version": {
+          "description": "The API version to use for the bulk operation. If not specified, uses the latest stable version.",
+          "env": "SHOPIFY_FLAG_VERSION",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "version",
+          "type": "option"
+        },
         "watch": {
           "allowNo": false,
           "description": "Wait for bulk operation results before exiting.",