feat(store): open GraphiQL when 'shopify store execute' has no query

gonzaloriestra · gonzaloriestra · commit 271d8f9e1b7c · 2026-04-24T09:54:01.000+02:00
When neither --query nor --query-file is provided, 'shopify store execute'
now spins up the GraphiQL HTTP server on a local port (using the
TokenProvider-based server from @shopify/cli-kit/node/graphiql/server),
prints the URL, and opens it in the browser.

- New service: openStoreGraphiQL backs the no-query branch. Token strategy
  delegates to loadStoredStoreSession, so the GraphiQL session uses the
  credentials previously set up by 'shopify store auth' and benefits from
  its expiry/refresh logic.
- New flags: --graphiql-port (env SHOPIFY_FLAG_GRAPHIQL_PORT) chooses the
  port; --no-open (env SHOPIFY_FLAG_NO_OPEN) keeps the browser closed.
- --query and --query-file are now optional and mutually exclusive instead
  of exactlyOne. Existing non-interactive behavior is unchanged.
- --allow-mutations also gates mutations in the interactive UI, mirroring
  the safe-by-default semantics of the non-interactive path. Without it,
  the proxy returns HTTP 400 for any mutation operation.
- --output-file and --json log a warning and are ignored in GraphiQL mode.
- Tests cover the routing, flag forwarding, and the openStoreGraphiQL
  service (server wiring, token provider, browser open, abort/close).
- README + oclif manifest regenerated; changeset added.
diff --git a/.changeset/store-execute-graphiql.md b/.changeset/store-execute-graphiql.md
@@ -0,0 +1,7 @@
+---
+'@shopify/cli-kit': minor
+'@shopify/app': minor
+'@shopify/store': minor
+---
+
+Open an interactive GraphiQL UI when running `shopify store execute` without `--query` or `--query-file`. The GraphiQL session uses the access token previously set up via `shopify store auth`, points at the same Admin GraphQL endpoint as the non-interactive mode, and respects `--allow-mutations` (mutations are blocked by default). The GraphiQL HTTP server has moved into `@shopify/cli-kit/node/graphiql/server` so both `shopify app dev` and `shopify store execute` can reuse it; behavior of `shopify app dev` is unchanged.
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -2141,41 +2141,50 @@ EXAMPLES
 
 ## `shopify store execute`
 
-Execute GraphQL queries and mutations on a store.
+Execute GraphQL queries and mutations on a store, or open an interactive GraphiQL UI.
 
 ```
 USAGE
-  $ shopify store execute -s <value> [--allow-mutations] [-j] [--no-color] [--output-file <value>] [-q <value>]
-    [--query-file <value>] [--variable-file <value> | -v <value>] [--verbose] [--version <value>]
+  $ shopify store execute -s <value> [--allow-mutations] [--graphiql-port <value>] [-j] [--no-color] [--no-open]
+    [--output-file <value>] [-q <value> | --query-file <value>] [--variable-file <value> | -v <value>] [--verbose]
+    [--version <value>]
 
 FLAGS
   -j, --json                   [env: SHOPIFY_FLAG_JSON] Output the result as JSON. Automatically disables color output.
-  -q, --query=<value>          [env: SHOPIFY_FLAG_QUERY] The GraphQL query or mutation, as a string.
+  -q, --query=<value>          [env: SHOPIFY_FLAG_QUERY] The GraphQL query or mutation, as a string. Omit to open
+                               GraphiQL.
   -s, --store=<value>          (required) [env: SHOPIFY_FLAG_STORE] The myshopify.com domain of the store to execute
                                against.
   -v, --variables=<value>      [env: SHOPIFY_FLAG_VARIABLES] The values for any GraphQL variables in your query or
                                mutation, in JSON format.
       --allow-mutations        [env: SHOPIFY_FLAG_ALLOW_MUTATIONS] Allow GraphQL mutations to run against the target
                                store.
+      --graphiql-port=<value>  [env: SHOPIFY_FLAG_GRAPHIQL_PORT] Local port for the GraphiQL server when no --query or
+                               --query-file is provided.
       --no-color               [env: SHOPIFY_FLAG_NO_COLOR] Disable color output.
+      --no-open                [env: SHOPIFY_FLAG_NO_OPEN] Do not open the GraphiQL URL in the browser automatically.
       --output-file=<value>    [env: SHOPIFY_FLAG_OUTPUT_FILE] The file name where results should be written, instead of
                                STDOUT.
       --query-file=<value>     [env: SHOPIFY_FLAG_QUERY_FILE] Path to a file containing the GraphQL query or mutation.
-                               Can't be used with --query.
+                               Can't be used with --query. Omit to open GraphiQL.
       --variable-file=<value>  [env: SHOPIFY_FLAG_VARIABLE_FILE] Path to a file containing GraphQL variables in JSON
                                format. Can't be used with --variables.
       --verbose                [env: SHOPIFY_FLAG_VERBOSE] Increase the verbosity of the output.
       --version=<value>        [env: SHOPIFY_FLAG_VERSION] The API version to use for the query or mutation. Defaults to
                                the latest stable version.
 
 DESCRIPTION
-  Execute GraphQL queries and mutations on a store.
+  Execute GraphQL queries and mutations on a store, or open an interactive GraphiQL UI.
 
   Executes an Admin API GraphQL query or mutation on the specified store using previously stored app authentication.
 
   Run `shopify store auth` first to create stored auth for the store.
 
-  Mutations are disabled by default. Re-run with `--allow-mutations` if you intend to modify store data.
+  When neither `--query` nor `--query-file` is provided, opens a local GraphiQL UI in the browser pointed at the store.
+  Use `--graphiql-port` to choose the port and `--no-open` to keep the browser closed.
+
+  Mutations are disabled by default. Re-run with `--allow-mutations` if you intend to modify store data; the same flag
+  controls whether the GraphiQL UI is allowed to issue mutations.
 
 EXAMPLES
   $ shopify store execute --store shop.myshopify.com --query "query { shop { name } }"
@@ -2185,6 +2194,8 @@ EXAMPLES
   $ shopify store execute --store shop.myshopify.com --query "mutation { shop { id } }" --allow-mutations
 
   $ shopify store execute --store shop.myshopify.com --query "query { shop { name } }" --json
+
+  $ shopify store execute --store shop.myshopify.com
 ```
 
 ## `shopify theme check`
diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json
@@ -5868,13 +5868,14 @@
       "args": {
       },
       "customPluginName": "@shopify/store",
-      "description": "Executes an Admin API GraphQL query or mutation on the specified store using previously stored app authentication.\n\nRun `shopify store auth` first to create stored auth for the store.\n\nMutations are disabled by default. Re-run with `--allow-mutations` if you intend to modify store data.",
-      "descriptionWithMarkdown": "Executes an Admin API GraphQL query or mutation on the specified store using previously stored app authentication.\n\nRun `shopify store auth` first to create stored auth for the store.\n\nMutations are disabled by default. Re-run with `--allow-mutations` if you intend to modify store data.",
+      "description": "Executes an Admin API GraphQL query or mutation on the specified store using previously stored app authentication.\n\nRun `shopify store auth` first to create stored auth for the store.\n\nWhen neither `--query` nor `--query-file` is provided, opens a local GraphiQL UI in the browser pointed at the store. Use `--graphiql-port` to choose the port and `--no-open` to keep the browser closed.\n\nMutations are disabled by default. Re-run with `--allow-mutations` if you intend to modify store data; the same flag controls whether the GraphiQL UI is allowed to issue mutations.",
+      "descriptionWithMarkdown": "Executes an Admin API GraphQL query or mutation on the specified store using previously stored app authentication.\n\nRun `shopify store auth` first to create stored auth for the store.\n\nWhen neither `--query` nor `--query-file` is provided, opens a local GraphiQL UI in the browser pointed at the store. Use `--graphiql-port` to choose the port and `--no-open` to keep the browser closed.\n\nMutations are disabled by default. Re-run with `--allow-mutations` if you intend to modify store data; the same flag controls whether the GraphiQL UI is allowed to issue mutations.",
       "examples": [
         "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --query \"query { shop { name } }\"",
         "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --query-file ./operation.graphql --variables '{\"id\":\"gid://shopify/Product/1\"}'",
         "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --query \"mutation { shop { id } }\" --allow-mutations",
-        "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --query \"query { shop { name } }\" --json"
+        "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --query \"query { shop { name } }\" --json",
+        "<%= config.bin %> <%= command.id %> --store shop.myshopify.com"
       ],
       "flags": {
         "allow-mutations": {
@@ -5884,6 +5885,14 @@
           "name": "allow-mutations",
           "type": "boolean"
         },
+        "graphiql-port": {
+          "description": "Local port for the GraphiQL server when no --query or --query-file is provided.",
+          "env": "SHOPIFY_FLAG_GRAPHIQL_PORT",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "graphiql-port",
+          "type": "option"
+        },
         "json": {
           "allowNo": false,
           "char": "j",
@@ -5901,6 +5910,13 @@
           "name": "no-color",
           "type": "boolean"
         },
+        "no-open": {
+          "allowNo": false,
+          "description": "Do not open the GraphiQL URL in the browser automatically.",
+          "env": "SHOPIFY_FLAG_NO_OPEN",
+          "name": "no-open",
+          "type": "boolean"
+        },
         "output-file": {
           "description": "The file name where results should be written, instead of STDOUT.",
           "env": "SHOPIFY_FLAG_OUTPUT_FILE",
@@ -5911,17 +5927,23 @@
         },
         "query": {
           "char": "q",
-          "description": "The GraphQL query or mutation, as a string.",
+          "description": "The GraphQL query or mutation, as a string. Omit to open GraphiQL.",
           "env": "SHOPIFY_FLAG_QUERY",
+          "exclusive": [
+            "query-file"
+          ],
           "hasDynamicHelp": false,
           "multiple": false,
           "name": "query",
           "required": false,
           "type": "option"
         },
         "query-file": {
-          "description": "Path to a file containing the GraphQL query or mutation. Can't be used with --query.",
+          "description": "Path to a file containing the GraphQL query or mutation. Can't be used with --query. Omit to open GraphiQL.",
           "env": "SHOPIFY_FLAG_QUERY_FILE",
+          "exclusive": [
+            "query"
+          ],
           "hasDynamicHelp": false,
           "multiple": false,
           "name": "query-file",
@@ -5985,7 +6007,7 @@
       "pluginName": "@shopify/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "Execute GraphQL queries and mutations on a store."
+      "summary": "Execute GraphQL queries and mutations on a store, or open an interactive GraphiQL UI."
     },
     "theme:check": {
       "aliases": [
diff --git a/packages/store/src/cli/commands/store/execute.test.ts b/packages/store/src/cli/commands/store/execute.test.ts
@@ -1,14 +1,17 @@
 import StoreExecute from './execute.js'
 import {executeStoreOperation} from '../../services/store/execute/index.js'
+import {openStoreGraphiQL} from '../../services/store/execute/graphiql.js'
 import {writeOrOutputStoreExecuteResult} from '../../services/store/execute/result.js'
 import {beforeEach, describe, expect, test, vi} from 'vitest'
 
 vi.mock('../../services/store/execute/index.js')
 vi.mock('../../services/store/execute/result.js')
+vi.mock('../../services/store/execute/graphiql.js')
 
 describe('store execute command', () => {
   beforeEach(() => {
     vi.mocked(executeStoreOperation).mockResolvedValue({data: {shop: {name: 'Test shop'}}})
+    vi.mocked(openStoreGraphiQL).mockResolvedValue()
   })
 
   test('passes the inline query through to the service and writes the result', async () => {
@@ -52,5 +55,64 @@ describe('store execute command', () => {
     expect(StoreExecute.flags['variable-file']).toBeDefined()
     expect(StoreExecute.flags['allow-mutations']).toBeDefined()
     expect(StoreExecute.flags.json).toBeDefined()
+    expect(StoreExecute.flags['graphiql-port']).toBeDefined()
+    expect(StoreExecute.flags['no-open']).toBeDefined()
+  })
+
+  describe('GraphiQL mode (no --query / --query-file)', () => {
+    test('opens GraphiQL with --allow-mutations false by default', async () => {
+      await StoreExecute.run(['--store', 'shop.myshopify.com'])
+
+      expect(openStoreGraphiQL).toHaveBeenCalledWith({
+        store: 'shop.myshopify.com',
+        port: undefined,
+        open: true,
+        allowMutations: false,
+        query: undefined,
+        variables: undefined,
+        apiVersion: undefined,
+      })
+      expect(executeStoreOperation).not.toHaveBeenCalled()
+      expect(writeOrOutputStoreExecuteResult).not.toHaveBeenCalled()
+    })
+
+    test('forwards --variables and --version as prefilled values for GraphiQL', async () => {
+      await StoreExecute.run([
+        '--store',
+        'shop.myshopify.com',
+        '--variables',
+        '{"id":"gid://shopify/Product/1"}',
+        '--version',
+        '2024-10',
+      ])
+
+      expect(openStoreGraphiQL).toHaveBeenCalledWith(
+        expect.objectContaining({
+          variables: '{"id":"gid://shopify/Product/1"}',
+          apiVersion: '2024-10',
+        }),
+      )
+    })
+
+    test('respects --graphiql-port and --no-open', async () => {
+      await StoreExecute.run(['--store', 'shop.myshopify.com', '--graphiql-port', '9123', '--no-open'])
+
+      expect(openStoreGraphiQL).toHaveBeenCalledWith(
+        expect.objectContaining({
+          port: 9123,
+          open: false,
+        }),
+      )
+    })
+
+    test('forwards --allow-mutations to the GraphiQL session', async () => {
+      await StoreExecute.run(['--store', 'shop.myshopify.com', '--allow-mutations'])
+
+      expect(openStoreGraphiQL).toHaveBeenCalledWith(
+        expect.objectContaining({
+          allowMutations: true,
+        }),
+      )
+    })
   })
 })
diff --git a/packages/store/src/cli/commands/store/execute.ts b/packages/store/src/cli/commands/store/execute.ts
@@ -1,19 +1,23 @@
 import {executeStoreOperation} from '../../services/store/execute/index.js'
+import {openStoreGraphiQL} from '../../services/store/execute/graphiql.js'
 import {writeOrOutputStoreExecuteResult} from '../../services/store/execute/result.js'
 import StoreCommand from '../../utilities/store-command.js'
 import {globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
 import {normalizeStoreFqdn} from '@shopify/cli-kit/node/context/fqdn'
+import {outputWarn} from '@shopify/cli-kit/node/output'
 import {resolvePath} from '@shopify/cli-kit/node/path'
 import {Flags} from '@oclif/core'
 
 export default class StoreExecute extends StoreCommand {
-  static summary = 'Execute GraphQL queries and mutations on a store.'
+  static summary = 'Execute GraphQL queries and mutations on a store, or open an interactive GraphiQL UI.'
 
   static descriptionWithMarkdown = `Executes an Admin API GraphQL query or mutation on the specified store using previously stored app authentication.
 
 Run \`shopify store auth\` first to create stored auth for the store.
 
-Mutations are disabled by default. Re-run with \`--allow-mutations\` if you intend to modify store data.`
+When neither \`--query\` nor \`--query-file\` is provided, opens a local GraphiQL UI in the browser pointed at the store. Use \`--graphiql-port\` to choose the port and \`--no-open\` to keep the browser closed.
+
+Mutations are disabled by default. Re-run with \`--allow-mutations\` if you intend to modify store data; the same flag controls whether the GraphiQL UI is allowed to issue mutations.`
 
   static description = this.descriptionWithoutMarkdown()
 
@@ -22,23 +26,25 @@ Mutations are disabled by default. Re-run with \`--allow-mutations\` if you inte
     `<%= config.bin %> <%= command.id %> --store shop.myshopify.com --query-file ./operation.graphql --variables '{"id":"gid://shopify/Product/1"}'`,
     '<%= config.bin %> <%= command.id %> --store shop.myshopify.com --query "mutation { shop { id } }" --allow-mutations',
     '<%= config.bin %> <%= command.id %> --store shop.myshopify.com --query "query { shop { name } }" --json',
+    '<%= config.bin %> <%= command.id %> --store shop.myshopify.com',
   ]
 
   static flags = {
     ...globalFlags,
     ...jsonFlag,
     query: Flags.string({
       char: 'q',
-      description: 'The GraphQL query or mutation, as a string.',
+      description: 'The GraphQL query or mutation, as a string. Omit to open GraphiQL.',
       env: 'SHOPIFY_FLAG_QUERY',
       required: false,
-      exactlyOne: ['query', 'query-file'],
+      exclusive: ['query-file'],
     }),
     'query-file': Flags.string({
-      description: "Path to a file containing the GraphQL query or mutation. Can't be used with --query.",
+      description:
+        "Path to a file containing the GraphQL query or mutation. Can't be used with --query. Omit to open GraphiQL.",
       env: 'SHOPIFY_FLAG_QUERY_FILE',
       parse: async (input) => resolvePath(input),
-      exactlyOne: ['query', 'query-file'],
+      exclusive: ['query'],
     }),
     variables: Flags.string({
       char: 'v',
@@ -73,11 +79,40 @@ Mutations are disabled by default. Re-run with \`--allow-mutations\` if you inte
       env: 'SHOPIFY_FLAG_ALLOW_MUTATIONS',
       default: false,
     }),
+    'graphiql-port': Flags.integer({
+      description: 'Local port for the GraphiQL server when no --query or --query-file is provided.',
+      env: 'SHOPIFY_FLAG_GRAPHIQL_PORT',
+    }),
+    'no-open': Flags.boolean({
+      description: 'Do not open the GraphiQL URL in the browser automatically.',
+      env: 'SHOPIFY_FLAG_NO_OPEN',
+      default: false,
+    }),
   }
 
   public async run(): Promise<void> {
     const {flags} = await this.parse(StoreExecute)
 
+    if (!flags.query && !flags['query-file']) {
+      if (flags['output-file']) {
+        outputWarn('--output-file is ignored when opening GraphiQL.')
+      }
+      if (flags.json) {
+        outputWarn('--json is ignored when opening GraphiQL.')
+      }
+
+      await openStoreGraphiQL({
+        store: flags.store,
+        port: flags['graphiql-port'],
+        open: !flags['no-open'],
+        allowMutations: flags['allow-mutations'],
+        query: flags.query,
+        variables: flags.variables,
+        apiVersion: flags.version,
+      })
+      return
+    }
+
     const result = await executeStoreOperation({
       store: flags.store,
       query: flags.query,
diff --git a/packages/store/src/cli/services/store/execute/graphiql.test.ts b/packages/store/src/cli/services/store/execute/graphiql.test.ts
diff --git a/packages/store/src/cli/services/store/execute/graphiql.ts b/packages/store/src/cli/services/store/execute/graphiql.ts
