Add resumable store auth for non-TTY flows

Let store auth start OAuth without waiting in non-TTY contexts, then resume from the browser callback URL to store the app session.

Author: gonzaloriestra

.changeset/store-auth-resume.md

@@ -0,0 +1,6 @@
+---
+'@shopify/store': minor
+'@shopify/cli': minor
+---
+
+Add resumable non-interactive `shopify store auth`.

docs-shopify.dev/commands/interfaces/store-auth.interface.ts

@@ -4,6 +4,12 @@
  * @publicDocs
  */
 export interface storeauth {
+  /**
+   * The final callback URL from the browser after authorizing the app.
+   * @environment SHOPIFY_FLAG_STORE_AUTH_CALLBACK_URL
+   */
+  '--callback-url <value>'?: string
+
   /**
    * Output the result as JSON. Automatically disables color output.
    * @environment SHOPIFY_FLAG_JSON
@@ -16,17 +22,23 @@ export interface storeauth {
    */
   '--no-color'?: ''
 
+  /**
+   * Resume a pending non-interactive store authentication flow.
+   * @environment SHOPIFY_FLAG_STORE_AUTH_RESUME
+   */
+  '--resume'?: ''
+
   /**
    * Comma-separated Admin API scopes to request for the app.
    * @environment SHOPIFY_FLAG_SCOPES
    */
-  '--scopes <value>': string
+  '--scopes <value>'?: string
 
   /**
    * The myshopify.com domain of the store to authenticate against.
    * @environment SHOPIFY_FLAG_STORE
    */
-  '-s, --store <value>': string
+  '-s, --store <value>'?: string
 
   /**
    * Increase the verbosity of the output.

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -4175,6 +4175,15 @@
       "description": "The following flags are available for the `store auth` command:",
       "isPublicDocs": true,
       "members": [
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/store-auth.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--callback-url <value>",
+          "value": "string",
+          "description": "The final callback URL from the browser after authorizing the app.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_STORE_AUTH_CALLBACK_URL"
+        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/store-auth.interface.ts",
           "syntaxKind": "PropertySignature",
@@ -4184,12 +4193,22 @@
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_NO_COLOR"
         },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/store-auth.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--resume",
+          "value": "''",
+          "description": "Resume a pending non-interactive store authentication flow.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_STORE_AUTH_RESUME"
+        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/store-auth.interface.ts",
           "syntaxKind": "PropertySignature",
           "name": "--scopes <value>",
           "value": "string",
           "description": "Comma-separated Admin API scopes to request for the app.",
+          "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_SCOPES"
         },
         {
@@ -4216,10 +4235,11 @@
           "name": "-s, --store <value>",
           "value": "string",
           "description": "The myshopify.com domain of the store to authenticate against.",
+          "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_STORE"
         }
       ],
-      "value": "export interface storeauth {\n  /**\n   * Output the result as JSON. Automatically disables color output.\n   * @environment SHOPIFY_FLAG_JSON\n   */\n  '-j, --json'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Comma-separated Admin API scopes to request for the app.\n   * @environment SHOPIFY_FLAG_SCOPES\n   */\n  '--scopes <value>': string\n\n  /**\n   * The myshopify.com domain of the store to authenticate against.\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}"
+      "value": "export interface storeauth {\n  /**\n   * The final callback URL from the browser after authorizing the app.\n   * @environment SHOPIFY_FLAG_STORE_AUTH_CALLBACK_URL\n   */\n  '--callback-url <value>'?: string\n\n  /**\n   * Output the result as JSON. Automatically disables color output.\n   * @environment SHOPIFY_FLAG_JSON\n   */\n  '-j, --json'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * Resume a pending non-interactive store authentication flow.\n   * @environment SHOPIFY_FLAG_STORE_AUTH_RESUME\n   */\n  '--resume'?: ''\n\n  /**\n   * Comma-separated Admin API scopes to request for the app.\n   * @environment SHOPIFY_FLAG_SCOPES\n   */\n  '--scopes <value>'?: string\n\n  /**\n   * The myshopify.com domain of the store to authenticate against.\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}"
     }
   },
   "storeexecute": {

packages/cli/README.md

@@ -2157,15 +2157,19 @@ Authenticate an app against a store for store commands.
 
 ```
 USAGE
-  $ shopify store auth --scopes <value> -s <value> [-j] [--no-color] [--verbose]
+  $ shopify store auth [--callback-url <value>] [-j] [--no-color] [--resume] [--scopes <value>] [-s <value>]
+    [--verbose]
 
 FLAGS
-  -j, --json            [env: SHOPIFY_FLAG_JSON] Output the result as JSON. Automatically disables color output.
-  -s, --store=<value>   (required) [env: SHOPIFY_FLAG_STORE] The myshopify.com domain of the store to authenticate
-                        against.
-      --no-color        [env: SHOPIFY_FLAG_NO_COLOR] Disable color output.
-      --scopes=<value>  (required) [env: SHOPIFY_FLAG_SCOPES] Comma-separated Admin API scopes to request for the app.
-      --verbose         [env: SHOPIFY_FLAG_VERBOSE] Increase the verbosity of the output.
+  -j, --json                  [env: SHOPIFY_FLAG_JSON] Output the result as JSON. Automatically disables color output.
+  -s, --store=<value>         [env: SHOPIFY_FLAG_STORE] The myshopify.com domain of the store to authenticate against.
+      --callback-url=<value>  [env: SHOPIFY_FLAG_STORE_AUTH_CALLBACK_URL] The final callback URL from the browser after
+                              authorizing the app.
+      --no-color              [env: SHOPIFY_FLAG_NO_COLOR] Disable color output.
+      --resume                [env: SHOPIFY_FLAG_STORE_AUTH_RESUME] Resume a pending non-interactive store
+                              authentication flow.
+      --scopes=<value>        [env: SHOPIFY_FLAG_SCOPES] Comma-separated Admin API scopes to request for the app.
+      --verbose               [env: SHOPIFY_FLAG_VERBOSE] Increase the verbosity of the output.
 
 DESCRIPTION
   Authenticate an app against a store for store commands.
@@ -2175,10 +2179,18 @@ DESCRIPTION
 
   Re-run this command if the stored token is missing, expires, or no longer has the scopes you need.
 
+  In a non-TTY environment, Shopify CLI returns the current session if it already has the requested scopes. If no usable
+  session exists, it starts OAuth, prints the authorization URL, stashes the PKCE state, and exits without waiting.
+
+  After authorizing in a browser, copy the final callback URL and run `shopify store auth --resume --callback-url
+  <callback-url>`.
+
 EXAMPLES
   $ shopify store auth --store shop.myshopify.com --scopes read_products,write_products
 
   $ shopify store auth --store shop.myshopify.com --scopes read_products,write_products --json
+
+  $ shopify store auth --resume --callback-url "http://127.0.0.1:13387/auth/callback?..."
 ```
 
 ## `shopify store execute`

packages/cli/oclif.manifest.json

@@ -5730,13 +5730,22 @@
       "args": {
       },
       "customPluginName": "@shopify/store",
-      "description": "Authenticates the app against the specified store for store commands and stores an online access token for later reuse.\n\nRe-run this command if the stored token is missing, expires, or no longer has the scopes you need.",
-      "descriptionWithMarkdown": "Authenticates the app against the specified store for store commands and stores an online access token for later reuse.\n\nRe-run this command if the stored token is missing, expires, or no longer has the scopes you need.",
+      "description": "Authenticates the app against the specified store for store commands and stores an online access token for later reuse.\n\nRe-run this command if the stored token is missing, expires, or no longer has the scopes you need.\n\nIn a non-TTY environment, Shopify CLI returns the current session if it already has the requested scopes. If no usable session exists, it starts OAuth, prints the authorization URL, stashes the PKCE state, and exits without waiting.\n\nAfter authorizing in a browser, copy the final callback URL and run `shopify store auth --resume --callback-url <callback-url>`.",
+      "descriptionWithMarkdown": "Authenticates the app against the specified store for store commands and stores an online access token for later reuse.\n\nRe-run this command if the stored token is missing, expires, or no longer has the scopes you need.\n\nIn a non-TTY environment, Shopify CLI returns the current session if it already has the requested scopes. If no usable session exists, it starts OAuth, prints the authorization URL, stashes the PKCE state, and exits without waiting.\n\nAfter authorizing in a browser, copy the final callback URL and run `shopify store auth --resume --callback-url <callback-url>`.",
       "examples": [
         "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --scopes read_products,write_products",
-        "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --scopes read_products,write_products --json"
+        "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --scopes read_products,write_products --json",
+        "<%= config.bin %> <%= command.id %> --resume --callback-url \"http://127.0.0.1:13387/auth/callback?...\""
       ],
       "flags": {
+        "callback-url": {
+          "description": "The final callback URL from the browser after authorizing the app.",
+          "env": "SHOPIFY_FLAG_STORE_AUTH_CALLBACK_URL",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "callback-url",
+          "type": "option"
+        },
         "json": {
           "allowNo": false,
           "char": "j",
@@ -5754,13 +5763,19 @@
           "name": "no-color",
           "type": "boolean"
         },
+        "resume": {
+          "allowNo": false,
+          "description": "Resume a pending non-interactive store authentication flow.",
+          "env": "SHOPIFY_FLAG_STORE_AUTH_RESUME",
+          "name": "resume",
+          "type": "boolean"
+        },
         "scopes": {
           "description": "Comma-separated Admin API scopes to request for the app.",
           "env": "SHOPIFY_FLAG_SCOPES",
           "hasDynamicHelp": false,
           "multiple": false,
           "name": "scopes",
-          "required": true,
           "type": "option"
         },
         "store": {
@@ -5770,7 +5785,6 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "name": "store",
-          "required": true,
           "type": "option"
         },
         "verbose": {

packages/store/src/cli/commands/store/auth.test.ts

@@ -1,5 +1,5 @@
 import StoreAuth from './auth.js'
-import {authenticateStoreWithApp} from '../../services/store/auth/index.js'
+import {authenticateStoreWithApp, resumeStoreAuthWithApp} from '../../services/store/auth/index.js'
 import {createStoreAuthPresenter} from '../../services/store/auth/result.js'
 import {describe, expect, test, vi} from 'vitest'
 
@@ -36,10 +36,25 @@ describe('store auth command', () => {
     )
   })
 
+  test('resumes store auth with callback URL', async () => {
+    await StoreAuth.run(['--resume', '--callback-url', 'http://127.0.0.1:13387/auth/callback?code=abc'])
+
+    expect(createStoreAuthPresenter).toHaveBeenCalledWith('text')
+    expect(resumeStoreAuthWithApp).toHaveBeenCalledWith(
+      {
+        callbackUrl: 'http://127.0.0.1:13387/auth/callback?code=abc',
+      },
+      {presenter: {format: 'text'}},
+    )
+    expect(authenticateStoreWithApp).not.toHaveBeenCalled()
+  })
+
   test('defines the expected flags', () => {
     expect(StoreAuth.flags.store).toBeDefined()
     expect(StoreAuth.flags.scopes).toBeDefined()
     expect(StoreAuth.flags.json).toBeDefined()
+    expect(StoreAuth.flags.resume).toBeDefined()
+    expect(StoreAuth.flags['callback-url']).toBeDefined()
     expect('port' in StoreAuth.flags).toBe(false)
     expect('client-secret-file' in StoreAuth.flags).toBe(false)
   })

packages/store/src/cli/commands/store/auth.ts

@@ -1,6 +1,7 @@
-import {authenticateStoreWithApp} from '../../services/store/auth/index.js'
+import {authenticateStoreWithApp, resumeStoreAuthWithApp} from '../../services/store/auth/index.js'
 import {createStoreAuthPresenter} from '../../services/store/auth/result.js'
 import StoreCommand from '../../utilities/store-command.js'
+import {AbortError} from '@shopify/cli-kit/node/error'
 import {globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
 import {normalizeStoreFqdn} from '@shopify/cli-kit/node/context/fqdn'
 import {Flags} from '@oclif/core'
@@ -10,13 +11,18 @@ export default class StoreAuth extends StoreCommand {
 
   static descriptionWithMarkdown = `Authenticates the app against the specified store for store commands and stores an online access token for later reuse.
 
-Re-run this command if the stored token is missing, expires, or no longer has the scopes you need.`
+Re-run this command if the stored token is missing, expires, or no longer has the scopes you need.
+
+In a non-TTY environment, Shopify CLI returns the current session if it already has the requested scopes. If no usable session exists, it starts OAuth, prints the authorization URL, stashes the PKCE state, and exits without waiting.
+
+After authorizing in a browser, copy the final callback URL and run \`shopify store auth --resume --callback-url <callback-url>\`.`
 
   static description = this.descriptionWithoutMarkdown()
 
   static examples = [
     '<%= config.bin %> <%= command.id %> --store shop.myshopify.com --scopes read_products,write_products',
     '<%= config.bin %> <%= command.id %> --store shop.myshopify.com --scopes read_products,write_products --json',
+    '<%= config.bin %> <%= command.id %> --resume --callback-url "http://127.0.0.1:13387/auth/callback?..."',
   ]
 
   static flags = {
@@ -27,25 +33,51 @@ Re-run this command if the stored token is missing, expires, or no longer has th
       description: 'The myshopify.com domain of the store to authenticate against.',
       env: 'SHOPIFY_FLAG_STORE',
       parse: async (input) => normalizeStoreFqdn(input),
-      required: true,
     }),
     scopes: Flags.string({
       description: 'Comma-separated Admin API scopes to request for the app.',
       env: 'SHOPIFY_FLAG_SCOPES',
-      required: true,
+    }),
+    resume: Flags.boolean({
+      description: 'Resume a pending non-interactive store authentication flow.',
+      default: false,
+      env: 'SHOPIFY_FLAG_STORE_AUTH_RESUME',
+    }),
+    'callback-url': Flags.string({
+      description: 'The final callback URL from the browser after authorizing the app.',
+      env: 'SHOPIFY_FLAG_STORE_AUTH_CALLBACK_URL',
     }),
   }
 
   public async run(): Promise<void> {
     const {flags} = await this.parse(StoreAuth)
+    const presenter = createStoreAuthPresenter(flags.json ? 'json' : 'text')
+
+    if (flags.resume) {
+      if (!flags['callback-url']) {
+        throw new AbortError('Missing callback URL.', 'Pass --callback-url with the final browser callback URL.')
+      }
+
+      await resumeStoreAuthWithApp(
+        {callbackUrl: flags['callback-url']},
+        {
+          presenter,
+        },
+      )
+      return
+    }
+
+    if (!flags.store || !flags.scopes) {
+      throw new AbortError('Missing required flags.', 'Pass --store and --scopes, or use --resume with --callback-url.')
+    }
 
     await authenticateStoreWithApp(
       {
         store: flags.store,
         scopes: flags.scopes,
       },
       {
-        presenter: createStoreAuthPresenter(flags.json ? 'json' : 'text'),
+        presenter,
       },
     )
   }