From 518710163f58f2ce288e6300eb464f8b95e9d347 Mon Sep 17 00:00:00 2001
From: Gonzalo Riestra <gonzalo.riestra@shopify.com>
Date: Mon, 25 May 2026 14:23:44 +0200
Subject: [PATCH 1/3] Add theme dev reconciliation strategy flag

---
 .../theme-dev-reconciliation-strategy.md      |   5 +
 .../generated/generated_docs_data_v2.json     |  11 +-
 packages/cli/README.md                        |  11 +-
 packages/cli/oclif.manifest.json              |  16 +++
 packages/theme/src/cli/commands/theme/dev.ts  |  10 +-
 packages/theme/src/cli/services/dev.ts        |   9 +-
 .../theme-environment/remote-theme-watcher.ts |   2 +
 .../theme-environment.test.ts                 |   2 +-
 .../theme-environment/theme-environment.ts    |   1 +
 .../theme-reconciliation.test.ts              | 117 ++++++++++++++++++
 .../theme-environment/theme-reconciliation.ts |  80 +++++++++++-
 .../cli/utilities/theme-environment/types.ts  |  10 ++
 12 files changed, 266 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/theme-dev-reconciliation-strategy.md

diff --git a/.changeset/theme-dev-reconciliation-strategy.md b/.changeset/theme-dev-reconciliation-strategy.md
new file mode 100644
index 00000000000..0270d7df179
--- /dev/null
+++ b/.changeset/theme-dev-reconciliation-strategy.md
@@ -0,0 +1,5 @@
+---
+'@shopify/theme': patch
+---
+
+Add a `--reconciliation-strategy` option to `theme dev`.
diff --git a/docs-shopify.dev/generated/generated_docs_data_v2.json b/docs-shopify.dev/generated/generated_docs_data_v2.json
index 0ec90ceec51..e8f2e68c87c 100644
--- a/docs-shopify.dev/generated/generated_docs_data_v2.json
+++ b/docs-shopify.dev/generated/generated_docs_data_v2.json
@@ -5789,6 +5789,15 @@
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_PORT"
         },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/theme-dev.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--reconciliation-strategy <value>",
+          "value": "string",
+          "description": "How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_RECONCILIATION_STRATEGY"
+        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/theme-dev.interface.ts",
           "syntaxKind": "PropertySignature",
@@ -5889,7 +5898,7 @@
           "environmentValue": "SHOPIFY_FLAG_IGNORE"
         }
       ],
