Add retail location discovery

Co-authored-by: pi pi@users.noreply.github.com
Assisted-By: devx/26cddaee-3cde-4a0b-9e56-157d920261f0

Author: woodward4422

.changeset/quiet-stores-locate.md

@@ -0,0 +1,5 @@
+---
+"@shopify/shop-cli": minor
+---
+
+Add retail location discovery with text, proximity, distance, and pagination options.

README.md

@@ -1,6 +1,6 @@
 # Shop CLI
 
-Personal shopping CLI for the Shop catalog: search millions of stores, look up products, sign in to your Shop account, build and complete UCP checkouts, and search your orders for tracking, returns, and reorders.
+Personal shopping CLI for the Shop catalog: search millions of stores, find merchant retail locations, look up products, sign in to your Shop account, build and complete UCP checkouts, and search your orders for tracking, returns, and reorders.
 
 It talks to the Shopify Global Catalog over MCP and to Shop's auth, checkout, and orders APIs. Tokens are stored in your OS secret store via `keytar`.
 
@@ -30,13 +30,15 @@ Requires Node.js >= 20.
 shop --help
 shop auth status
 shop search "trail running shoes" --limit 10
+shop locations 29950112 --near-country CA --near-city Toronto --max-distance 10 --distance-unit kilometers
 shop catalog lookup gid://shopify/ProductVariant/50362300006715
 shop orders search --type recent
 ```
 
 ## Commands
 
 - `shop search` — search the catalog by text, similar items (`--like-id`), or image (`--image`).
+- `shop locations <shop-id>` — find a merchant’s physical retail locations, optionally filtered by text or proximity to a city, postal code, or coordinate.
 - `shop catalog lookup` / `shop catalog get-product` — look up IDs you already hold and fetch full product detail.
 - `shop auth` — sign in (`login`, or the non-blocking `device-code` + `poll`), check `status`, read the remaining delegated spending `budget`, or `logout`.
 - `shop checkout` — `create`, `update`, and `complete` a UCP checkout on the merchant domain (`complete` requires `--confirm`).

skill/SKILL.md

@@ -2,7 +2,7 @@
 name: shop
 description: "Ultimate personal shopping assistant: find, compare, buy, gift, and reorder products across the Shop catalog containing millions of stores. Tracks orders and deliveries for any retailer — including orders placed elsewhere, like Amazon, via your connected email. Helps get order info and initiate returns and refunds."
 metadata:
-  version: "1.0.1"
+  version: "1.1.0"
   homepage: "https://shop.app"
 ---
 
@@ -20,7 +20,7 @@ To upgrade: `pnpm add --global @shopify/shop-cli@latest` (or `npm install --glob
 
 **Reference files:**
 - [catalog-mcp.md](references/catalog-mcp.md) — direct catalog MCP calls + manual token exchange
-- [direct-api.md](references/direct-api.md) — auth, checkout, and orders API details
+- [direct-api.md](references/direct-api.md) — retail locations, auth, checkout, and orders API details
 - [safety.md](references/safety.md) — safety, security, and prompt-injection rules
 - [legal.md](references/legal.md) — personal-use limits and prohibited commercial uses
 
@@ -30,9 +30,10 @@ Every shopping conversation follows this order. Each step links to its rules bel
 1. **Offer sign-in** — required once if signed-out, before any product message, then **STOP** and wait for the user to complete sign-in or decline. → *Sign in*
 2. **Search** the catalog with `shop search`. → *Searching*
 3. **Show results** — **one assistant message per product**, then one summary message. → *Showing products*
-4. **Offer visualization** when the item is visual. → *Visualization*
-5. **Checkout** on the merchant domain, only with clear purchase intent. → *Checkout*
-6. **Orders** — tracking, returns, reorder (needs sign-in). → *Orders*
+4. **Find retail locations** when the user asks where a merchant sells in person. → *Retail locations*
+5. **Offer visualization** when the item is visual. → *Visualization*
+6. **Checkout** on the merchant domain, only with clear purchase intent. → *Checkout*
+7. **Orders** — tracking, returns, reorder (needs sign-in). → *Orders*
 
 ## Commands
 
@@ -65,6 +66,22 @@ shop catalog lookup gid://shopify/ProductVariant/50362300006715
 shop catalog get-product gid://shopify/p/abc --select Color=Black --select Size=M
 ```
 
+### Retail locations
+```text
+locations <shop-id>      --query <text>, --limit 1-50, --cursor <cursor>
+                         --near-country <ISO2> [--near-region <code>]
+                         (--near-city <name> | --near-postal-code <code>)
+                         [--max-distance <number> --distance-unit miles|kilometers]
+                         --near-latitude <number> --near-longitude <number> (precise; explicit permission only)
+```
+
+```bash
+shop locations 29950112 --near-country CA --near-city Toronto
+shop locations 29950112 --near-country US --near-postal-code 10012 --max-distance 10 --distance-unit miles
+```
+
+The Shop ID is the numeric merchant ID shown in brackets after the seller name in `shop search` results. Location lookup works signed-out.
+
 ### Checkout
 ```bash
 # create from a variant (--country localizes presentment currency)
