Ecommerce orders, products, customers, inventory, fulfillment orders, and bulk operations via the Shopify Admin GraphQL API.
Learn more at Shopify.
Created by @cathrynlavery (Cathryn Lavery).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
This CLI talks to the Shopify GraphQL API at https://{shop}/admin/api/{api_version}/graphql.json.
Set the endpoint variables for the tenant, workspace, or API version you want this CLI to use:
export SHOPIFY_SHOP="<your-store>.myshopify.com"
export SHOPIFY_API_VERSION="2026-04"
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export SHOPIFY_ACCESS_TOKEN="<paste-your-key>"
You can also persist this in your config file at ~/.config/shopify-pp-cli/config.toml.
3. Verify Setup
shopify-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
shopify-pp-cli abandoned-checkouts list
Usage
Run shopify-pp-cli --help for the full command reference and flag list.
Commands
abandoned-checkouts
Shopify abandoned checkouts for recovery campaigns and lost-cart analysis.
shopify-pp-cli abandoned-checkouts get - Get one Shopify abandoned checkout by GraphQL ID.shopify-pp-cli abandoned-checkouts list - List abandoned checkouts from the Shopify Admin GraphQL API.
customers
Shopify customers with lifetime order count, lifetime spend, and contact fields.
shopify-pp-cli customers get - Get one Shopify customer by GraphQL ID.shopify-pp-cli customers list - List customers from the Shopify Admin GraphQL API.
fulfillment-orders
Shopify fulfillment orders for lag, routing, and fulfillment-state analysis.
shopify-pp-cli fulfillment-orders get - Get one Shopify fulfillment order by GraphQL ID.shopify-pp-cli fulfillment-orders list - List fulfillment orders from the Shopify Admin GraphQL API.
inventory-items
Shopify inventory items with tracked status and available quantities by location.
shopify-pp-cli inventory-items get - Get one Shopify inventory item by GraphQL ID.shopify-pp-cli inventory-items list - List inventory items from the Shopify Admin GraphQL API.
orders
Shopify orders with money totals, financial state, and fulfillment state.
shopify-pp-cli orders get - Get one Shopify order by GraphQL ID.shopify-pp-cli orders list - List orders from the Shopify Admin GraphQL API.
products
Shopify products with product status, catalog metadata, and a compact variant inventory projection.
shopify-pp-cli products get - Get one Shopify product by GraphQL ID.shopify-pp-cli products list - List products from the Shopify Admin GraphQL API.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
shopify-pp-cli abandoned-checkouts list
# JSON for scripting and agents
shopify-pp-cli abandoned-checkouts list --json
# Filter to specific fields
shopify-pp-cli abandoned-checkouts list --json --select id,name,status
# Dry run — show the request without sending
shopify-pp-cli abandoned-checkouts list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
shopify-pp-cli abandoned-checkouts list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Freshness
This CLI owns bounded freshness for registered store-backed read command paths. In --data-source auto mode, covered commands check the local SQLite store before serving results; stale or missing resources trigger a bounded refresh, and refresh failures fall back to the existing local data with a warning. --data-source local never refreshes, and --data-source live reads the API without mutating the local store.
Set SHOPIFY_NO_AUTO_REFRESH=1 to disable the pre-read freshness hook while preserving the selected data source.
Covered command paths:
shopify-pp-cli abandoned-checkoutsshopify-pp-cli abandoned-checkouts getshopify-pp-cli abandoned-checkouts listshopify-pp-cli abandoned-checkouts searchshopify-pp-cli customersshopify-pp-cli customers getshopify-pp-cli customers listshopify-pp-cli customers searchshopify-pp-cli fulfillment-ordersshopify-pp-cli fulfillment-orders getshopify-pp-cli fulfillment-orders listshopify-pp-cli fulfillment-orders searchshopify-pp-cli inventory-itemsshopify-pp-cli inventory-items getshopify-pp-cli inventory-items listshopify-pp-cli inventory-items searchshopify-pp-cli ordersshopify-pp-cli orders getshopify-pp-cli orders listshopify-pp-cli orders searchshopify-pp-cli productsshopify-pp-cli products getshopify-pp-cli products listshopify-pp-cli products search
JSON outputs that use the generated provenance envelope include freshness metadata at meta.freshness. This metadata describes the freshness decision for the covered command path; it does not claim full historical backfill or API-specific enrichment.
Runtime Endpoint
This CLI resolves endpoint placeholders at runtime, so one installed binary can target different tenants or API versions without regeneration.
Endpoint environment variables:
SHOPIFY_SHOP resolves {shop}SHOPIFY_API_VERSION resolves {api_version}
Base URL: https://{shop}
GraphQL path: /admin/api/{api_version}/graphql.json
Health Check
shopify-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/shopify-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
SHOPIFY_SHOP | endpoint | Yes | |
SHOPIFY_API_VERSION | endpoint | Yes | |
SHOPIFY_ACCESS_TOKEN | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
shopify-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $SHOPIFY_ACCESS_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press