-      "value": "export interface themedev {\n  /**\n   * Allow development on a live theme.\n   * @environment SHOPIFY_FLAG_ALLOW_LIVE\n   */\n  '-a, --allow-live'?: ''\n\n  /**\n   * Alias of the Shopify account to use for authentication.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--auth-alias <value>'?: string\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   * Controls the visibility of the error overlay when an theme asset upload fails:\n- silent Prevents the error overlay from appearing.\n- default Displays the error overlay.\n      \n   * @environment SHOPIFY_FLAG_ERROR_OVERLAY\n   */\n  '--error-overlay <value>'?: string\n\n  /**\n   * Set which network interface the web server listens on. The default value is 127.0.0.1.\n   * @environment SHOPIFY_FLAG_HOST\n   */\n  '--host <value>'?: string\n\n  /**\n   * Skip hot reloading any files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_IGNORE\n   */\n  '-x, --ignore <value>'?: string\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   * The live reload mode switches the server behavior when a file is modified:\n- hot-reload Hot reloads local changes to CSS and sections (default)\n- full-page  Always refreshes the entire page\n- off        Deactivate live reload\n   * @environment SHOPIFY_FLAG_LIVE_RELOAD\n   */\n  '--live-reload <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Prevents files from being deleted in the remote theme when a file has been deleted locally. This applies to files that are deleted while the command is running, and files that have been deleted locally before the command is run.\n   * @environment SHOPIFY_FLAG_NODELETE\n   */\n  '-n, --nodelete'?: ''\n\n  /**\n   * The file path or URL. The file path is to a file that you want updated on idle. The URL path is where you want a webhook posted to report on file changes.\n   * @environment SHOPIFY_FLAG_NOTIFY\n   */\n  '--notify <value>'?: string\n\n  /**\n   * Hot reload only files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_ONLY\n   */\n  '-o, --only <value>'?: string\n\n  /**\n   * Automatically launch the theme preview in your default web browser.\n   * @environment SHOPIFY_FLAG_OPEN\n   */\n  '--open'?: ''\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   * Local port to serve theme preview from. Must be between 1 and 65535.\n   * @environment SHOPIFY_FLAG_PORT\n   */\n  '--port <value>'?: string\n\n  /**\n   * Inject the standard events inspector into storefront HTML.\n   * @environment SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR\n   */\n  '--standard-events-inspector'?: ''\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   * The password for storefronts with password protection.\n   * @environment SHOPIFY_FLAG_STORE_PASSWORD\n   */\n  '--store-password <value>'?: string\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   * Synchronize Theme Editor updates in the local theme files.\n   * @environment SHOPIFY_FLAG_THEME_EDITOR_SYNC\n   */\n  '--theme-editor-sync'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+      "value": "export interface themedev {\n  /**\n   * Allow development on a live theme.\n   * @environment SHOPIFY_FLAG_ALLOW_LIVE\n   */\n  '-a, --allow-live'?: ''\n\n  /**\n   * Alias of the Shopify account to use for authentication.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--auth-alias <value>'?: string\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   * Controls the visibility of the error overlay when an theme asset upload fails:\n- silent Prevents the error overlay from appearing.\n- default Displays the error overlay.\n      \n   * @environment SHOPIFY_FLAG_ERROR_OVERLAY\n   */\n  '--error-overlay <value>'?: string\n\n  /**\n   * Set which network interface the web server listens on. The default value is 127.0.0.1.\n   * @environment SHOPIFY_FLAG_HOST\n   */\n  '--host <value>'?: string\n\n  /**\n   * Skip hot reloading any files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_IGNORE\n   */\n  '-x, --ignore <value>'?: string\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   * The live reload mode switches the server behavior when a file is modified:\n- hot-reload Hot reloads local changes to CSS and sections (default)\n- full-page  Always refreshes the entire page\n- off        Deactivate live reload\n   * @environment SHOPIFY_FLAG_LIVE_RELOAD\n   */\n  '--live-reload <value>'?: string\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Prevents files from being deleted in the remote theme when a file has been deleted locally. This applies to files that are deleted while the command is running, and files that have been deleted locally before the command is run.\n   * @environment SHOPIFY_FLAG_NODELETE\n   */\n  '-n, --nodelete'?: ''\n\n  /**\n   * The file path or URL. The file path is to a file that you want updated on idle. The URL path is where you want a webhook posted to report on file changes.\n   * @environment SHOPIFY_FLAG_NOTIFY\n   */\n  '--notify <value>'?: string\n\n  /**\n   * Hot reload only files that match the specified pattern.\n   * @environment SHOPIFY_FLAG_ONLY\n   */\n  '-o, --only <value>'?: string\n\n  /**\n   * Automatically launch the theme preview in your default web browser.\n   * @environment SHOPIFY_FLAG_OPEN\n   */\n  '--open'?: ''\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   * Local port to serve theme preview from. Must be between 1 and 65535.\n   * @environment SHOPIFY_FLAG_PORT\n   */\n  '--port <value>'?: string\n\n  /**\n   * How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.\n   * @environment SHOPIFY_FLAG_RECONCILIATION_STRATEGY\n   */\n  '--reconciliation-strategy <value>'?: string\n\n  /**\n   * Inject the standard events inspector into storefront HTML.\n   * @environment SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR\n   */\n  '--standard-events-inspector'?: ''\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   * The password for storefronts with password protection.\n   * @environment SHOPIFY_FLAG_STORE_PASSWORD\n   */\n  '--store-password <value>'?: string\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   * Synchronize Theme Editor updates in the local theme files.\n   * @environment SHOPIFY_FLAG_THEME_EDITOR_SYNC\n   */\n  '--theme-editor-sync'?: ''\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
     }
   },
   "themeduplicate": {
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 764f6563de0..0ac9c268133 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -4103,8 +4103,9 @@ Uploads the current theme as a development theme to the connected store, then pr
 USAGE
   $ shopify theme dev [-a] [--auth-alias <value>] [-e <value>...] [--error-overlay silent|default] [--host
     <value>] [-x <value>...] [--listing <value>] [--live-reload hot-reload|full-page|off] [--no-color] [-n] [--notify
-    <value>] [-o <value>...] [--open] [--password <value>] [--path <value>] [--port <value>]
-    [--standard-events-inspector] [-s <value>] [--store-password <value>] [-t <value>] [--theme-editor-sync] [--verbose]
+    <value>] [-o <value>...] [--open] [--password <value>] [--path <value>] [--port <value>] [--reconciliation-strategy
+    keep-local|keep-remote|abort --theme-editor-sync] [--standard-events-inspector] [-s <value>] [--store-password
+    <value>] [-t <value>] [--verbose]
 
 FLAGS
   -a, --allow-live