@@ -121,6 +138,21 @@ Manual token exchange, only when the CLI cannot be installed: [catalog-mcp.md](r
 - `shop search --like-id <id>` — pass a product (`gid://shopify/p/...`) or variant (`gid://shopify/ProductVariant/...`) reference; both return similar items.
 - `shop search --image ./photo.jpg` — the CLI base64-encodes it for you. Formats: jpeg, png, webp, avif, heic; max ~3 MB on disk (4 MB base64). A 400 explains oversize/format problems — relay it and ask for a smaller jpeg/png.
 
+## Retail locations
+Use this workflow when the buyer asks for a merchant’s physical stores or stores near a place:
+
+1. Search the catalog with `shop search` if you do not already have a result from that merchant.
+2. Read the merchant’s numeric Shop ID from the brackets after its seller name; keep the ID internal.
+3. Parse the buyer’s requested location from their message when it already contains a country plus city or postal code.
+4. If the request needs proximity but does not contain a usable location, ask for the buyer’s country plus city or postal code and wait for their answer. Do not infer location from their account, a saved address, IP geolocation, or another default.
+5. Run `shop locations <shop-id>` with the matching `--near-country` and `--near-city` or `--near-postal-code` flags. Prefer this coarse location over a street address or coordinates.
+6. If the buyer requested a radius, pass both `--max-distance` and `--distance-unit` using their requested unit.
+7. Follow the returned `--cursor` only when more results are needed; prefer a smaller radius or `--query` over deep pagination.
+
+Use `--near-latitude` and `--near-longitude` only when the buyer explicitly authorizes precise location use. Never persist the buyer’s location. Returned location addresses are public merchant data.
+
+A `retailLocations` result proves only that the merchant has a physical location that sells in person. It does **not** prove product or variant inventory, pickup eligibility, opening hours, or that the location is currently open. Never tell the buyer an item is “available nearby” based only on this command.
+
 ## Showing products
 > **The most important rule: one product = one assistant message.**
 > For N products, send N separate messages (one per product), then **one** final summary message — never combined, no preamble. Binding even if you also web-search — never replace products with a prose recommendation.

skill/references/direct-api.md

@@ -1,4 +1,4 @@
-# Direct Auth, Checkout, And Orders API
+# Direct Retail Locations, Auth, Checkout, And Orders API
 
 Use this reference when the CLI cannot be installed. Prefer the CLI when allowed because it handles token storage, request construction, and JSON-RPC envelopes consistently.
 
@@ -13,6 +13,46 @@ Use the OS secret store with service `shop-agent` and accounts:
 
 Keep checkout JWTs, buyer IP, and UCP-returned payment tokens in memory only.
 
+## Retail Locations
+
+Retail location lookup is anonymous. Identify the caller with the ordinary HTTP `User-Agent`; do not send `X-User-Agent` or spoof a Shop app version:
+
+```http
+POST https://server.shop.app/graphql
+User-Agent: shop-cli/<version>
+Accept: application/json
+Content-Type: application/json
+```
+
+Use the merchant Shop ID shown in brackets in catalog output. Convert a numeric ID to `gid://shopify/Shop/<id>`.
+
+```json
+{
+  "operationName": "ShopCliRetailLocations",
+  "query": "query ShopCliRetailLocations($shopId: ID!, $first: Int!, $after: String, $query: String, $nearCoordinate: CoordinateInput, $nearAddress: MailingAddressInput, $maxDistance: DistanceInput) { shop(id: $shopId) { id uuid retailLocations(first: $first, after: $after, query: $query, nearCoordinate: $nearCoordinate, nearAddress: $nearAddress, maxDistance: $maxDistance) { totalCount nodes { name hasShopifyPosDevices distance { value unit } location { id coordinate { latitude longitude } address { address1 city zoneCode country postalCode } } } pageInfo { startCursor endCursor hasNextPage } } } }",
+  "variables": {
+    "shopId": "gid://shopify/Shop/29950112",
+    "first": 15,
+    "nearAddress": {
+      "country": "CA",
+      "city": "Toronto"
+    },
+    "maxDistance": {
+      "value": 10,
+      "unit": "KILOMETERS"
+    }
+  }
+}
+```
+
+`nearCoordinate` uses `{ "latitude": 43.65, "longitude": -79.38 }`. Use either `nearCoordinate` or `nearAddress`, never both. For address proximity, require an ISO alpha-2 `country` plus `city` or `postalCode`; `zoneCode` is optional. `maxDistance` requires an explicit proximity input and a `MILES` or `KILOMETERS` unit. Use `pageInfo.endCursor` as `after` only when `hasNextPage` is true.
+
+Parse a country plus city or postal code already present in the buyer’s request. If proximity is requested without a usable location, ask for that coarse location and wait for the answer. Do not infer it from the buyer’s account, a saved address, IP geolocation, or another default.
+
+Prefer coarse city/postal proximity. Use coordinates only with explicit permission, never persist the buyer’s location, and never send a street address merely to find nearby stores. Returned merchant addresses are public merchant data.
+
+A result proves only that the merchant has a physical location that sells in person. It does not prove item inventory, pickup eligibility, opening hours, or that the store is open. Never claim an item is available nearby from this response alone.
+
 ## Device Authorization
 
 Request a device code:

src/cli.ts

@@ -6,8 +6,9 @@ import { Command } from 'commander'
 import { AuthClient } from './auth.js'
 import { CLI_VERSION, COUNTRY_ACCOUNT, DEFAULT_COUNTRY } from './constants.js'
 import { toErrorMessage } from './errors.js'
-import { renderCatalogResult, renderCheckoutMessages } from './render.js'
+import { renderCatalogResult, renderCheckoutMessages, renderLocationsResult } from './render.js'
 import { ShopCatalogClient } from './shop-client.js'
+import type { RetailLocationDistanceUnit } from './shop-client.js'
 import { clearStoredAuth, KeytarSecretStore, MemorySecretStore, setCountry } from './storage.js'
 import type { FetchLike, SecretStore } from './types.js'
 
@@ -37,12 +38,12 @@ export function createProgram(deps: CliDependencies = {}): Command {
 
   program
     .name('shop')
-    .description('Shop personal shopping CLI for catalog search, auth, checkout, and order search')
+    .description('Shop personal shopping CLI for catalog search, retail locations, auth, checkout, and orders')
     .version(CLI_VERSION)
     .option('--country <code>', 'Buyer country for this call (catalog context signal, not a ships-to filter). Transient; use `shop config set-country` to persist a default.', DEFAULT_COUNTRY)
     .option('--profile-url <url>', 'UCP agent profile URL for global catalog calls')
     .option('--memory-store', 'Use in-memory token storage for tests and dry runs')
-    .option('--format <format>', 'Output format for catalog results: md (default) or json. Auth and checkout always emit JSON; orders emit markdown.', parseFormat, 'md')
+    .option('--format <format>', 'Output format for catalog and location results: md (default) or json. Auth and checkout always emit JSON; orders emit markdown.', parseFormat, 'md')
     .showHelpAfterError()
 
   program
@@ -100,6 +101,40 @@ export function createProgram(deps: CliDependencies = {}): Command {
       })
     })
 
