From d3478fec57d1bbf7cd7c09c265f1c8fc67ad3a06 Mon Sep 17 00:00:00 2001
From: Alfonso Noriega <alfonso.noriega@shopify.com>
Date: Tue, 19 May 2026 15:20:54 +0200
Subject: [PATCH] feat(store): add shopify store list command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lists every locally stored store-auth session — both standard
PKCE-authenticated (shopify store auth) and preview-store
(shopify store create preview) — with a 3-column table (Store,
Kind, User), --kind filter, and --json output for agent
consumption. Adds a LocalStorage#entries() enumerator in
cli-kit and a listStoredStoreAppSessions() helper in @shopify/store
so the command can resolve sessions across every stored shop
without knowing the keys in advance.

Stacked on store-create-preview-command (#7558) → preview-store-session-discriminator (#7557).
---
 .changeset/store-list-command.md              |   9 ++
 .../src/public/node/local-storage.test.ts     |  24 ++++
 .../cli-kit/src/public/node/local-storage.ts  |  21 +++
 packages/cli/README.md                        |  32 +++++
 packages/cli/oclif.manifest.json              |  63 +++++++++
 packages/store/src/cli/commands/store/list.ts |  44 ++++++
 .../services/store/auth/session-store.test.ts | 125 ++++++++++++++++++
 .../cli/services/store/auth/session-store.ts  |  57 +++++++-
 .../src/cli/services/store/list/index.test.ts | 105 +++++++++++++++
 .../src/cli/services/store/list/index.ts      |  56 ++++++++
 .../cli/services/store/list/result.test.ts    |  83 ++++++++++++
 .../src/cli/services/store/list/result.ts     |  57 ++++++++
 packages/store/src/index.ts                   |   2 +
 13 files changed, 677 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/store-list-command.md
 create mode 100644 packages/store/src/cli/commands/store/list.ts
 create mode 100644 packages/store/src/cli/services/store/list/index.test.ts
 create mode 100644 packages/store/src/cli/services/store/list/index.ts
 create mode 100644 packages/store/src/cli/services/store/list/result.test.ts
 create mode 100644 packages/store/src/cli/services/store/list/result.ts

diff --git a/.changeset/store-list-command.md b/.changeset/store-list-command.md
new file mode 100644
index 00000000000..94ce763ad33
--- /dev/null
+++ b/.changeset/store-list-command.md
@@ -0,0 +1,9 @@
+---
+'@shopify/store': minor
+'@shopify/cli-kit': patch
+'@shopify/cli': minor
+---
+
+Add `shopify store list`, which prints every locally stored store-auth session — both standard PKCE-authenticated sessions (`shopify store auth`) and preview-store sessions (`shopify store create preview`) — as a table with `Store`, `Kind`, and `User` columns. Supports `--kind standard|preview` for filtering and `--json` for machine-readable output (intended for AI agent consumption alongside the M1 [Preview Store for AI Agent Surfaces](https://vault.shopify.io/gsd/proposals/60T12R) work).
+
+Internally adds a `LocalStorage#entries()` enumerator to `@shopify/cli-kit` and a `listStoredStoreAppSessions()` helper to `@shopify/store` so the new command can resolve sessions across every stored shop without knowing the keys in advance.
diff --git a/packages/cli-kit/src/public/node/local-storage.test.ts b/packages/cli-kit/src/public/node/local-storage.test.ts
index cc1ab842326..d12f2151078 100644
--- a/packages/cli-kit/src/public/node/local-storage.test.ts
+++ b/packages/cli-kit/src/public/node/local-storage.test.ts
@@ -62,6 +62,30 @@ describe('storage', () => {
       expect(got2).toEqual(undefined)
     })
   })
+
+  test('entries returns every stored key/value pair', async () => {
+    await inTemporaryDirectory((cwd) => {
+      const storage = new LocalStorage<TestSchema>({cwd})
+
+      storage.set('testValue', 'first')
+      storage.set('anotherKey' as keyof TestSchema, 'second' as TestSchema[keyof TestSchema])
+
+      const entries = storage.entries()
+
+      expect(entries).toHaveLength(2)
+      expect(Object.fromEntries(entries)).toEqual({
+        testValue: 'first',
+        anotherKey: 'second',
+      })
+    })
+  })
+
+  test('entries returns an empty array when nothing has been stored', async () => {
+    await inTemporaryDirectory((cwd) => {
+      const storage = new LocalStorage<TestSchema>({cwd})
+      expect(storage.entries()).toEqual([])
+    })
+  })
 })
 
 describe('error handling', () => {
diff --git a/packages/cli-kit/src/public/node/local-storage.ts b/packages/cli-kit/src/public/node/local-storage.ts
index 9759267aab9..aec9a58b5c0 100644
--- a/packages/cli-kit/src/public/node/local-storage.ts
+++ b/packages/cli-kit/src/public/node/local-storage.ts
@@ -66,6 +66,27 @@ export class LocalStorage<T extends Record<string, any>> {
     }
   }
 
+  /**
+   * Get every `[key, value]` pair currently held in the local storage.
+   *
+   * Useful for callers that need to enumerate all stored values without knowing the
+   * full set of keys in advance (for example, a `list` command iterating over every
+   * stored session). The `conf` package stores its entire state as a single JSON
+   * object, so this is just a typed wrapper around that object.
+   *
+   * @returns An array of `[key, value]` tuples.
+   * @throws AbortError if a permission error occurs.
+   * @throws BugError if an unexpected error occurs.
+   */
+  entries(): [keyof T, T[keyof T]][] {
+    try {
+      return Object.entries(this.config.store) as [keyof T, T[keyof T]][]
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch (error) {
+      this.handleError(error, 'entries')
+    }
+  }
+
   /**
    * Clear the local storage (delete all values).
    *
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 72159c47124..02c1f635d03 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -79,6 +79,7 @@
 * [`shopify store auth`](#shopify-store-auth)
 * [`shopify store create preview`](#shopify-store-create-preview)
 * [`shopify store execute`](#shopify-store-execute)
+* [`shopify store list`](#shopify-store-list)
 * [`shopify theme check`](#shopify-theme-check)
 * [`shopify theme console`](#shopify-theme-console)
 * [`shopify theme delete`](#shopify-theme-delete)
@@ -2224,6 +2225,37 @@ EXAMPLES
   $ shopify store execute --store shop.myshopify.com --query "query { shop { name } }" --json
 ```
 
+## `shopify store list`
+
+List stored store-auth sessions.
+
+```
+USAGE
+  $ shopify store list [-j] [--kind standard|preview] [--no-color] [--verbose]
+
+FLAGS
+  -j, --json           [env: SHOPIFY_FLAG_JSON] Output the result as JSON. Automatically disables color output.
+      --kind=<option>  [env: SHOPIFY_FLAG_STORE_LIST_KIND] Filter results to a single session kind.
+                       <options: standard|preview>
+      --no-color       [env: SHOPIFY_FLAG_NO_COLOR] Disable color output.
+      --verbose        [env: SHOPIFY_FLAG_VERBOSE] Increase the verbosity of the output.
+
+DESCRIPTION
+  List stored store-auth sessions.
+
+  Lists every store that has a locally stored auth session, including both standard PKCE-authenticated stores (via
+  `shopify store auth`) and preview stores (via `shopify store create preview`).
+
+  Use `--kind` to filter by session type, or `--json` to emit a machine-readable list for agent consumption.
+
+EXAMPLES
+  $ shopify store list
+
+  $ shopify store list --kind preview
+
+  $ shopify store list --json
+```
+
 ## `shopify theme check`
 
 Validate the theme.
diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json
index 6f15369d841..d32a1d8c776 100644
--- a/packages/cli/oclif.manifest.json
+++ b/packages/cli/oclif.manifest.json
@@ -5967,6 +5967,69 @@
       "strict": true,
       "summary": "Execute GraphQL queries and mutations on a store."
     },
+    "store:list": {
+      "aliases": [
+      ],
+      "args": {
+      },
+      "customPluginName": "@shopify/store",
+      "description": "Lists every store that has a locally stored auth session, including both standard PKCE-authenticated stores (via `shopify store auth`) and preview stores (via `shopify store create preview`).\n\nUse `--kind` to filter by session type, or `--json` to emit a machine-readable list for agent consumption.",
+      "descriptionWithMarkdown": "Lists every store that has a locally stored auth session, including both standard PKCE-authenticated stores (via `shopify store auth`) and preview stores (via `shopify store create preview`).\n\nUse `--kind` to filter by session type, or `--json` to emit a machine-readable list for agent consumption.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --kind preview",
+        "<%= config.bin %> <%= command.id %> --json"
+      ],
+      "flags": {
+        "json": {
+          "allowNo": false,
+          "char": "j",
+          "description": "Output the result as JSON. Automatically disables color output.",
+          "env": "SHOPIFY_FLAG_JSON",
+          "hidden": false,
+          "name": "json",
+          "type": "boolean"
+        },
+        "kind": {
+          "description": "Filter results to a single session kind.",
+          "env": "SHOPIFY_FLAG_STORE_LIST_KIND",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "name": "kind",
+          "options": [
+            "standard",
+            "preview"
+          ],
+          "required": false,
+          "type": "option"
+        },
+        "no-color": {
+          "allowNo": false,
+          "description": "Disable color output.",
+          "env": "SHOPIFY_FLAG_NO_COLOR",
+          "hidden": false,
+          "name": "no-color",
+          "type": "boolean"
+        },
+        "verbose": {
+          "allowNo": false,
+          "description": "Increase the verbosity of the output.",
+          "env": "SHOPIFY_FLAG_VERBOSE",
+          "hidden": false,
+          "name": "verbose",
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [
+      ],
+      "id": "store:list",
+      "pluginAlias": "@shopify/cli",
+      "pluginName": "@shopify/cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "List stored store-auth sessions."
+    },
     "theme:check": {
       "aliases": [
       ],
diff --git a/packages/store/src/cli/commands/store/list.ts b/packages/store/src/cli/commands/store/list.ts
new file mode 100644
index 00000000000..280f3b08f83
--- /dev/null
+++ b/packages/store/src/cli/commands/store/list.ts
@@ -0,0 +1,44 @@
+import {listStoredStores, type StoreListEntryKind} from '../../services/store/list/index.js'
+import {writeStoreListResult} from '../../services/store/list/result.js'
+import StoreCommand from '../../utilities/store-command.js'
+import {globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
+import {Flags} from '@oclif/core'
+
+const STORE_LIST_KINDS: StoreListEntryKind[] = ['standard', 'preview']
+
+export default class StoreList extends StoreCommand {
+  static summary = 'List stored store-auth sessions.'
+
+  static descriptionWithMarkdown = `Lists every store that has a locally stored auth session, including both standard PKCE-authenticated stores (via \`shopify store auth\`) and preview stores (via \`shopify store create preview\`).
+
+Use \`--kind\` to filter by session type, or \`--json\` to emit a machine-readable list for agent consumption.`
+
+  static description = this.descriptionWithoutMarkdown()
+
+  static examples = [
+    '<%= config.bin %> <%= command.id %>',
+    '<%= config.bin %> <%= command.id %> --kind preview',
+    '<%= config.bin %> <%= command.id %> --json',
+  ]
+
+  static flags = {
+    ...globalFlags,
+    ...jsonFlag,
+    kind: Flags.string({
+      description: 'Filter results to a single session kind.',
+      env: 'SHOPIFY_FLAG_STORE_LIST_KIND',
+      options: STORE_LIST_KINDS,
+      required: false,
+    }),
+  }
+
+  public async run(): Promise<void> {
+    const {flags} = await this.parse(StoreList)
+
+    const entries = listStoredStores({
+      kind: flags.kind as StoreListEntryKind | undefined,
+    })
+
+    writeStoreListResult(entries, flags.json ? 'json' : 'text')
+  }
+}
diff --git a/packages/store/src/cli/services/store/auth/session-store.test.ts b/packages/store/src/cli/services/store/auth/session-store.test.ts
index 7840b559407..577bf7c0d1f 100644
--- a/packages/store/src/cli/services/store/auth/session-store.test.ts
+++ b/packages/store/src/cli/services/store/auth/session-store.test.ts
@@ -3,6 +3,7 @@ import {
   clearStoredStoreAppSession,
   getCurrentStoredStoreAppSession,
   isPreviewStoreSession,
+  listStoredStoreAppSessions,
   sessionKind,
   setStoredStoreAppSession,
   type StoredStoreAppSession,
@@ -24,6 +25,9 @@ function inMemoryStorage() {
     delete(key: string) {
       values.delete(key)
     },
+    entries() {
+      return Array.from(values.entries()) as [string, unknown][]
+    },
   } as LocalStorage<Record<string, unknown>>
 }
 
@@ -340,3 +344,124 @@ describe('preview-store discriminator', () => {
     expect(getCurrentStoredStoreAppSession(standard.store, storage as any)).toEqual(preview)
   })
 })
+
+describe('listStoredStoreAppSessions', () => {
+  test('returns an empty array when no sessions are stored', () => {
+    expect(listStoredStoreAppSessions(inMemoryStorage() as any)).toEqual([])
+  })
+
+  test('returns the current session for every shop with a stored bucket', () => {
+    const storage = inMemoryStorage()
+    const first = buildSession({store: 'a.myshopify.com'})
+    const second = buildSession({store: 'b.myshopify.com', userId: '84'})
+    const preview = buildPreviewSession({store: 'c.myshopify.io'})
+
+    setStoredStoreAppSession(first, storage as any)
+    setStoredStoreAppSession(second, storage as any)
+    setStoredStoreAppSession(preview, storage as any)
+
+    const listed = listStoredStoreAppSessions(storage as any)
+    expect(listed).toHaveLength(3)
+    expect(listed.map((session) => session.store).sort()).toEqual([
+      'a.myshopify.com',
+      'b.myshopify.com',
+      'c.myshopify.io',
+    ])
+  })
+
+  test('returns only the bucket\u2019s current-user session, not every stored user', () => {
+    const storage = inMemoryStorage()
+    const firstUser = buildSession({userId: '42', accessToken: 'token-old'})
+    const secondUser = buildSession({userId: '84', accessToken: 'token-new'})
+
+    setStoredStoreAppSession(firstUser, storage as any)
+    setStoredStoreAppSession(secondUser, storage as any)
+
+    const listed = listStoredStoreAppSessions(storage as any)
+    expect(listed).toHaveLength(1)
+    expect(listed[0]!.userId).toBe('84')
+  })
+
+  test('skips buckets that belong to a different client id', () => {
+    const storage = inMemoryStorage()
+    setStoredStoreAppSession(buildSession(), storage as any)
+    storage.set('some-other-client::shop.myshopify.com', {
+      currentUserId: '42',
+      sessionsByUserId: {'42': buildSession({clientId: 'some-other-client'})},
+    })
+
+    const listed = listStoredStoreAppSessions(storage as any)
+    expect(listed).toHaveLength(1)
+    expect(listed[0]!.clientId).toBe(STORE_AUTH_APP_CLIENT_ID)
+  })
+
+  test('silently skips malformed buckets and sessions that fail sanitization', () => {
+    const storage = inMemoryStorage()
+    setStoredStoreAppSession(buildSession(), storage as any)
+
+    storage.set(storeAuthSessionKey('malformed-bucket.myshopify.com'), {
+      currentUserId: 42,
+      sessionsByUserId: null,
+    })
+    storage.set(storeAuthSessionKey('missing-current.myshopify.com'), {
+      currentUserId: '999',
+      sessionsByUserId: {'42': buildSession()},
+    })
+    storage.set(storeAuthSessionKey('malformed-session.myshopify.com'), {
+      currentUserId: '42',
+      sessionsByUserId: {'42': {userId: '42'}},
+    })
+
+    const listed = listStoredStoreAppSessions(storage as any)
+    expect(listed).toHaveLength(1)
+    expect(listed[0]!.store).toBe('shop.myshopify.com')
+  })
+
+  // The underlying `conf` library treats `.` in keys as a path separator, so a shop
+  // domain like `preview-1.my.shop.dev` is persisted as a nested object tree rather
+  // than a single top-level key. `entries()` therefore returns only the outermost
+  // segment, and listStoredStoreAppSessions has to walk down into the tree to find
+  // the bucket. The in-memory test storage doesn't reproduce that nesting, so we
+  // simulate it directly here.
+  test('finds buckets stored under a dotted shop domain (conf dot-notation expansion)', () => {
+    const storage = inMemoryStorage()
+    const dottedDomainSession = buildSession({store: 'preview-1.my.shop.dev', userId: '7'})
+    storage.set(`${STORE_AUTH_APP_CLIENT_ID}::preview-1`, {
+      my: {
+        shop: {
+          dev: {
+            currentUserId: '7',
+            sessionsByUserId: {'7': dottedDomainSession},
+          },
+        },
+      },
+    })
+
+    const listed = listStoredStoreAppSessions(storage as any)
+    expect(listed).toHaveLength(1)
+    expect(listed[0]!.store).toBe('preview-1.my.shop.dev')
+  })
+
+  test('finds buckets at multiple depths under the same top-level key', () => {
+    const storage = inMemoryStorage()
+    const shallow = buildSession({store: 'shop-a.myshopify.com', userId: '1'})
+    const deep = buildSession({store: 'shop-a.my.shop.dev', userId: '2'})
+
+    storage.set(`${STORE_AUTH_APP_CLIENT_ID}::shop-a`, {
+      myshopify: {
+        com: {currentUserId: '1', sessionsByUserId: {'1': shallow}},
+      },
+      my: {
+        shop: {
+          dev: {currentUserId: '2', sessionsByUserId: {'2': deep}},
+        },
+      },
+    })
+
+    const listed = listStoredStoreAppSessions(storage as any)
+    expect(listed.map((session) => session.store).sort()).toEqual([
+      'shop-a.my.shop.dev',
+      'shop-a.myshopify.com',
+    ])
+  })
+})
diff --git a/packages/store/src/cli/services/store/auth/session-store.ts b/packages/store/src/cli/services/store/auth/session-store.ts
index f3cddcba86a..df458ed8789 100644
--- a/packages/store/src/cli/services/store/auth/session-store.ts
+++ b/packages/store/src/cli/services/store/auth/session-store.ts
@@ -1,4 +1,4 @@
-import {storeAuthSessionKey} from './config.js'
+import {STORE_AUTH_APP_CLIENT_ID, storeAuthSessionKey} from './config.js'
 import {LocalStorage} from '@shopify/cli-kit/node/local-storage'
 
 /**
@@ -211,6 +211,61 @@ function readStoredStoreAppSessionBucket(
   }
 }
 
+/**
+ * Returns the current session for every shop that has one stored, across all known buckets.
+ *
+ * Mirrors {@link getCurrentStoredStoreAppSession}: only the bucket's `currentUserId`
+ * session is returned per shop, since that is the one the rest of the CLI acts on. The
+ * result order is unspecified — callers that need a stable order should sort.
+ *
+ * Buckets whose stored shape is malformed, or whose current session is missing or fails
+ * sanitization, are silently skipped (they are cleaned up the next time their shop is
+ * looked up by key via {@link getCurrentStoredStoreAppSession}).
+ *
+ * Implementation note: the underlying `conf` library treats `.` in keys as a path
+ * separator, so a key like `<clientId>::shop.myshopify.com` is persisted as a nested
+ * object `{ <clientId>::shop: { myshopify: { com: <bucket> } } }`. `get`/`set` round-
+ * trip through that nesting symmetrically, but the top-level enumerator only sees the
+ * outermost segment. To find every bucket regardless of how many dots the shop domain
+ * contains, this function walks the value tree under each prefix-matching top-level key
+ * and recognizes buckets by shape (`currentUserId` + `sessionsByUserId`).
+ */
+export function listStoredStoreAppSessions(
+  storage: LocalStorage<StoreSessionSchema> = storeSessionStorage(),
+): StoredStoreAppSession[] {
+  const sessions: StoredStoreAppSession[] = []
+  const keyPrefix = `${STORE_AUTH_APP_CLIENT_ID}::`
+
+  for (const [key, value] of storage.entries()) {
+    if (typeof key !== 'string' || !key.startsWith(keyPrefix)) continue
+    collectBucketsFromSubtree(value, sessions)
+  }
+
+  return sessions
+}
+
+function collectBucketsFromSubtree(value: unknown, sessions: StoredStoreAppSession[]): void {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return
+
+  const bucketCandidate = value as Partial<StoredStoreAppSessionBucket>
+  if (
+    typeof bucketCandidate.currentUserId === 'string' &&
+    bucketCandidate.sessionsByUserId &&
+    typeof bucketCandidate.sessionsByUserId === 'object' &&
+    !Array.isArray(bucketCandidate.sessionsByUserId)
+  ) {
+    const session = sanitizeStoredStoreAppSession(
+      bucketCandidate.sessionsByUserId[bucketCandidate.currentUserId],
+    )
+    if (session) sessions.push(session)
+    return
+  }
+
+  for (const child of Object.values(value as Record<string, unknown>)) {
+    collectBucketsFromSubtree(child, sessions)
+  }
+}
+
 export function getCurrentStoredStoreAppSession(
   store: string,
   storage: LocalStorage<StoreSessionSchema> = storeSessionStorage(),
diff --git a/packages/store/src/cli/services/store/list/index.test.ts b/packages/store/src/cli/services/store/list/index.test.ts
new file mode 100644
index 00000000000..f24765d0300
--- /dev/null
+++ b/packages/store/src/cli/services/store/list/index.test.ts
@@ -0,0 +1,105 @@
+import {listStoredStores} from './index.js'
+import {STORE_AUTH_APP_CLIENT_ID} from '../auth/config.js'
+import * as sessionStore from '../auth/session-store.js'
+import {type StoredStoreAppSession} from '../auth/session-store.js'
+import {describe, test, expect, vi, afterEach} from 'vitest'
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+function buildStandardSession(overrides: Partial<StoredStoreAppSession> = {}): StoredStoreAppSession {
+  return {
+    store: 'b-shop.myshopify.com',
+    clientId: STORE_AUTH_APP_CLIENT_ID,
+    userId: '42',
+    accessToken: 'token-standard',
+    scopes: ['read_products'],
+    acquiredAt: '2026-03-27T00:00:00.000Z',
+    associatedUser: {id: 42, email: 'merchant@example.com'},
+    ...overrides,
+  }
+}
+
+function buildPreviewSession(overrides: Partial<StoredStoreAppSession> = {}): StoredStoreAppSession {
+  return {
+    store: 'a-preview.myshopify.io',
+    clientId: STORE_AUTH_APP_CLIENT_ID,
+    userId: 'placeholder:aaaa',
+    accessToken: 'shpat_preview',
+    scopes: ['read_products', 'write_products'],
+    acquiredAt: '2026-03-27T00:00:00.000Z',
+    kind: 'preview',
+    preview: {
+      placeholderAccountUuid: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+      coreUrl: 'https://app.shop.dev',
+    },
+    ...overrides,
+  }
+}
+
+function mockStoredSessions(sessions: StoredStoreAppSession[]): void {
+  vi.spyOn(sessionStore, 'listStoredStoreAppSessions').mockReturnValue(sessions)
+}
+
+describe('listStoredStores', () => {
+  test('returns an empty array when no sessions are stored', () => {
+    mockStoredSessions([])
+    expect(listStoredStores()).toEqual([])
+  })
+
+  test('sorts entries alphabetically by store domain regardless of stored order', () => {
+    mockStoredSessions([buildStandardSession(), buildPreviewSession()])
+
+    const result = listStoredStores()
+    expect(result.map((entry) => entry.store)).toEqual([
+      'a-preview.myshopify.io',
+      'b-shop.myshopify.com',
+    ])
+  })
+
+  test('projects a standard session into a row with email when available', () => {
+    mockStoredSessions([buildStandardSession()])
+
+    expect(listStoredStores()).toEqual([
+      {
+        store: 'b-shop.myshopify.com',
+        kind: 'standard',
+        userId: '42',
+        email: 'merchant@example.com',
+      },
+    ])
+  })
+
+  test('omits email when the standard session has no associated user', () => {
+    mockStoredSessions([buildStandardSession({associatedUser: undefined})])
+    const [entry] = listStoredStores()
+    expect(entry).not.toHaveProperty('email')
+  })
+
+  test('surfaces preview metadata on preview rows', () => {
+    mockStoredSessions([buildPreviewSession()])
+
+    expect(listStoredStores()).toEqual([
+      {
+        store: 'a-preview.myshopify.io',
+        kind: 'preview',
+        userId: 'placeholder:aaaa',
+        placeholderAccountUuid: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+        coreUrl: 'https://app.shop.dev',
+      },
+    ])
+  })
+
+  test('filters by kind when requested', () => {
+    mockStoredSessions([buildStandardSession(), buildPreviewSession()])
+
+    expect(listStoredStores({kind: 'preview'}).map((entry) => entry.store)).toEqual([
+      'a-preview.myshopify.io',
+    ])
+    expect(listStoredStores({kind: 'standard'}).map((entry) => entry.store)).toEqual([
+      'b-shop.myshopify.com',
+    ])
+  })
+})
+
diff --git a/packages/store/src/cli/services/store/list/index.ts b/packages/store/src/cli/services/store/list/index.ts
new file mode 100644
index 00000000000..de434788795
--- /dev/null
+++ b/packages/store/src/cli/services/store/list/index.ts
@@ -0,0 +1,56 @@
+import {
+  isPreviewStoreSession,
+  listStoredStoreAppSessions,
+  sessionKind,
+  type StoredStoreAppSession,
+} from '../auth/session-store.js'
+
+export type StoreListEntryKind = 'standard' | 'preview'
+
+export interface StoreListEntry {
+  store: string
+  kind: StoreListEntryKind
+  userId: string
+  email?: string
+  placeholderAccountUuid?: string
+  coreUrl?: string
+}
+
+interface ListStoredStoresOptions {
+  /** Optional filter. When omitted, all sessions are returned. */
+  kind?: StoreListEntryKind
+}
+
+/**
+ * Enumerates every stored store-auth session and projects it into the row shape consumed
+ * by the `shopify store list` command's renderer.
+ *
+ * The session-store enumerator already strips malformed buckets and surfaces only each
+ * bucket's current-user session, so the shape returned here is a faithful 1:1 view of
+ * what other store commands would resolve when called with the same `--store` flag.
+ *
+ * Results are sorted alphabetically by store domain so the output is deterministic and
+ * easy to diff across runs.
+ */
+export function listStoredStores(options: ListStoredStoresOptions = {}): StoreListEntry[] {
+  const entries = listStoredStoreAppSessions().map(toListEntry)
+  const filtered = options.kind ? entries.filter((entry) => entry.kind === options.kind) : entries
+  return filtered.sort((a, b) => a.store.localeCompare(b.store))
+}
+
+function toListEntry(session: StoredStoreAppSession): StoreListEntry {
+  const kind = sessionKind(session)
+  const base: StoreListEntry = {
+    store: session.store,
+    kind,
+    userId: session.userId,
+    ...(session.associatedUser?.email ? {email: session.associatedUser.email} : {}),
+  }
+
+  if (isPreviewStoreSession(session)) {
+    base.placeholderAccountUuid = session.preview.placeholderAccountUuid
+    base.coreUrl = session.preview.coreUrl
+  }
+
+  return base
+}
diff --git a/packages/store/src/cli/services/store/list/result.test.ts b/packages/store/src/cli/services/store/list/result.test.ts
new file mode 100644
index 00000000000..ff05acf364c
--- /dev/null
+++ b/packages/store/src/cli/services/store/list/result.test.ts
@@ -0,0 +1,83 @@
+import {type StoreListEntry} from './index.js'
+import {writeStoreListResult} from './result.js'
+import {beforeEach, describe, expect, test} from 'vitest'
+import {mockAndCaptureOutput} from '@shopify/cli-kit/node/testing/output'
+
+const standardEntry: StoreListEntry = {
+  store: 'b-shop.myshopify.com',
+  kind: 'standard',
+  userId: '42',
+  email: 'merchant@example.com',
+}
+
+const previewEntry: StoreListEntry = {
+  store: 'a-preview.myshopify.io',
+  kind: 'preview',
+  userId: 'placeholder:aaaa',
+  placeholderAccountUuid: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+  coreUrl: 'https://app.shop.dev',
+}
+
+describe('writeStoreListResult', () => {
+  beforeEach(() => {
+    mockAndCaptureOutput().clear()
+  })
+
+  test('renders an empty-state message when no sessions are stored', () => {
+    const output = mockAndCaptureOutput()
+
+    writeStoreListResult([], 'text')
+
+    expect(output.info()).toContain('No stores authenticated.')
+    expect(output.info()).toContain('shopify store auth')
+    expect(output.info()).toContain('shopify store create preview')
+  })
+
+  test('renders a table row with the email for standard sessions', () => {
+    const output = mockAndCaptureOutput()
+
+    writeStoreListResult([standardEntry], 'text')
+
+    const rendered = output.info()
+    expect(rendered).toContain('b-shop.myshopify.com')
+    expect(rendered).toContain('standard')
+    expect(rendered).toContain('merchant@example.com')
+  })
+
+  test('renders a dash in the user column for preview sessions to avoid showing placeholder ids', () => {
+    const output = mockAndCaptureOutput()
+
+    writeStoreListResult([previewEntry], 'text')
+
+    const rendered = output.info()
+    expect(rendered).toContain('a-preview.myshopify.io')
+    expect(rendered).toContain('preview')
+    expect(rendered).toContain('\u2014')
+    expect(rendered).not.toContain('placeholder:aaaa')
+  })
+
+  test('includes a footer summary counting both kinds', () => {
+    const output = mockAndCaptureOutput()
+
+    writeStoreListResult([standardEntry, previewEntry], 'text')
+
+    expect(output.info()).toContain('2 stores (1 standard, 1 preview)')
+  })
+
+  test('uses the singular noun for a single-entry summary', () => {
+    const output = mockAndCaptureOutput()
+
+    writeStoreListResult([standardEntry], 'text')
+
+    expect(output.info()).toContain('1 store (1 standard, 0 preview)')
+  })
+
+  test('emits machine-readable JSON through the result channel when format is json', () => {
+    const output = mockAndCaptureOutput()
+
+    writeStoreListResult([standardEntry, previewEntry], 'json')
+
+    const parsed = JSON.parse(output.output())
+    expect(parsed).toEqual([standardEntry, previewEntry])
+  })
+})
diff --git a/packages/store/src/cli/services/store/list/result.ts b/packages/store/src/cli/services/store/list/result.ts
new file mode 100644
index 00000000000..7393292a3a3
--- /dev/null
+++ b/packages/store/src/cli/services/store/list/result.ts
@@ -0,0 +1,57 @@
+import {type StoreListEntry} from './index.js'
+import {outputInfo, outputResult} from '@shopify/cli-kit/node/output'
+import {renderTable} from '@shopify/cli-kit/node/ui'
+
+type StoreListOutputFormat = 'text' | 'json'
+
+const EMPTY_USER_PLACEHOLDER = '—'
+
+export function writeStoreListResult(entries: StoreListEntry[], format: StoreListOutputFormat): void {
+  if (format === 'json') {
+    outputResult(serializeAsJson(entries))
+    return
+  }
+  renderTextResult(entries)
+}
+
+function serializeAsJson(entries: StoreListEntry[]): string {
+  return JSON.stringify(entries, null, 2)
+}
+
+function renderTextResult(entries: StoreListEntry[]): void {
+  if (entries.length === 0) {
+    outputInfo(
+      [
+        'No stores authenticated.',
+        '',
+        'Run `shopify store auth --store <domain>` to authenticate against an existing store,',
+        'or `shopify store create preview` to mint a preview store.',
+      ].join('\n'),
+    )
+    return
+  }
+
+  renderTable({
+    rows: entries.map((entry) => ({
+      store: entry.store,
+      kind: entry.kind,
+      // Preview sessions are backed by a placeholder identity that has no human-meaningful
+      // email; rendering the synthetic value would be misleading, so the column is dashed out.
+      user: entry.kind === 'preview' ? EMPTY_USER_PLACEHOLDER : entry.email ?? entry.userId,
+    })),
+    columns: {
+      store: {header: 'Store'},
+      kind: {header: 'Kind'},
+      user: {header: 'User'},
+    },
+  })
+
+  outputInfo(`\n${summaryLine(entries)}`)
+}
+
+function summaryLine(entries: StoreListEntry[]): string {
+  const standardCount = entries.filter((entry) => entry.kind === 'standard').length
+  const previewCount = entries.filter((entry) => entry.kind === 'preview').length
+  const noun = entries.length === 1 ? 'store' : 'stores'
+  return `${entries.length} ${noun} (${standardCount} standard, ${previewCount} preview)`
+}
diff --git a/packages/store/src/index.ts b/packages/store/src/index.ts
index 2d571415986..cc15f60ae3e 100644
--- a/packages/store/src/index.ts
+++ b/packages/store/src/index.ts
@@ -1,11 +1,13 @@
 import StoreAuth from './cli/commands/store/auth.js'
 import StoreCreatePreview from './cli/commands/store/create/preview.js'
 import StoreExecute from './cli/commands/store/execute.js'
+import StoreList from './cli/commands/store/list.js'
 
 const COMMANDS = {
   'store:auth': StoreAuth,
   'store:create:preview': StoreCreatePreview,
   'store:execute': StoreExecute,
+  'store:list': StoreList,
 }
 
 export default COMMANDS