@@ -4190,6 +4191,12 @@ FLAGS
       Local port to serve theme preview from. Must be between 1 and 65535.
       [env: SHOPIFY_FLAG_PORT]
 
+  --reconciliation-strategy=<option>
+      How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote
+      to keep remote files, or abort to fail instead of prompting.
+      [env: SHOPIFY_FLAG_RECONCILIATION_STRATEGY]
+      <options: keep-local|keep-remote|abort>
+
   --standard-events-inspector
       Inject the standard events inspector into storefront HTML.
       [env: SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR]
diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json
index 2c18645f3af..a63653fc9f0 100644
--- a/packages/cli/oclif.manifest.json
+++ b/packages/cli/oclif.manifest.json
@@ -7765,6 +7765,22 @@
           "name": "port",
           "type": "option"
         },
+        "reconciliation-strategy": {
+          "dependsOn": [
+            "theme-editor-sync"
+          ],
+          "description": "How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.",
+          "env": "SHOPIFY_FLAG_RECONCILIATION_STRATEGY",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "reconciliation-strategy",
+          "options": [
+            "keep-local",
+            "keep-remote",
+            "abort"
+          ],
+          "type": "option"
+        },
         "standard-events-inspector": {
           "allowNo": false,
           "description": "Inject the standard events inspector into storefront HTML.",
diff --git a/packages/theme/src/cli/commands/theme/dev.ts b/packages/theme/src/cli/commands/theme/dev.ts
index 35a4df24359..88979191f54 100644
--- a/packages/theme/src/cli/commands/theme/dev.ts
+++ b/packages/theme/src/cli/commands/theme/dev.ts
@@ -12,7 +12,7 @@ import {recordEvent} from '@shopify/cli-kit/node/analytics'
 import {AdminSession} from '@shopify/cli-kit/node/session'
 import {InferredFlags} from '@oclif/core/interfaces'
 
-import type {ErrorOverlayMode, LiveReload} from '../../utilities/theme-environment/types.js'
+import type {ErrorOverlayMode, LiveReload, ReconciliationStrategy} from '../../utilities/theme-environment/types.js'
 
 type DevFlags = InferredFlags<typeof Dev.flags>
 
@@ -82,6 +82,13 @@ You can run this command only in a directory that matches the [default Shopify t
       env: 'SHOPIFY_FLAG_STANDARD_EVENTS_INSPECTOR',
       default: false,
     }),
