Add shopify store auth and store execute by dmerand · Pull Request #7122 · Shopify/cli

dmerand · 2026-03-27T16:10:57Z

What

Add shopify store auth and shopify store execute so Shopify CLI can authenticate an app against a store and then run Admin API GraphQL without needing a local app project in the current repo.

shopify store auth starts a PKCE OAuth flow and stores online per-user auth for later store commands.
shopify store execute runs Admin API GraphQL against that stored auth.
Writes require --allow-mutations.
The command surface is aligned with shopify app execute where it makes sense.

Why

We want a clear store workflow in CLI:

authenticate the app against a store
verify access
run store-scoped Admin API operations

This makes store operations usable outside an app project while still using standard app auth and explicit mutation safety.

How

`shopify store auth`

Add a new shopify store auth command that:

authenticates with PKCE (response_type=code, code_challenge, code_challenge_method=S256, code_verifier)
listens on a loopback callback bound to 127.0.0.1
validates the callback store and state before exchanging the code
stores the resulting online token, refresh token, expiry metadata, scopes, and associated user details for reuse by later store commands

`shopify store execute`

Add a new shopify store execute command that:

accepts query / query-file / variables / variable-file / version / output-file flags similar to shopify app execute
parses and validates the GraphQL operation before execution
blocks mutations unless --allow-mutations is passed
fails the command on GraphQL errors instead of treating them as successful output

Session handling

Store auth is persisted per store and per user for the configured app client ID.

When stored auth is expired, shopify store execute refreshes it before version resolution / execution. When stored auth is no longer valid, the current stored session is cleared and the user is prompted to re-run shopify store auth.

That invalid-auth path is handled consistently for:

refresh failures
invalid refresh responses
version-discovery auth failures
execute-time 401s

Internal structure

The execute path is split into request preparation, auth/context loading, transport, and result emission helpers so the command stays thin and the execution flow is easier to reason about.

The implementation also adds a small internal target seam for future store-scoped GraphQL APIs while keeping the current behavior Admin-only.

Manual testing

# Authenticate the app against the store
pnpm run shopify store auth \
  --store shop.myshopify.com \
  --scopes read_products,write_products

# Run a read query
pnpm run shopify store execute \
  --store shop.myshopify.com \
  --query 'query { shop { name id } }'

# Run a query with variables from the command line
pnpm run shopify store execute \
  --store shop.myshopify.com \
  --query-file ./operation.graphql \
  --variables '{"id":"gid://shopify/Product/1"}'

# Verify execute fails without stored auth
pnpm run shopify store execute \
  --store shop.myshopify.com \
  --query 'query { shop { name } }'
# after clearing stored auth, should prompt to run `shopify store auth`

# Verify mutations require explicit opt-in
pnpm run shopify store execute \
  --store shop.myshopify.com \
  --query 'mutation { shop { id } }'
# should fail until --allow-mutations is added

dmerand · 2026-03-27T16:11:11Z

Replace store auth with PKCE and add token refresh #7136
Add shopify store auth and store execute #7122 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

github-actions · 2026-03-27T16:15:42Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	82.35%	15352/18642
🟡	Branches	74.75%	7530/10074
🟢	Functions	81.48%	3853/4729
🟢	Lines	82.75%	14517/17543

Test suite run success

4032 tests passing in 1541 suites.

Report generated by 🧪jest coverage report action from 7aae5d3

dmerand · 2026-03-27T16:27:32Z

/snapit

github-actions · 2026-03-27T16:29:55Z

🫰✨ Thanks @dmerand! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

npm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260327162821

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

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

dmerand · 2026-03-27T20:31:36Z

/snapit

github-actions · 2026-03-27T20:33:59Z

🫰✨ Thanks @dmerand! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

npm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260327203223

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

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

Copilot

Pull request overview

Adds a new “store” workflow to Shopify CLI that can authenticate an app against a store (PKCE, per-user online tokens) and then execute Admin API GraphQL operations without requiring a local app project.

Changes:

Introduces shopify store auth (PKCE OAuth to loopback callback; persists online auth per store/user).
Introduces shopify store execute (Admin API GraphQL execution with variable/query file support, mutation safety via --allow-mutations, and error/failure handling).
Adds supporting session storage, context/version resolution, transport helpers, and CLI docs/topic updates.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/cli/src/index.ts	Registers `store:auth` and `store:execute` commands with the CLI entrypoint.
packages/cli/src/cli/commands/store/auth.ts	New `shopify store auth` command wiring/flags.
packages/cli/src/cli/commands/store/auth.test.ts	Tests flag parsing and service invocation for `store auth`.
packages/cli/src/cli/commands/store/execute.ts	New `shopify store execute` command wiring/flags.
packages/cli/src/cli/commands/store/execute.test.ts	Tests flag parsing and service invocation for `store execute`.
packages/cli/src/cli/services/store/auth-config.ts	Defines store auth client id, callback path/port, session keying, token masking.
packages/cli/src/cli/services/store/session.ts	Implements persisted per-store/per-user session bucket and expiry helper.
packages/cli/src/cli/services/store/session.test.ts	Unit tests for session bucket behavior and expiry margin logic.
packages/cli/src/cli/services/store/auth.ts	Implements PKCE flow, loopback callback server, token exchange, and persistence.
packages/cli/src/cli/services/store/auth.test.ts	Unit tests for PKCE helpers, callback server, token exchange, and persistence.
packages/cli/src/cli/services/store/execute-request.ts	Parses query/query-file, variables, validates single operation and mutation gating.
packages/cli/src/cli/services/store/execute-request.test.ts	Unit tests for request preparation and validation errors.
packages/cli/src/cli/services/store/admin-graphql-context.ts	Loads/refreshes stored auth and resolves Admin API version.
packages/cli/src/cli/services/store/admin-graphql-context.test.ts	Tests refresh flow, invalid auth paths, and version selection/validation.
packages/cli/src/cli/services/store/admin-graphql-transport.ts	Executes Admin GraphQL request and normalizes 401/GraphQL-error handling.
packages/cli/src/cli/services/store/admin-graphql-transport.test.ts	Tests success, 401 clearing + reauth message, GraphQL errors, and passthrough errors.
packages/cli/src/cli/services/store/graphql-targets.ts	Adds an internal target seam (currently Admin-only) for store-scoped GraphQL APIs.
packages/cli/src/cli/services/store/graphql-targets.test.ts	Tests target context preparation and execution delegation.
packages/cli/src/cli/services/store/execute-result.ts	Writes results to file or stdout and emits a success UI message.
packages/cli/src/cli/services/store/execute-result.test.ts	Tests file output vs stdout output behavior.
packages/cli/src/cli/services/store/execute.ts	Orchestrates request prep → context load → execution → result emission.
packages/cli/src/cli/services/store/execute.test.ts	End-to-end-ish unit tests for execute flow behaviors and error cases.
packages/cli/package.json	Adds a new `store` topic/category for CLI command grouping.
packages/cli/README.md	Adds docs entries for new commands (and includes regenerated usage sections).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/cli/README.md

packages/cli/src/cli/services/store/session.ts

ryancbahan · 2026-04-01T01:58:57Z

packages/cli/src/cli/services/store/admin-graphql-context.ts

@@ -0,0 +1,168 @@
+import {fetchApiVersions} from '@shopify/cli-kit/node/api/admin'


there are a lot of different concerns going on in this services area. it'd be nice to establish some clearer patterns of organization around things.

I asked this question myself and landed here. This is definitely a big PR, and if you can believe it the current state is a significant decomposition of several earlier attempts. I agree that we can find more patterns, but I'd like to defer further architectural work until we have either better repo guidelines for service architecture, or more APIs we want to use for store execute that would guide patterns.

ryancbahan · 2026-04-01T02:00:03Z

packages/cli/src/cli/services/store/admin-graphql-context.ts

