Add resumable auth login for non-TTY flows

Allow agents to start Shopify auth without blocking on device-code polling, then resume the stashed device code exchange after the user authorizes.

Author: gonzaloriestra

.changeset/resumable-auth-login.md

@@ -0,0 +1,6 @@
+---
+'@shopify/cli': minor
+'@shopify/cli-kit': minor
+---
+
+Add resumable non-interactive `shopify auth login` with `--resume` and `--new`.

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

@@ -9,4 +9,16 @@ export interface authlogin {
    * @environment SHOPIFY_FLAG_AUTH_ALIAS
    */
   '--alias <value>'?: string
+
+  /**
+   * Log in with a new account instead of choosing from existing sessions.
+   * @environment SHOPIFY_FLAG_AUTH_NEW
+   */
+  '--new'?: ''
+
+  /**
+   * Resume a pending non-interactive login flow.
+   * @environment SHOPIFY_FLAG_AUTH_RESUME
+   */
+  '--resume'?: ''
 }

docs-shopify.dev/generated/generated_docs_data_v2.json

@@ -2592,9 +2592,27 @@
           "description": "Alias of the session you want to login to.",
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_AUTH_ALIAS"
+        },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/auth-login.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--new",
+          "value": "''",
+          "description": "Log in with a new account instead of choosing from existing sessions.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_AUTH_NEW"
+        },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/auth-login.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "--resume",
+          "value": "''",
+          "description": "Resume a pending non-interactive login flow.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_AUTH_RESUME"
         }
       ],
-      "value": "export interface authlogin {\n  /**\n   * Alias of the session you want to login to.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--alias <value>'?: string\n}"
+      "value": "export interface authlogin {\n  /**\n   * Alias of the session you want to login to.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--alias <value>'?: string\n\n  /**\n   * Log in with a new account instead of choosing from existing sessions.\n   * @environment SHOPIFY_FLAG_AUTH_NEW\n   */\n  '--new'?: ''\n\n  /**\n   * Resume a pending non-interactive login flow.\n   * @environment SHOPIFY_FLAG_AUTH_RESUME\n   */\n  '--resume'?: ''\n}"
     }
   },
   "authlogout": {

docs/README.md

@@ -12,6 +12,7 @@ The list below contains valuable resources for people interested in contributing
 
 * [Get started](./cli/get-started.md)
 * [Architecture](./cli/architecture.md)
+* [Authentication](./cli/auth.md)
 * [Conventions](./cli/conventions.md)
 * [Performance](./cli/performance.md)
 * [Debugging](./cli/debugging.md)

docs/cli/auth.md

@@ -0,0 +1,48 @@
+# Shopify CLI Authentication
+
+Shopify CLI authenticates developers with Shopify through a device-code OAuth flow. This works in local terminals, remote development environments, and agent-driven workflows where a browser might not be available to the CLI process.
+
+## Recommended Flow
+
+1. Check whether a session is already available with `shopify auth status` or `shopify auth status --json`.
+2. If a session is available, continue with the command that needs authentication.
+3. If no session is available, run `shopify auth login`.
+4. Shopify CLI prints a verification URL and user code, or opens the verification URL in your browser.
+5. The user completes login in the browser.
+6. Complete the CLI flow:
+   - In an interactive terminal, keep the command running. It polls and continues automatically after authentication succeeds.
+   - In a non-TTY environment, run `shopify auth login --resume` after the user authorizes.
+
+Agents should show the verification URL and user code to the user, ask the user to complete authentication in the browser, and then either wait for the interactive command to finish or run `shopify auth login --resume` for a non-TTY login.
+
+## Commands
+
+- `shopify auth status`: Check whether Shopify CLI has a usable Shopify account session. Use `--json` for stable machine-readable output.
+- `shopify auth login`: Log in to a Shopify account. In a non-TTY environment, this starts the device-code flow, prints the verification URL and code, stashes the device code, and exits without waiting.
+- `shopify auth login --resume`: Resume a pending non-TTY login after the user has authorized in the browser. On success, Shopify CLI exchanges the stashed device code for tokens and stores the session.
+- `shopify auth login --new`: Start a new login instead of reusing or choosing from existing sessions.
+- `shopify auth logout`: Clear the stored Shopify CLI session.
+- Commands that need authentication may start the same login flow automatically when no usable session exists.
+
+## Non-TTY Behavior
+
+When `shopify auth login` runs without a TTY:
+
+1. Shopify CLI checks for an existing usable session.
+2. If a session exists, Shopify CLI prints the current account and exits without starting a new login.
+3. If no session exists, Shopify CLI starts device authorization, prints the verification URL and user code, stores the pending device code, and exits immediately.
+4. After the user authorizes in the browser, run `shopify auth login --resume`.
+
+Use `shopify auth login --new` to skip the existing-session check and start a new device authorization flow.
+
+## CI
+
+Do not start browser-based login from CI. Use credentials provided through the supported environment variables for the command you are running.
+
+## Scopes
+
+Shopify CLI requests the scopes needed for CLI workflows, including access to Shopify Admin, Partners, Storefront Renderer, Business Platform, and App Management APIs. Individual commands may request additional scopes for the task being performed.
+
+## Support
+
+For issues with Shopify CLI authentication, see https://shopify.dev/docs/api/shopify-cli or contact Shopify support at https://help.shopify.com.

packages/cli-kit/src/private/node/conf-store.test.ts

@@ -13,6 +13,9 @@ import {
   getCachedPartnerAccountStatus,
   setCachedPartnerAccountStatus,
   runWithRateLimit,
+  clearPendingDeviceAuth,
+  getPendingDeviceAuth,
+  setPendingDeviceAuth,
 } from './conf-store.js'
 import {isLocalEnvironment} from './context/service.js'
 import {LocalStorage} from '../../public/node/local-storage.js'
@@ -194,6 +197,34 @@ describe('removeCurrentSessionId', () => {
   })
 })
 
