Add ability to set theme name on push

graygilmore · graygilmore · commit c24eece76ea7 · 2026-02-02T13:30:01.000-08:00
diff --git a/.changeset/puny-plants-allow.md b/.changeset/puny-plants-allow.md
@@ -0,0 +1,7 @@
+---
+'@shopify/cli-kit': minor
+'@shopify/theme': minor
+'@shopify/cli': minor
+---
+
+Add `--development-context` flag to `theme push`
diff --git a/docs-shopify.dev/commands/interfaces/theme-push.interface.ts b/docs-shopify.dev/commands/interfaces/theme-push.interface.ts
@@ -42,6 +42,12 @@ export interface themepush {
    */
   '-l, --live'?: ''
 
+  /**
+   * The name for the theme. Will always create a new theme.
+   * @environment SHOPIFY_FLAG_NAME
+   */
+  '--name <value>'?: string
+
   /**
    * Disable color output.
    * @environment SHOPIFY_FLAG_NO_COLOR
diff --git a/docs-shopify.dev/generated/generated_docs_data.json b/docs-shopify.dev/generated/generated_docs_data.json
@@ -6884,6 +6884,15 @@
                 "isOptional": true,
                 "environmentValue": "SHOPIFY_FLAG_LISTING"
               },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/theme-push.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--name <value>",
+                "value": "string",
+                "description": "The name for the theme. Will always create a new theme.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_NAME"
+              },
               {
                 "filePath": "docs-shopify.dev/commands/interfaces/theme-push.interface.ts",
                 "syntaxKind": "PropertySignature",
@@ -7038,7 +7047,7 @@
                 "environmentValue": "SHOPIFY_FLAG_IGNORE"
               }
             ],
-            "value": "export interface themepush {\n  /**\n   * Allow push to a live theme.\n   * @environment SHOPIFY_FLAG_ALLOW_LIVE\n   */\n  '-a, --allow-live'?: ''\n\n  /**\n   * Push theme files from your remote development theme.\n   * @environment SHOPIFY_FLAG_DEVELOPMENT\n   */\n  '-d, --development'?: ''\n\n  /**\n   * The environment to apply to the current command.\n   * @environment SHOPIFY_FLAG_ENVIRONMENT\n   */\n  '-e, --environment <value>'?: string\n\n  /**\n   * Skip uploading the specified files (Multiple flags allowed). Wrap the value in double quotes if you're using wildcards.\n   * @environment SHOPIFY_FLAG_IGNORE\n   */\n  '-x, --ignore <value>'?: string\n\n  /**\n   * Output the result as JSON.\n   * @environment SHOPIFY_FLAG_JSON\n   */\n  '-j, --json'?: ''\n\n  /**\n   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.\n   * @environment SHOPIFY_FLAG_LISTING\n   */\n  '--listing <value>'?: string\n\n  /**\n   * Push theme files from your remote live theme.\n   * @environment SHOPIFY_FLAG_LIVE\n   */\n  '-l, --live'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Prevent deleting remote files that don't exist locally.\n   * @environment SHOPIFY_FLAG_NODELETE\n   */\n  '-n, --nodelete'?: ''\n\n  /**\n   * Upload only the specified files (Multiple flags allowed). Wrap the value in double quotes if you're using wildcards.\n   * @environment SHOPIFY_FLAG_ONLY\n   */\n  '-o, --only <value>'?: string\n\n  /**\n   * Password generated from the Theme Access app or an Admin API token.\n   * @environment SHOPIFY_CLI_THEME_TOKEN\n   */\n  '--password <value>'?: string\n\n  /**\n   * The path where you want to run the command. Defaults to the current working directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Publish as the live theme after uploading.\n   * @environment SHOPIFY_FLAG_PUBLISH\n   */\n  '-p, --publish'?: ''\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   * Require theme check to pass without errors before pushing. Warnings are allowed.\n   * @environment SHOPIFY_FLAG_STRICT_PUSH\n   */\n  '--strict'?: ''\n\n  /**\n   * Theme ID or name of the remote theme.\n   * @environment SHOPIFY_FLAG_THEME_ID\n   */\n  '-t, --theme <value>'?: string\n\n  /**\n   * Create a new unpublished theme and push to it.\n   * @environment SHOPIFY_FLAG_UNPUBLISHED\n   */\n  '-u, --unpublished'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+            "value": "export interface themepush {\n  /**\n   * Allow push to a live theme.\n   * @environment SHOPIFY_FLAG_ALLOW_LIVE\n   */\n  '-a, --allow-live'?: ''\n\n  /**\n   * Push theme files from your remote development theme.\n   * @environment SHOPIFY_FLAG_DEVELOPMENT\n   */\n  '-d, --development'?: ''\n\n  /**\n   * The environment to apply to the current command.\n   * @environment SHOPIFY_FLAG_ENVIRONMENT\n   */\n  '-e, --environment <value>'?: string\n\n  /**\n   * Skip uploading the specified files (Multiple flags allowed). Wrap the value in double quotes if you're using wildcards.\n   * @environment SHOPIFY_FLAG_IGNORE\n   */\n  '-x, --ignore <value>'?: string\n\n  /**\n   * Output the result as JSON.\n   * @environment SHOPIFY_FLAG_JSON\n   */\n  '-j, --json'?: ''\n\n  /**\n   * The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.\n   * @environment SHOPIFY_FLAG_LISTING\n   */\n  '--listing <value>'?: string\n\n  /**\n   * Push theme files from your remote live theme.\n   * @environment SHOPIFY_FLAG_LIVE\n   */\n  '-l, --live'?: ''\n\n  /**\n   * The name for the theme. Will always create a new theme.\n   * @environment SHOPIFY_FLAG_NAME\n   */\n  '--name <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Prevent deleting remote files that don't exist locally.\n   * @environment SHOPIFY_FLAG_NODELETE\n   */\n  '-n, --nodelete'?: ''\n\n  /**\n   * Upload only the specified files (Multiple flags allowed). Wrap the value in double quotes if you're using wildcards.\n   * @environment SHOPIFY_FLAG_ONLY\n   */\n  '-o, --only <value>'?: string\n\n  /**\n   * Password generated from the Theme Access app or an Admin API token.\n   * @environment SHOPIFY_CLI_THEME_TOKEN\n   */\n  '--password <value>'?: string\n\n  /**\n   * The path where you want to run the command. Defaults to the current working directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Publish as the live theme after uploading.\n   * @environment SHOPIFY_FLAG_PUBLISH\n   */\n  '-p, --publish'?: ''\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   * Require theme check to pass without errors before pushing. Warnings are allowed.\n   * @environment SHOPIFY_FLAG_STRICT_PUSH\n   */\n  '--strict'?: ''\n\n  /**\n   * Theme ID or name of the remote theme.\n   * @environment SHOPIFY_FLAG_THEME_ID\n   */\n  '-t, --theme <value>'?: string\n\n  /**\n   * Create a new unpublished theme and push to it.\n   * @environment SHOPIFY_FLAG_UNPUBLISHED\n   */\n  '-u, --unpublished'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
           }
         }
       }