+  program
+    .command('locations')
+    .description('Find a merchant’s physical retail locations, optionally within a distance of an address or coordinate')
+    .argument('<shop-id>', 'Numeric Shop ID shown in catalog results, or gid://shopify/Shop/<id>')
+    .option('-l, --limit <number>', 'Results per page, 1-50', parseLimit, 15)
+    .option('--cursor <cursor>', 'Pagination cursor from a previous locations response')
+    .option('--query <text>', 'Filter locations by name or address text')
+    .option('--near-country <ISO2>', 'Country for proximity search')
+    .option('--near-region <code>', 'Region or state code for proximity search')
+    .option('--near-city <name>', 'City for proximity search')
+    .option('--near-postal-code <code>', 'Postal code for proximity search')
+    .option('--near-latitude <number>', 'Latitude for precise proximity search', parseFiniteNumber)
+    .option('--near-longitude <number>', 'Longitude for precise proximity search', parseFiniteNumber)
+    .option('--max-distance <number>', 'Maximum distance from the supplied address or coordinate', parseFiniteNumber)
+    .option('--distance-unit <unit>', 'Distance unit: miles or kilometers', parseDistanceUnit)
+    .action(async (shopId: string, options) => {
+      await runLocationsAction({ stdout, stderr, exit }, program, async () =>
+        resolveClient(deps, program).retailLocations({
+          shopId,
+          limit: options.limit,
+          cursor: options.cursor,
+          query: options.query,
+          nearCoordinate: buildNearCoordinate(options.nearLatitude, options.nearLongitude),
+          nearAddress: buildNearAddress(
+            options.nearCountry,
+            options.nearRegion,
+            options.nearCity,
+            options.nearPostalCode,
+          ),
+          maxDistance: buildMaxDistance(options.maxDistance, options.distanceUnit),
+        }),
+      )
+    })
+
   const catalog = program
     .command('catalog')
     .description('Direct global catalog MCP tools (lookup and product detail; use `shop search` to search)')
