Run GraphQL against any Shopify store from your terminal

Sometimes the job is tiny: check one metafield across a product catalogue, inspect a configuration value, or add a tag to a known resource. The slow part is often everything around the GraphQL. Creating a custom app, choosing scopes, copying a token, and assembling a one-off request can take longer than the question itself.

Shopify CLI gives you a shorter route. shopify store auth authenticates against a store you can access, and shopify store execute runs Admin API GraphQL from the same terminal where you are already working.

Authenticate once

Start by requesting only the scopes the operation needs. The command opens a browser so you can approve access using your existing Shopify identity.

# Authenticate against the store with the minimum scope
shopify store auth \
  --store my-shop.myshopify.com \
  --scopes read_products

The CLI stores an online access token for later store commands. There is no custom app to scaffold and no token to paste into a temporary curl command.

Run a read directly

Here is the catalogue check from the opening example. It returns each product and the value of its custom.spec_sheet metafield.

shopify store execute \
  --store my-shop.myshopify.com \
  --query 'query ProductSpecSheets {
    products(first: 50) {
      nodes {
        id
        title
        metafield(namespace: "custom", key: "spec_sheet") {
          value
        }
      }
    }
  }'

That is the complete loop. Change the query, run it again, and keep the result beside the code or investigation that needed it.

Write data carefully

Reads are the default. Mutations require two deliberate choices: authenticate with an appropriate write scope, then add --allow-mutations to the execution command.

shopify store auth \
  --store my-shop.myshopify.com \
  --scopes write_products

shopify store execute \
  --store my-shop.myshopify.com \
  --allow-mutations \
  --query 'mutation AddClearanceTag {
    tagsAdd(
      id: "gid://shopify/Product/123"
      tags: ["clearance"]
    ) {
      node {
        id
      }
      userErrors {
        field
        message
      }
    }
  }'

The second gate matters. A write-capable token alone is not enough for store execute to run a mutation. The command has to opt in as well.

Always request userErrors from mutations. Shopify can reject an individual write inside a successful GraphQL response, so checking only whether the command ran is not enough.

Make the output useful

The command works well in scripts and agent workflows:

• --json returns machine-readable output.
• --output-file writes the response to disk.
• --query-file keeps larger operations in a GraphQL file.
• --variables and --variable-file keep values separate from the operation.
• --version pins the Admin API version when reproducibility matters.

There is also shopify store info --store my-shop.myshopify.com, which surfaces metadata such as the plan, organization, owner, store type, and admin URL. Add --json when another tool needs to consume it.

How I use it with pi

I rarely need to type the full operation myself. I describe the store question in plain English, pi writes and validates the GraphQL, authenticates with the narrowest required scopes, runs store execute, and reads the result back.

That turns jobs I would otherwise click through one screen at a time into a short, reviewable terminal workflow. The useful part is not only speed. The query becomes an exact record of what was inspected or changed.

Try it

shopify store execute --help
shopify store auth --help
shopify store info --help
shopify help store

If a store command is not recognised, update Shopify CLI with shopify upgrade.

For the full command reference, read Shopify’s documentation for shopify store execute and shopify store auth.