+    'reconciliation-strategy': Flags.string({
+      description:
+        'How to resolve JSON conflicts when --theme-editor-sync is enabled. Use keep-local to keep local files, keep-remote to keep remote files, or abort to fail instead of prompting.',
+      options: ['keep-local', 'keep-remote', 'abort'],
+      env: 'SHOPIFY_FLAG_RECONCILIATION_STRATEGY',
+      dependsOn: ['theme-editor-sync'],
+    }),
     port: portFlag({
       description: 'Local port to serve theme preview from.',
       env: 'SHOPIFY_FLAG_PORT',
@@ -186,6 +193,7 @@ You can run this command only in a directory that matches the [default Shopify t
       open: flags.open,
       'theme-editor-sync': flags['theme-editor-sync'],
       'standard-events-inspector': flags['standard-events-inspector'],
+      reconciliationStrategy: flags['reconciliation-strategy'] as ReconciliationStrategy | undefined,
       noDelete: flags.nodelete,
       ignore,
       only,
diff --git a/packages/theme/src/cli/services/dev.ts b/packages/theme/src/cli/services/dev.ts
index 5c657aaabbe..17c560f6876 100644
--- a/packages/theme/src/cli/services/dev.ts
+++ b/packages/theme/src/cli/services/dev.ts
@@ -1,7 +1,12 @@
 import {hasRequiredThemeDirectories, mountThemeFileSystem} from '../utilities/theme-fs.js'
 import {ensureDirectoryConfirmed} from '../utilities/theme-ui.js'
 import {setupDevServer} from '../utilities/theme-environment/theme-environment.js'
-import {type DevServerContext, type ErrorOverlayMode, type LiveReload} from '../utilities/theme-environment/types.js'
+import {
+  type DevServerContext,
+  type ErrorOverlayMode,
+  type LiveReload,
+  type ReconciliationStrategy,
+} from '../utilities/theme-environment/types.js'
 import {isStorefrontPasswordProtected} from '../utilities/theme-environment/storefront-session.js'
 import {ensureValidPassword} from '../utilities/theme-environment/storefront-password-prompt.js'
 import {emptyThemeExtFileSystem} from '../utilities/theme-fs-empty.js'
@@ -42,6 +47,7 @@ interface DevOptions {
   force: boolean
   'standard-events-inspector': boolean
   'theme-editor-sync': boolean
+  reconciliationStrategy?: ReconciliationStrategy
   'live-reload': LiveReload
   'error-overlay': ErrorOverlayMode
   noDelete: boolean
@@ -134,6 +140,7 @@ export async function dev(options: DevOptions) {
     lastRequestedPath: '',
     options: {
       themeEditorSync: options['theme-editor-sync'],
+      reconciliationStrategy: options.reconciliationStrategy,
       host,
       port,
       open: options.open,
diff --git a/packages/theme/src/cli/utilities/theme-environment/remote-theme-watcher.ts b/packages/theme/src/cli/utilities/theme-environment/remote-theme-watcher.ts
index 7c300586ee3..780534e0e42 100644
--- a/packages/theme/src/cli/utilities/theme-environment/remote-theme-watcher.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/remote-theme-watcher.ts
@@ -4,6 +4,7 @@ import {outputDebug} from '@shopify/cli-kit/node/output'
 import {AdminSession} from '@shopify/cli-kit/node/session'
 import {Checksum, Theme, ThemeFileSystem} from '@shopify/cli-kit/node/themes/types'
 import {fetchChecksums} from '@shopify/cli-kit/node/themes/api'
+import type {ReconciliationStrategy} from './types.js'
 
 export const LOCAL_STRATEGY = 'local'
 export const REMOTE_STRATEGY = 'remote'
@@ -21,6 +22,7 @@ export async function reconcileAndPollThemeEditorChanges(
     noDelete: boolean
     ignore: string[]
     only: string[]
+    reconciliationStrategy?: ReconciliationStrategy
   },
   rejectBackgroundJob: (reason?: unknown) => void,
 ): Promise<{
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts b/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts
index ee1df677679..3dfc4088617 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-environment.test.ts
@@ -215,7 +215,7 @@ describe('setupDevServer', () => {
       context.session,
       [],
       context.localThemeFileSystem,
-      {noDelete: true, ...filters},
+      {noDelete: true, ...filters, reconciliationStrategy: undefined},
       expect.anything(),
     )
     // This is the best way I could think of verifying the rejectBackgroundJob
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts b/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts
index 5e9e37ac15e..e08ae6b615e 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-environment.ts
@@ -114,6 +114,7 @@ function handleThemeEditorSync(
         noDelete: ctx.options.noDelete,
         ignore: ctx.options.ignore,
         only: ctx.options.only,
+        reconciliationStrategy: ctx.options.reconciliationStrategy,
       },
       rejectBackgroundJob,
     )
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
index 3a885a2abdd..a08ad934bce 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
@@ -104,6 +104,26 @@ describe('reconcileJsonFiles', () => {
   })
 
   describe('files only present on remote developer theme', () => {
+    test('should download assets from remote theme without prompting when keep-remote strategy is selected', async () => {
+      // Given
+      const assetToBeDownloaded = {checksum: '2', key: 'templates/second_asset.json', value: 'content'}
+      vi.mocked(fetchThemeAssets).mockResolvedValue([assetToBeDownloaded])
+
+      // When
+      await reconcileAndWaitForReconciliationFinish(
+        developmentTheme,
+        adminSession,
+        [assetToBeDownloaded],
+        defaultThemeFileSystem,
+        {...defaultOptions, reconciliationStrategy: 'keep-remote'},
+      )
+
+      // Then
+      expect(renderSelectPrompt).not.toHaveBeenCalled()
+      expect(fetchThemeAssets).toHaveBeenCalledWith(developmentTheme.id, [assetToBeDownloaded.key], adminSession)
+      expect(defaultThemeFileSystem.files.get('templates/second_asset.json')).toEqual(assetToBeDownloaded)
+    })
+
     test('should download assets from remote theme when `remote` source is selected', async () => {
       // Given
       vi.mocked(renderSelectPrompt).mockResolvedValue(REMOTE_STRATEGY)
@@ -146,6 +166,24 @@ describe('reconcileJsonFiles', () => {
       expect(deleteThemeAssets).toHaveBeenCalledWith(developmentTheme.id, [assetToBeDeleted.key], adminSession)
       expect(defaultThemeFileSystem.files.get('templates/asset.json')).toBeUndefined()
     })
+
+    test('should delete assets from remote theme without prompting when keep-local strategy is selected', async () => {
+      // Given
+      const assetToBeDeleted = {checksum: '2', key: 'templates/asset.json'}
+
+      // When
+      await reconcileAndWaitForReconciliationFinish(
+        developmentTheme,
+        adminSession,
+        [assetToBeDeleted],
+        defaultThemeFileSystem,
+        {...defaultOptions, reconciliationStrategy: 'keep-local'},
+      )
+
+      // Then
+      expect(renderSelectPrompt).not.toHaveBeenCalled()
+      expect(deleteThemeAssets).toHaveBeenCalledWith(developmentTheme.id, [assetToBeDeleted.key], adminSession)
+    })
   })
 
   describe('files only present on local developer theme', () => {
@@ -171,6 +209,27 @@ describe('reconcileJsonFiles', () => {
       expect(spy).toHaveBeenCalledWith('templates/asset.json')
     })
 
+    test('should delete files from local disk without prompting when keep-remote strategy is selected', async () => {
+      // Given
+      vi.mocked(fetchThemeAssets).mockResolvedValue([])
+      const files = new Map([['templates/asset.json', {checksum: '1', key: 'templates/asset.json'}]])
+      const localThemeFileSystem = fakeThemeFileSystem('tmp', files)
+      const spy = vi.spyOn(localThemeFileSystem, 'delete')
+
+      // When
+      await reconcileAndWaitForReconciliationFinish(
+        developmentTheme,
+        adminSession,
+        remoteChecksums,
+        localThemeFileSystem,
+        {...defaultOptions, reconciliationStrategy: 'keep-remote'},
+      )
+
+      // Then
+      expect(renderSelectPrompt).not.toHaveBeenCalled()
+      expect(spy).toHaveBeenCalledWith('templates/asset.json')
+    })
+
     test('should not delete files from local disk when `local` source is selected', async () => {
       // Given
       vi.mocked(renderSelectPrompt).mockResolvedValue(LOCAL_STRATEGY)
@@ -220,6 +279,64 @@ describe('reconcileJsonFiles', () => {
   })
 
   describe('files with conflicting checksums', () => {
+    test('should keep local files without prompting when keep-local strategy is selected', async () => {
+      // Given
+      const files = new Map([['templates/asset.json', {checksum: '1', key: 'templates/asset.json'}]])
+      const localThemeFileSystem = fakeThemeFileSystem('tmp', files)
+      const remoteChecksums = [{checksum: '2', key: 'templates/asset.json'}]
+
+      // When
+      await reconcileAndWaitForReconciliationFinish(
+        developmentTheme,
+        adminSession,
+        remoteChecksums,
+        localThemeFileSystem,
+        {...defaultOptions, reconciliationStrategy: 'keep-local'},
+      )
+
+      // Then
+      expect(renderSelectPrompt).not.toHaveBeenCalled()
+      expect(fetchThemeAssets).not.toHaveBeenCalled()
+    })
+
+    test('should abort without prompting when abort strategy is selected', async () => {
+      // Given
+      const files = new Map([
+        ['templates/local_only.json', {checksum: '1', key: 'templates/local_only.json'}],
+        ['templates/conflict.json', {checksum: '1', key: 'templates/conflict.json'}],
+      ])
+      const localThemeFileSystem = fakeThemeFileSystem('tmp', files)
+      const remoteChecksums = [
+        {checksum: '2', key: 'templates/conflict.json'},
+        {checksum: '3', key: 'templates/remote_only.json'},
+      ]
+
+      // When
+      const result = reconcileAndWaitForReconciliationFinish(
+        developmentTheme,
+        adminSession,
+        remoteChecksums,
+        localThemeFileSystem,
+        {...defaultOptions, reconciliationStrategy: 'abort'},
+      )
+
+      // Then
+      let error: (Error & {tryMessage?: string}) | undefined
+      try {
+        await result
+        throw new Error('Expected reconciliation to abort')
+      } catch (caughtError) {
+        error = caughtError as Error & {tryMessage?: string}
+      }
+
+      expect(error).toBeDefined()
+      expect(error!.message).toEqual('Theme JSON files need reconciliation.')
+      expect(error!.tryMessage).toContain('templates/local_only.json')
+      expect(error!.tryMessage).toContain('templates/remote_only.json')
+      expect(error!.tryMessage).toContain('templates/conflict.json')
+      expect(renderSelectPrompt).not.toHaveBeenCalled()
+    })
+
     test('should download files from remote theme when `remote` source is selected', async () => {
       // Given
       vi.mocked(renderSelectPrompt).mockResolvedValue(REMOTE_STRATEGY)
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
index d678aa06526..3bb6648bcd3 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
@@ -7,8 +7,10 @@ import {deleteThemeAssets, fetchThemeAssets} from '@shopify/cli-kit/node/themes/
 import {Checksum, ThemeFileSystem, ThemeAsset, Theme} from '@shopify/cli-kit/node/themes/types'
 import {renderInfo, renderSelectPrompt} from '@shopify/cli-kit/node/ui'
 import {recordEvent} from '@shopify/cli-kit/node/analytics'
+import {AbortError} from '@shopify/cli-kit/node/error'
+import type {ReconciliationStrategy} from './types.js'
 
-type ReconciliationStrategy = typeof LOCAL_STRATEGY | typeof REMOTE_STRATEGY | undefined
+type PromptReconciliationStrategy = typeof LOCAL_STRATEGY | typeof REMOTE_STRATEGY | undefined
 
 interface FilePartitions {
   localFilesToDelete: Checksum[]
@@ -20,6 +22,7 @@ interface ReconciliationOptions {
   noDelete: boolean
   only: string[]
   ignore: string[]
+  reconciliationStrategy?: ReconciliationStrategy
 }
 
 const noWorkPromise = {
@@ -129,11 +132,17 @@ async function promptFileReconciliationStrategy(
       callback: (files: Checksum[]) => void
     }
   },
-): Promise<ReconciliationStrategy | undefined> {
+  strategy?: ReconciliationStrategy,
+): Promise<PromptReconciliationStrategy> {
   if (files.length === 0) {
     return
   }
 
+  if (strategy) {
+    applyReconciliationStrategy(files, options, strategy)
+    return
+  }
+
   renderInfo({
     body: {
       list: {
@@ -158,6 +167,57 @@ async function promptFileReconciliationStrategy(
   }
 }
 
+function applyReconciliationStrategy(
+  files: Checksum[],
+  options: {
+    remote: {
+      callback: (files: Checksum[]) => void
+    }
+    local: {
+      callback: (files: Checksum[]) => void
+    }
+  },
+  strategy: ReconciliationStrategy,
+) {
+  switch (strategy) {
+    case 'keep-remote':
+      options.remote.callback(files)
+      break
+    case 'keep-local':
+      options.local.callback(files)
+      break
+  }
+}
+
+function abortReconciliation(files: {
+  filesOnlyPresentLocally: Checksum[]
+  filesOnlyPresentOnRemote: Checksum[]
+  filesWithConflictingChecksums: Checksum[]
+}) {
+  const reconciliationSections = [
+    {
+      title: 'The files listed below are only present locally.',
+      files: files.filesOnlyPresentLocally,
+    },
+    {
+      title: 'The files listed below are only present on the remote theme.',
+      files: files.filesOnlyPresentOnRemote,
+    },
+    {
+      title: 'The files listed below differ between the local and remote versions.',
+      files: files.filesWithConflictingChecksums,
+    },
+  ]
+
+  throw new AbortError(
+    'Theme JSON files need reconciliation.',
+    reconciliationSections
+      .filter((section) => section.files.length > 0)
+      .map((section) => `${section.title}\n${section.files.map((file) => `- ${file.key}`).join('\n')}`)
+      .join('\n\n'),
+  )
+}
+
 async function performFileReconciliation(
   targetTheme: Theme,
   session: AdminSession,
@@ -201,11 +261,24 @@ async function partitionFilesByReconciliationStrategy(
   options: ReconciliationOptions,
 ): Promise<FilePartitions> {
   const {filesOnlyPresentLocally, filesOnlyPresentOnRemote, filesWithConflictingChecksums} = files
+  const {reconciliationStrategy} = options
 
   const localFilesToDelete: Checksum[] = []
   const filesToDownload: Checksum[] = []
   const remoteFilesToDelete: Checksum[] = []
 
+  const reconciliationFiles = {
+    filesOnlyPresentLocally: options.noDelete ? [] : filesOnlyPresentLocally,
+    filesOnlyPresentOnRemote,
+    filesWithConflictingChecksums,
+  }
+
+  const hasFilesToReconcile = Object.values(reconciliationFiles).some((files) => files.length > 0)
+
+  if (reconciliationStrategy === 'abort' && hasFilesToReconcile) {
+    abortReconciliation(reconciliationFiles)
+  }
+
   if (!options.noDelete) {
     await promptFileReconciliationStrategy(
       filesOnlyPresentLocally,
@@ -222,6 +295,7 @@ async function partitionFilesByReconciliationStrategy(
           callback: () => {},
         },
       },
+      reconciliationStrategy,
     )
   }
 
@@ -242,6 +316,7 @@ async function partitionFilesByReconciliationStrategy(
         },
       },
     },
+    reconciliationStrategy,
   )
 
   await promptFileReconciliationStrategy(
@@ -259,6 +334,7 @@ async function partitionFilesByReconciliationStrategy(
         callback: () => {},
       },
     },
+    reconciliationStrategy,
   )
 
   return {localFilesToDelete, filesToDownload, remoteFilesToDelete}
diff --git a/packages/theme/src/cli/utilities/theme-environment/types.ts b/packages/theme/src/cli/utilities/theme-environment/types.ts
index 6a58821a6ac..3ba820d1a24 100644
--- a/packages/theme/src/cli/utilities/theme-environment/types.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/types.ts
@@ -64,6 +64,11 @@ export type LiveReload = 'hot-reload' | 'full-page' | 'off'
  */
 export type ErrorOverlayMode = 'silent' | 'default'
 
+/**
+ * Controls how theme editor JSON conflicts are resolved without prompting.
+ */
+export type ReconciliationStrategy = 'keep-local' | 'keep-remote' | 'abort'
+
 /**
  * Maintains the state of local and remote assets in theme development server.
  */
@@ -123,6 +128,11 @@ export interface DevServerContext {
      */
     only: string[]
 
+    /**
+     * Strategy to apply when JSON files need reconciliation.
+     */
+    reconciliationStrategy?: ReconciliationStrategy
+
     /**
      * Network interface to bind the development server to.
      */

From 2054117c0f567c2f079f14780d3dfea90ec8a08e Mon Sep 17 00:00:00 2001
From: Gonzalo Riestra <gonzalo.riestra@shopify.com>
Date: Thu, 9 Jul 2026 16:20:10 +0200
Subject: [PATCH 2/3] Fix reconciliation strategy review feedback

---
 .../theme-reconciliation.test.ts              | 23 ++++++++-----------
 .../theme-environment/theme-reconciliation.ts |  6 ++++-
 2 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
index a08ad934bce..889dee8b15a 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.test.ts
@@ -297,6 +297,7 @@ describe('reconcileJsonFiles', () => {
       // Then
       expect(renderSelectPrompt).not.toHaveBeenCalled()
       expect(fetchThemeAssets).not.toHaveBeenCalled()
+      expect(deleteThemeAssets).toHaveBeenCalledWith(developmentTheme.id, [remoteChecksums[0]!.key], adminSession)
     })
 
     test('should abort without prompting when abort strategy is selected', async () => {
@@ -321,19 +322,12 @@ describe('reconcileJsonFiles', () => {
       )
 
       // Then
-      let error: (Error & {tryMessage?: string}) | undefined
-      try {
-        await result
-        throw new Error('Expected reconciliation to abort')
-      } catch (caughtError) {
-        error = caughtError as Error & {tryMessage?: string}
-      }
-
-      expect(error).toBeDefined()
-      expect(error!.message).toEqual('Theme JSON files need reconciliation.')
-      expect(error!.tryMessage).toContain('templates/local_only.json')
-      expect(error!.tryMessage).toContain('templates/remote_only.json')
-      expect(error!.tryMessage).toContain('templates/conflict.json')
+      await expect(result).rejects.toMatchObject({
+        message: 'Theme JSON files need reconciliation.',
+        tryMessage: expect.stringMatching(
+          /templates\/local_only\.json[\s\S]*templates\/remote_only\.json[\s\S]*templates\/conflict\.json/,
+        ),
+      })
       expect(renderSelectPrompt).not.toHaveBeenCalled()
     })
 
@@ -359,7 +353,7 @@ describe('reconcileJsonFiles', () => {
       expect(fetchThemeAssets).toHaveBeenCalled()
     })
 
-    test('should not download files from remote when `local` source is selected', async () => {
+    test('should delete files from remote when `local` source is selected', async () => {
       // Given
       vi.mocked(renderSelectPrompt).mockResolvedValue(LOCAL_STRATEGY)
       const files = new Map([['templates/asset.json', {checksum: '1', key: 'templates/asset.json'}]])
@@ -377,6 +371,7 @@ describe('reconcileJsonFiles', () => {
 
       // Then
       expect(fetchThemeAssets).not.toHaveBeenCalled()
+      expect(deleteThemeAssets).toHaveBeenCalledWith(developmentTheme.id, [remoteChecksums[0]!.key], adminSession)
     })
   })
 
diff --git a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
index 3bb6648bcd3..1ffbd903efc 100644
--- a/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
+++ b/packages/theme/src/cli/utilities/theme-environment/theme-reconciliation.ts
@@ -186,6 +186,8 @@ function applyReconciliationStrategy(
     case 'keep-local':
       options.local.callback(files)
       break
+    case 'abort':
+      break
   }
 }
 
@@ -331,7 +333,9 @@ async function partitionFilesByReconciliationStrategy(
       },
       local: {
         label: 'Keep the local version',
-        callback: () => {},
+        callback: (files) => {
+          remoteFilesToDelete.push(...files)
+        },
       },
     },
     reconciliationStrategy,

From 20c6377cbe742346c015cac70af9e10cc72f4d6a Mon Sep 17 00:00:00 2001
From: Gonzalo Riestra <gonzalo.riestra@shopify.com>
Date: Thu, 9 Jul 2026 16:22:29 +0200
Subject: [PATCH 3/3] Update theme reconciliation changeset to minor

---
 .changeset/theme-dev-reconciliation-strategy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/theme-dev-reconciliation-strategy.md b/.changeset/theme-dev-reconciliation-strategy.md
index 0270d7df179..64878072a71 100644
--- a/.changeset/theme-dev-reconciliation-strategy.md
+++ b/.changeset/theme-dev-reconciliation-strategy.md
@@ -1,5 +1,5 @@
 ---
-'@shopify/theme': patch
+'@shopify/theme': minor
 ---
 
 Add a `--reconciliation-strategy` option to `theme dev`.