diff --git a/packages/cli-kit/src/public/node/themes/theme-manager.test.ts b/packages/cli-kit/src/public/node/themes/theme-manager.test.ts
@@ -92,6 +92,28 @@ describe('ThemeManager', () => {
       expect(result).toEqual(mockTheme)
       expect(manager.getStoredThemeId()).toBe('123')
     })
+
+    test('always creates a new theme when name is provided', async () => {
+      // Given
+      manager.setThemeId('123')
+      const customTheme = {...mockTheme, name: 'Custom name'}
+      vi.mocked(themeCreate).mockResolvedValue(customTheme)
+
+      // When
+      const result = await manager.findOrCreate('Custom name')
+
+      // Then
+      expect(fetchTheme).not.toHaveBeenCalled()
+      expect(themeCreate).toHaveBeenCalledWith(
+        {
+          name: 'Custom name',
+          role: DEVELOPMENT_THEME_ROLE,
+        },
+        session,
+      )
+      expect(result).toEqual(customTheme)
+      expect(manager.getStoredThemeId()).toBe('123')
+    })
   })
 
   describe('fetch', () => {
diff --git a/packages/cli-kit/src/public/node/themes/theme-manager.ts b/packages/cli-kit/src/public/node/themes/theme-manager.ts
@@ -1,4 +1,4 @@
-import {fetchTheme, themeCreate} from './api.js'
+import {fetchTheme, findThemeByName, themeCreate} from './api.js'
 import {Theme} from './types.js'
 import {DEVELOPMENT_THEME_ROLE, Role} from './utils.js'
 import {generateThemeName} from '../../../private/node/themes/generate-theme-name.js'
@@ -13,19 +13,24 @@ export abstract class ThemeManager {
 
   constructor(protected adminSession: AdminSession) {}
 
-  async findOrCreate(): Promise<Theme> {
-    let theme = await this.fetch()
+  async findOrCreate(name?: string): Promise<Theme> {
+    let theme = await this.fetch(name)
     if (!theme) {
-      theme = await this.create()
+      theme = await this.create(DEVELOPMENT_THEME_ROLE, name)
     }
     return theme
   }
 
-  async fetch() {
-    if (!this.themeId) {
+  async fetch(name?: string) {
+    if (!this.themeId && !name) {
       return
     }
-    const theme = await fetchTheme(parseInt(this.themeId, 10), this.adminSession)
+
+    const theme = name
+      ? await findThemeByName(name, this.adminSession)
+      : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        await fetchTheme(parseInt(this.themeId!, 10), this.adminSession)
+
     if (!theme) {
       this.removeTheme()
     }
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -2400,6 +2400,7 @@ FLAGS
                                 quotes if you're using wildcards.
       --listing=<value>         The listing preset to use for multi-preset themes. Applies preset files from
                                 listings/[preset-name] directory.
+      --name=<value>            The name for the theme. Will always create a new theme.
       --no-color                Disable color output.
       --password=<value>        Password generated from the Theme Access app or an Admin API token.
       --path=<value>            The path where you want to run the command. Defaults to the current working directory.
diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json
@@ -7134,6 +7134,17 @@
           "name": "live",
           "type": "boolean"
         },
+        "name": {
+          "description": "The name for the theme. Will always create a new theme.",
+          "env": "SHOPIFY_FLAG_NAME",
+          "exclusive": [
+            "theme"
+          ],
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "name",
+          "type": "option"
+        },
         "no-color": {
           "allowNo": false,
           "description": "Disable color output.",
diff --git a/packages/theme/src/cli/commands/theme/push.ts b/packages/theme/src/cli/commands/theme/push.ts
@@ -102,6 +102,13 @@ export default class Push extends ThemeCommand {
         'The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.',
       env: 'SHOPIFY_FLAG_LISTING',
     }),
+    'development-context': Flags.string({
+      description:
+        'Unique identifier for a development theme context (e.g., PR number, branch name). Reuses an existing development theme with this context name, or creates one if none exists.',
+      env: 'SHOPIFY_FLAG_DEVELOPMENT_CONTEXT',
+      dependsOn: ['development'],
+      exclusive: ['theme'],
+    }),
     environment: themeFlags.environment,
   }
 
diff --git a/packages/theme/src/cli/services/push.test.ts b/packages/theme/src/cli/services/push.test.ts
@@ -292,6 +292,20 @@ describe('createOrSelectTheme', async () => {
     expect(setDevelopmentTheme).toHaveBeenCalled()
   })
 
+  test('creates development theme when development and development-context flags are provided', async () => {
+    // Given
+    vi.mocked(themeCreate).mockResolvedValue(buildTheme({id: 1, name: 'Custom name', role: DEVELOPMENT_THEME_ROLE}))
+    vi.mocked(fetchTheme).mockResolvedValue(undefined)
+    const flags: PushFlags = {development: true, developmentContext: 'Custom name'}
+
+    // When
+    const theme = await createOrSelectTheme(adminSession, flags)
+
+    // Then
+    expect(theme).toMatchObject({role: DEVELOPMENT_THEME_ROLE, name: 'Custom name'})
+    expect(setDevelopmentTheme).toHaveBeenCalled()
+  })
+
   test('creates development theme when development and unpublished flags are provided', async () => {
     // Given
     vi.mocked(themeCreate).mockResolvedValue(buildTheme({id: 1, name: 'Theme', role: DEVELOPMENT_THEME_ROLE}))
diff --git a/packages/theme/src/cli/services/push.ts b/packages/theme/src/cli/services/push.ts
@@ -113,6 +113,9 @@ export interface PushFlags {
 
   /** The listing preset to use for multi-preset themes. */
   listing?: string
+
+  /** Unique identifier for a development theme context. Reuses an existing development theme with this context name, or creates one if none exists. */
+  developmentContext?: string
 }
 
 /**
@@ -379,11 +382,11 @@ export async function createOrSelectTheme(
   flags: PushFlags,
   multiEnvironment?: boolean,
 ): Promise<Theme | undefined> {
-  const {live, development, unpublished, theme, environment} = flags
+  const {live, development, unpublished, theme, environment, developmentContext} = flags
 
   if (development) {
     const themeManager = new DevelopmentThemeManager(session)
-    return themeManager.findOrCreate()
+    return themeManager.findOrCreate(developmentContext)
   } else if (unpublished) {
     const themeName = theme ?? (await promptThemeName('Name of the new theme'))
     return themeCreate(

Original file line number	Diff line number	Diff line change
`@@ -6884,6 +6884,15 @@`
`6884`	`6884`	`"isOptional": true,`
`6885`	`6885`	`"environmentValue": "SHOPIFY_FLAG_LISTING"`
`6886`	`6886`	`},`
	`6887`	`+ {`
	`6888`	`+ "filePath": "docs-shopify.dev/commands/interfaces/theme-push.interface.ts",`
	`6889`	`+ "syntaxKind": "PropertySignature",`
	`6890`	`+ "name": "--name <value>",`
	`6891`	`+ "value": "string",`
	`6892`	`+ "description": "The name for the theme. Will always create a new theme.",`
	`6893`	`+ "isOptional": true,`
	`6894`	`+ "environmentValue": "SHOPIFY_FLAG_NAME"`
	`6895`	`+ },`
`6887`	`6896`	`{`
`6888`	`6897`	`"filePath": "docs-shopify.dev/commands/interfaces/theme-push.interface.ts",`
`6889`	`6898`	`"syntaxKind": "PropertySignature",`
`@@ -7038,7 +7047,7 @@`
`7038`	`7047`	`"environmentValue": "SHOPIFY_FLAG_IGNORE"`
`7039`	`7048`	`}`
`7040`	`7049`	`],`
`7041`		- "value": "export interface themepush {\n /*\n Allow push to a live theme.\n * @environment SHOPIFY_FLAG_ALLOW_LIVE\n /\n '-a, --allow-live'?: ''\n\n /\n Push theme files from your remote development theme.\n * @environment SHOPIFY_FLAG_DEVELOPMENT\n /\n '-d, --development'?: ''\n\n /\n The environment to apply to the current command.\n * @environment SHOPIFY_FLAG_ENVIRONMENT\n /\n '-e, --environment <value>'?: string\n\n /\n Skip uploading the specified files (Multiple flags allowed). Wrap the value in double quotes if you're using wildcards.\n * @environment SHOPIFY_FLAG_IGNORE\n /\n '-x, --ignore <value>'?: string\n\n /\n Output the result as JSON.\n * @environment SHOPIFY_FLAG_JSON\n /\n '-j, --json'?: ''\n\n /\n The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.\n * @environment SHOPIFY_FLAG_LISTING\n /\n '--listing <value>'?: string\n\n /\n Push theme files from your remote live theme.\n * @environment SHOPIFY_FLAG_LIVE\n /\n '-l, --live'?: ''\n\n /\n Disable color output.\n * @environment SHOPIFY_FLAG_NO_COLOR\n /\n '--no-color'?: ''\n\n /\n Prevent deleting remote files that don't exist locally.\n * @environment SHOPIFY_FLAG_NODELETE\n /\n '-n, --nodelete'?: ''\n\n /\n Upload only the specified files (Multiple flags allowed). Wrap the value in double quotes if you're using wildcards.\n * @environment SHOPIFY_FLAG_ONLY\n /\n '-o, --only <value>'?: string\n\n /\n Password generated from the Theme Access app or an Admin API token.\n * @environment SHOPIFY_CLI_THEME_TOKEN\n /\n '--password <value>'?: string\n\n /\n The path where you want to run the command. Defaults to the current working directory.\n * @environment SHOPIFY_FLAG_PATH\n /\n '--path <value>'?: string\n\n /\n Publish as the live theme after uploading.\n * @environment SHOPIFY_FLAG_PUBLISH\n /\n '-p, --publish'?: ''\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 Require theme check to pass without errors before pushing. Warnings are allowed.\n * @environment SHOPIFY_FLAG_STRICT_PUSH\n /\n '--strict'?: ''\n\n /\n Theme ID or name of the remote theme.\n * @environment SHOPIFY_FLAG_THEME_ID\n /\n '-t, --theme <value>'?: string\n\n /\n Create a new unpublished theme and push to it.\n * @environment SHOPIFY_FLAG_UNPUBLISHED\n /\n '-u, --unpublished'?: ''\n\n /\n Increase the verbosity of the output.\n * @environment SHOPIFY_FLAG_VERBOSE\n */\n '--verbose'?: ''\n}"
	`7050`	+ "value": "export interface themepush {\n /*\n Allow push to a live theme.\n * @environment SHOPIFY_FLAG_ALLOW_LIVE\n /\n '-a, --allow-live'?: ''\n\n /\n Push theme files from your remote development theme.\n * @environment SHOPIFY_FLAG_DEVELOPMENT\n /\n '-d, --development'?: ''\n\n /\n The environment to apply to the current command.\n * @environment SHOPIFY_FLAG_ENVIRONMENT\n /\n '-e, --environment <value>'?: string\n\n /\n Skip uploading the specified files (Multiple flags allowed). Wrap the value in double quotes if you're using wildcards.\n * @environment SHOPIFY_FLAG_IGNORE\n /\n '-x, --ignore <value>'?: string\n\n /\n Output the result as JSON.\n * @environment SHOPIFY_FLAG_JSON\n /\n '-j, --json'?: ''\n\n /\n The listing preset to use for multi-preset themes. Applies preset files from listings/[preset-name] directory.\n * @environment SHOPIFY_FLAG_LISTING\n /\n '--listing <value>'?: string\n\n /\n Push theme files from your remote live theme.\n * @environment SHOPIFY_FLAG_LIVE\n /\n '-l, --live'?: ''\n\n /\n The name for the theme. Will always create a new theme.\n * @environment SHOPIFY_FLAG_NAME\n /\n '--name <value>'?: string\n\n /\n Disable color output.\n * @environment SHOPIFY_FLAG_NO_COLOR\n /\n '--no-color'?: ''\n\n /\n Prevent deleting remote files that don't exist locally.\n * @environment SHOPIFY_FLAG_NODELETE\n /\n '-n, --nodelete'?: ''\n\n /\n Upload only the specified files (Multiple flags allowed). Wrap the value in double quotes if you're using wildcards.\n * @environment SHOPIFY_FLAG_ONLY\n /\n '-o, --only <value>'?: string\n\n /\n Password generated from the Theme Access app or an Admin API token.\n * @environment SHOPIFY_CLI_THEME_TOKEN\n /\n '--password <value>'?: string\n\n /\n The path where you want to run the command. Defaults to the current working directory.\n * @environment SHOPIFY_FLAG_PATH\n /\n '--path <value>'?: string\n\n /\n Publish as the live theme after uploading.\n * @environment SHOPIFY_FLAG_PUBLISH\n /\n '-p, --publish'?: ''\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 Require theme check to pass without errors before pushing. Warnings are allowed.\n * @environment SHOPIFY_FLAG_STRICT_PUSH\n /\n '--strict'?: ''\n\n /\n Theme ID or name of the remote theme.\n * @environment SHOPIFY_FLAG_THEME_ID\n /\n '-t, --theme <value>'?: string\n\n /\n Create a new unpublished theme and push to it.\n * @environment SHOPIFY_FLAG_UNPUBLISHED\n /\n '-u, --unpublished'?: ''\n\n /\n Increase the verbosity of the output.\n * @environment SHOPIFY_FLAG_VERBOSE\n */\n '--verbose'?: ''\n}"
`7042`	`7051`	`}`
`7043`	`7052`	`}`
`7044`	`7053`	`}`