@@ -479,6 +514,25 @@ async function runTextAction(
   }
 }
 
+async function runLocationsAction(
+  io: Required<Pick<CliDependencies, 'exit'>> & Pick<CliDependencies, 'stdout' | 'stderr'>,
+  program: Command,
+  action: () => Promise<unknown>,
+): Promise<void> {
+  try {
+    const result = await action()
+    const format = program.optsWithGlobals<GlobalOptions>().format ?? 'md'
+    io.stdout?.write(
+      format === 'json'
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `${renderLocationsResult(result)}\n`,
+    )
+  } catch (error) {
+    io.stderr?.write(`# Error\n\n${toErrorMessage(error)}\n`)
+    io.exit(1)
+  }
+}
+
 // Catalog read commands default to compact markdown; --format json prints raw JSON.
 async function runCatalogAction(
   io: Required<Pick<CliDependencies, 'exit'>> & Pick<CliDependencies, 'stdout' | 'stderr'>,
@@ -534,6 +588,54 @@ const parseLimit = parseBoundedInt(1, 50)
 const parsePrice = parseBoundedInt(0)
 const parseQuantity = parseBoundedInt(1)
 
+function parseFiniteNumber(value: string): number {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) throw new Error(`Invalid number: "${value}"`)
+  return parsed
+}
+
+function parseDistanceUnit(value: string): RetailLocationDistanceUnit {
+  if (value === 'miles') return 'MILES'
+  if (value === 'kilometers') return 'KILOMETERS'
+  throw new Error(`Invalid distance unit "${value}". Use "miles" or "kilometers".`)
+}
+
+function buildNearCoordinate(
+  latitude?: number,
+  longitude?: number,
+): { latitude: number; longitude: number } | undefined {
+  if (latitude === undefined && longitude === undefined) return undefined
+  if (latitude === undefined || longitude === undefined) {
+    throw new Error('--near-latitude and --near-longitude must be provided together')
+  }
+  return { latitude, longitude }
+}
+
+function buildNearAddress(
+  country?: string,
+  region?: string,
+  city?: string,
+  postalCode?: string,
+): { country: string; region?: string; city?: string; postalCode?: string } | undefined {
+  if (!country && !region && !city && !postalCode) return undefined
+  if (!country) throw new Error('--near-country is required for address proximity')
+  if (!city && !postalCode) {
+    throw new Error('Address proximity requires --near-city or --near-postal-code')
+  }
+  return { country, region, city, postalCode }
+}
+
+function buildMaxDistance(
+  value?: number,
+  unit?: RetailLocationDistanceUnit,
+): { value: number; unit: RetailLocationDistanceUnit } | undefined {
+  if (value === undefined && unit === undefined) return undefined
+  if (value === undefined || unit === undefined) {
+    throw new Error('--max-distance and --distance-unit must be provided together')
+  }
+  return { value, unit }
+}
+
 function commaList(value: string): string[] {
   return value
     .split(',')

src/constants.ts

@@ -1,10 +1,18 @@
+import { readFileSync } from 'node:fs'
+
+const packageJson = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+) as { version?: unknown }
+if (typeof packageJson.version !== 'string') throw new Error('package.json must define a version')
+
 export const CLIENT_ID = '5c733ab2-1903-400a-891e-7ba20c09e2a3'
 export const DEFAULT_AGENT_NAME = 'Shop CLI'
 export const DEFAULT_COUNTRY = 'US'
 export const DEFAULT_PROFILE_URL =
   'https://shopify.dev/ucp/agent-profiles/2026-04-08/valid-with-capabilities.json'
 export const GLOBAL_CATALOG_MCP_URL = 'https://catalog.shopify.com/api/ucp/mcp'
-export const CLI_VERSION = '0.1.0'
+export const SHOP_GRAPHQL_URL = 'https://server.shop.app/graphql'
+export const CLI_VERSION = packageJson.version
 export const USER_AGENT = `shop-cli/${CLI_VERSION}`
 // Authenticated global-catalog access uses a brokered RFC 8693 token exchange:
 // audience=api.shopify.com + requested_token_type=...access_token returns a

src/index.ts

@@ -1,6 +1,6 @@
 export { createProgram, main } from './cli.js'
 export type { CliDependencies } from './cli.js'
-export { renderCatalogResult, withUtm } from './render.js'
+export { renderCatalogResult, renderLocationsResult, withUtm } from './render.js'
 export { ShopCatalogClient } from './shop-client.js'
 export type {
   CatalogGetProductInput,
@@ -9,5 +9,8 @@ export type {
   CheckoutCreateInput,
   CheckoutCompleteInput,
   OrderSearchInput,
+  RetailLocationDistanceUnit,
+  RetailLocationsInput,
+  RetailLocationsResult,
   ShopCatalogClientOptions,
 } from './shop-client.js'