+describe('pending device auth', () => {
+  test('stores, reads, and clears pending device auth', async () => {
+    await inTemporaryDirectory(async (cwd) => {
+      // Given
+      const config = new LocalStorage<ConfSchema>({cwd})
+      const pendingDeviceAuth = {
+        deviceCode: 'device-code',
+        userCode: 'user-code',
+        verificationUriComplete: 'https://accounts.shopify.com/activate?user_code=user-code',
+        interval: 5,
+        expiresAt: 1893456000000,
+      }
+
+      // When
+      setPendingDeviceAuth(pendingDeviceAuth, config)
+
+      // Then
+      expect(getPendingDeviceAuth(config)).toEqual(pendingDeviceAuth)
+
+      // When
+      clearPendingDeviceAuth(config)
+
+      // Then
+      expect(getPendingDeviceAuth(config)).toBeUndefined()
+    })
+  })
+})
+
 describe('session environment isolation', () => {
   test('getSessions returns production sessions in production', async () => {
     await inTemporaryDirectory(async (cwd) => {

packages/cli-kit/src/private/node/conf-store.ts

@@ -26,13 +26,22 @@ interface Cache {
   [rateLimitKey: RateLimitKey]: CacheValue<number[]>
 }
 
+export interface PendingDeviceAuth {
+  deviceCode: string
+  userCode: string
+  verificationUriComplete: string
+  interval: number
+  expiresAt: number
+}
+
 export interface ConfSchema {
   sessionStore: string
   currentSessionId?: string
   devSessionStore?: string
   currentDevSessionId?: string
   cache?: Cache
   autoUpgradeEnabled?: boolean
+  pendingDeviceAuth?: PendingDeviceAuth
 }
 
 let _instance: LocalStorage<ConfSchema> | undefined
@@ -111,6 +120,31 @@ export function removeCurrentSessionId(config: LocalStorage<ConfSchema> = cliKit
   config.delete(currentSessionIdKey())
 }
 
+/**
+ * Get pending device auth state for a resumable non-interactive login flow.
+ *
+ * @returns Pending device auth state, if present.
+ */
+export function getPendingDeviceAuth(config: LocalStorage<ConfSchema> = cliKitStore()): PendingDeviceAuth | undefined {
+  return config.get('pendingDeviceAuth')
+}
+
+/**
+ * Stash pending device auth state for a later `shopify auth login --resume`.
+ *
+ * @param auth - Pending device auth state.
+ */
+export function setPendingDeviceAuth(auth: PendingDeviceAuth, config: LocalStorage<ConfSchema> = cliKitStore()): void {
+  config.set('pendingDeviceAuth', auth)
+}
+
+/**
+ * Clear pending device auth state after completion or expiry.
+ */
+export function clearPendingDeviceAuth(config: LocalStorage<ConfSchema> = cliKitStore()): void {
+  config.delete('pendingDeviceAuth')
+}
+
 type CacheValueForKey<TKey extends keyof Cache> = NonNullable<Cache[TKey]>['value']
 
 /**

packages/cli-kit/src/private/node/session.ts

@@ -294,8 +294,6 @@ The CLI is currently unable to prompt for reauthentication.`,
  */
 async function executeCompleteFlow(applications: OAuthApplications, existingAlias?: string): Promise<Session> {
   const scopes = getFlattenScopes(applications)
-  const exchangeScopes = getExchangeScopes(applications)
-  const store = applications.adminApi?.storeFqdn
   if (firstPartyDev()) {
     outputDebug(outputContent`Authenticating as Shopify Employee...`)
     scopes.push('employee')
@@ -315,6 +313,28 @@ async function executeCompleteFlow(applications: OAuthApplications, existingAlia
     identityToken = await pollForDeviceAuthorization(deviceAuth.deviceCode, deviceAuth.interval)
   }
 
+  const session = await completeAuthFlow(identityToken, applications, existingAlias)
+  outputCompleted(`Logged in.`)
+  return session
+}
+
+/**
+ * Given an identity token, exchange it for application tokens and build a complete session.
+ * Shared between the interactive login flow and the resumable non-interactive flow.
+ *
+ * @param identityToken - Identity token returned by the OAuth device code flow.
+ * @param applications - Applications to exchange access tokens for.
+ * @param existingAlias - Optional alias from a previous session to preserve if the email fetch fails.
+ * @returns A complete session with identity and application tokens.
+ */
+export async function completeAuthFlow(
+  identityToken: IdentityToken,
+  applications: OAuthApplications,
+  existingAlias?: string,
+): Promise<Session> {
+  const exchangeScopes = getExchangeScopes(applications)
+  const store = applications.adminApi?.storeFqdn
+
   // Exchange identity token for application tokens
   outputDebug(outputContent`CLI token received. Exchanging it for application tokens...`)
   const result = await exchangeAccessForApplicationTokens(identityToken, exchangeScopes, store)
@@ -330,9 +350,6 @@ async function executeCompleteFlow(applications: OAuthApplications, existingAlia
     },
     applications: result,
   }
-
-  outputCompleted(`Logged in.`)
-
   return session
 }
 

packages/cli-kit/src/private/node/session/device-authorization.test.ts

@@ -8,10 +8,11 @@ import {IdentityToken} from './schema.js'
 import {exchangeDeviceCodeForAccessToken} from './exchange.js'
 import {identityFqdn} from '../../../public/node/context/fqdn.js'
 import {shopifyFetch} from '../../../public/node/http.js'
-import {isTTY} from '../../../public/node/ui.js'
+import {isTTY, keypress} from '../../../public/node/ui.js'
 import {err, ok} from '../../../public/node/result.js'
 import {AbortError} from '../../../public/node/error.js'
-import {isCI} from '../../../public/node/system.js'
+import {isCI, openURL} from '../../../public/node/system.js'
+import {mockAndCaptureOutput} from '../../../public/node/testing/output.js'
 
 import {beforeEach, describe, expect, test, vi} from 'vitest'
 import {Response} from 'node-fetch'
@@ -24,6 +25,7 @@ vi.mock('./exchange.js')
 vi.mock('../../../public/node/system.js')
 
 beforeEach(() => {
+  vi.clearAllMocks()
   vi.mocked(isTTY).mockReturnValue(true)
   vi.mocked(isCI).mockReturnValue(false)
 })
@@ -66,6 +68,26 @@ describe('requestDeviceAuthorization', () => {
     expect(got).toEqual(dataExpected)
   })
 
+  test('can request a device auth code without prompting or polling', async () => {
+    // Given
+    const outputMock = mockAndCaptureOutput()
+    const response = new Response(JSON.stringify(data))
+    vi.mocked(shopifyFetch).mockResolvedValue(response)
+    vi.mocked(identityFqdn).mockResolvedValue('fqdn.com')
+    vi.mocked(clientId).mockReturnValue('clientId')
+    vi.mocked(isCI).mockReturnValue(true)
+
+    // When
+    const got = await requestDeviceAuthorization(['scope1', 'scope2'], {noPrompt: true})
+
+    // Then
+    expect(got).toEqual(dataExpected)
+    expect(keypress).not.toHaveBeenCalled()
+    expect(openURL).not.toHaveBeenCalled()
+    expect(outputMock.info()).toContain('User verification code: user_code')
+    expect(outputMock.info()).toContain('verification_uri_complete')
+  })
+
   test('when the response is not valid JSON, throw an error with context', async () => {
     // Given
     const response = new Response('not valid JSON')

packages/cli-kit/src/private/node/session/device-authorization.ts

@@ -28,9 +28,13 @@ export interface DeviceAuthorizationResponse {
  * Also returns a `deviceCode` used for polling the token endpoint in the next step.
  *
  * @param scopes - The scopes to request
+ * @param options - Optional settings for presenting the device authorization instructions.
  * @returns An object with the device authorization response.
  */
-export async function requestDeviceAuthorization(scopes: string[]): Promise<DeviceAuthorizationResponse> {
+export async function requestDeviceAuthorization(
+  scopes: string[],
+  {noPrompt = false}: {noPrompt?: boolean} = {},
+): Promise<DeviceAuthorizationResponse> {
   const fqdn = await identityFqdn()
   const identityClientId = clientId()
   const queryParams = {client_id: identityClientId, scope: scopes.join(' ')}
@@ -69,32 +73,39 @@ export async function requestDeviceAuthorization(scopes: string[]): Promise<Devi
     throw new BugError('Failed to start authorization process')
   }
 
-  outputInfo('\nTo run this command, log in to Shopify.')
-
-  if (isCI()) {
-    throw new AbortError(
-      'Authorization is required to continue, but the current environment does not support interactive prompts.',
-      'To resolve this, specify credentials in your environment, or run the command in an interactive environment such as your local terminal.',
-    )
-  }
-
-  outputInfo(outputContent`User verification code: ${jsonResult.user_code}`)
   const linkToken = outputToken.link(jsonResult.verification_uri_complete)
 
   const cloudMessage = () => {
     outputInfo(outputContent`👉 Open this link to start the auth process: ${linkToken}`)
   }
 
-  if (isCloudEnvironment() || !isTTY()) {
+  if (noPrompt) {
+    outputInfo('\nTo log in to Shopify, open the following URL and enter the verification code.')
+    outputInfo(outputContent`User verification code: ${jsonResult.user_code}`)
     cloudMessage()
   } else {
-    outputInfo('👉 Press any key to open the login page on your browser')
-    await keypress()
-    const opened = await openURL(jsonResult.verification_uri_complete)
-    if (opened) {
-      outputInfo(outputContent`Opened link to start the auth process: ${linkToken}`)
-    } else {
+    outputInfo('\nTo run this command, log in to Shopify.')
+
+    if (isCI()) {
+      throw new AbortError(
+        'Authorization is required to continue, but the current environment does not support interactive prompts.',
+        'To resolve this, specify credentials in your environment, or run the command in an interactive environment such as your local terminal.',
+      )
+    }
+
+    outputInfo(outputContent`User verification code: ${jsonResult.user_code}`)
+
+    if (isCloudEnvironment() || !isTTY()) {
       cloudMessage()
+    } else {
+      outputInfo('👉 Press any key to open the login page on your browser')
+      await keypress()
+      const opened = await openURL(jsonResult.verification_uri_complete)
+      if (opened) {
+        outputInfo(outputContent`Opened link to start the auth process: ${linkToken}`)
+      } else {
+        cloudMessage()
+      }
     }
   }