+    outputContent`Refreshing expired token for ${outputToken.raw(session.store)} (expired at ${outputToken.raw(session.expiresAt ?? 'unknown')}, refresh_token=${outputToken.raw(maskToken(session.refreshToken))})`,
+  )
+
+  const response = await fetch(endpoint, {


it'd be nice to split out the gql scaffolding from the specific queries/mutations

Similar comment here, decomposing the API contexts further is good follow-up work IMO.

ryancbahan · 2026-04-01T02:03:34Z

packages/cli/src/cli/services/store/admin-graphql-context.ts

+  } catch (error) {
+    if (
+      error instanceof AbortError &&
+      error.message.includes(`Error connecting to your store ${adminSession.storeFqdn}:`) &&


can we add a code comment to address the string parsing later?

ryancbahan · 2026-04-01T02:05:41Z

packages/cli/src/cli/services/store/session.ts

+  [key: string]: StoredStoreAppSessionBucket
+}
+
+let _storeSessionStorage: LocalStorage<StoreSessionSchema> | undefined


ideally this gets initialized as part of some lifecycle and not inlined

I agree, but I'd like to address in follow-up given shipping pressure unless you think it's broken.

ryancbahan · 2026-04-01T02:06:17Z

packages/cli/src/cli/services/store/graphql-targets.ts

+}
+
+export function getStoreGraphQLTarget(api: StoreGraphQLApi): StoreGraphQLTarget<AdminStoreGraphQLContext> {
+  switch (api) {


what other targets are we going to be supporting?

Admin API is a known first target, and we know we're going to be adding more -- the conceptual limit would be all of the APIs that dev-mcp supports. Since each API has its own auth/setup concerns, I've designed it to make those pluggable. It's arguably not necessary for this first PR, but I also wanted to guide agents not to make monolithic additions, which were definitely their preference here.

ryancbahan · 2026-04-01T02:07:35Z

packages/cli/src/cli/services/store/execute.ts

+    allowMutations: input.allowMutations,
+  })
+
+  const context = await renderSingleTask({


unrelated as it's an existing pattern, but i really want us to split out rendering and data flow more

Agree. This could be a function that returns an object that is renderable, or a task, and the rendering could be separate. Not to litigate in this PR though.

ryancbahan

code generally makes sense. i think there are some improvements we can make to organization, and generally to establishing more clarity around what goes where.

ryancbahan

tophatted and works as expected. nice job! a few small notes:

the "authorization successful" callback view that opens in browser after auth is totally unstyled. would be nice to improve that
after running auth, the command outputs a "next steps" block. this is nice, but has two minor issues:
1. it renders backticks inline, presumably for markdown codelbock that doesn't exist
2. when the text breaks to a newline, it adds a pipe | where the newline break is, which breaks the ability to copy/paste

craigmichaelmartin · 2026-04-01T16:33:06Z

/snapit

github-actions · 2026-04-01T16:35:43Z

🫰✨ Thanks @craigmichaelmartin! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

npm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260401163359

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.

dmerand force-pushed the store-execute branch from 2ae87db to ad2aea3 Compare March 27, 2026 16:26

dmerand force-pushed the store-execute branch 2 times, most recently from e15c53b to 893af23 Compare March 27, 2026 16:59

github-advanced-security bot found potential problems Mar 27, 2026

View reviewed changes

packages/cli/src/cli/services/store/auth.ts Fixed Show fixed Hide fixed

dmerand force-pushed the store-execute branch from ff99bca to 1664aae Compare March 27, 2026 20:31

dmerand force-pushed the store-execute branch from 1664aae to 7aae5d3 Compare March 30, 2026 14:45

github-advanced-security bot found potential problems Mar 30, 2026

View reviewed changes

packages/cli/src/cli/services/store/auth.ts Fixed Show fixed Hide fixed

dmerand force-pushed the store-execute branch 2 times, most recently from 97030c7 to 0a0c94d Compare March 31, 2026 17:35

RyanDJLee mentioned this pull request Mar 31, 2026

Replace store auth with PKCE and add token refresh #7136

Closed

7 tasks

dmerand force-pushed the store-execute branch from 0a0c94d to 5afc583 Compare March 31, 2026 21:00

dmerand changed the title ~~Proto: shopify store execute~~ Add shopify store auth and store execute Mar 31, 2026

dmerand force-pushed the store-execute branch 4 times, most recently from 3d0c271 to c83e839 Compare March 31, 2026 22:36

dmerand marked this pull request as ready for review March 31, 2026 22:37

dmerand requested review from a team as code owners March 31, 2026 22:37

dmerand requested review from Copilot, isaacroldan and ryancbahan March 31, 2026 22:37

Copilot started reviewing on behalf of dmerand March 31, 2026 22:37 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

packages/cli/README.md Outdated Show resolved Hide resolved

packages/cli/README.md Outdated Show resolved Hide resolved

packages/cli/src/cli/services/store/session.ts Outdated Show resolved Hide resolved

packages/cli/src/cli/services/store/session.ts Outdated Show resolved Hide resolved

dmerand force-pushed the store-execute branch from c83e839 to b03b785 Compare March 31, 2026 22:42

This comment has been minimized.

Sign in to view

dmerand force-pushed the store-execute branch 7 times, most recently from 870584e to a462574 Compare March 31, 2026 23:51

ryancbahan reviewed Apr 1, 2026

View reviewed changes

Add shopify store execute / auth

ff40140

dmerand force-pushed the store-execute branch from a462574 to ff40140 Compare April 1, 2026 14:11

dmerand requested a review from ryancbahan April 1, 2026 14:23

ryancbahan approved these changes Apr 1, 2026

View reviewed changes

dmerand requested a review from craigmichaelmartin April 1, 2026 18:19

Style callback + format next steps

d79c6c4

dmerand force-pushed the store-execute branch from 259a931 to d79c6c4 Compare April 1, 2026 18:41

		@@ -0,0 +1,168 @@
		import {fetchApiVersions} from '@shopify/cli-kit/node/api/admin'

Conversation

dmerand commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

shopify store auth

shopify store execute

Session handling

Internal structure

Manual testing

Uh oh!

dmerand commented Mar 27, 2026 • edited by RyanDJLee Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Test suite run success

Uh oh!

dmerand commented Mar 27, 2026

Uh oh!

github-actions bot commented Mar 27, 2026

Uh oh!

Uh oh!

dmerand commented Mar 27, 2026

Uh oh!

github-actions bot commented Mar 27, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryancbahan left a comment

Choose a reason for hiding this comment

Uh oh!

ryancbahan left a comment

Choose a reason for hiding this comment

Uh oh!

craigmichaelmartin commented Apr 1, 2026

Uh oh!

github-actions bot commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dmerand commented Mar 27, 2026 •

edited

Loading

`shopify store auth`

`shopify store execute`

dmerand commented Mar 27, 2026 •

edited by RyanDJLee

Loading

github-actions bot commented Mar 27, 2026 •

edited

Loading