shopify-gql-cli

CLI tool for the Shopify Admin GraphQL API. Provides structured commands for common operations (orders, products, customers, inventory) plus a raw GraphQL escape hatch and an interactive REPL.

Installation

pip install git+https://github.com/hatlabs/shopify-gql-cli.git

Configuration

Set two environment variables:

export SHOPIFY_STORE_URL="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="shpat_..."

Or pass them as CLI flags: --store and --token.

Usage

JSON mode

Add --json before any subcommand to get machine-readable JSON output:

shopify-gql-cli --json shop info

Shop

shopify-gql-cli shop info
shopify-gql-cli shop locations

Orders

shopify-gql-cli orders list --first 20
shopify-gql-cli orders list --query "financial_status:paid"
shopify-gql-cli orders get 12345
shopify-gql-cli orders cancel 12345 --reason CUSTOMER
shopify-gql-cli orders close 12345

Orders default to status:any (all orders). Pass an explicit status: filter to restrict (e.g. status:open).

Products

shopify-gql-cli products list --query "title:Widget*"
shopify-gql-cli products get 12345
shopify-gql-cli products create "New Product" --type "Hardware" --status DRAFT
shopify-gql-cli products update 12345 --title "Updated Title"
shopify-gql-cli products delete 12345

Customers

shopify-gql-cli customers list --first 20
shopify-gql-cli customers get 12345

Inventory

shopify-gql-cli inventory levels --query "sku:WIDGET-001"
shopify-gql-cli inventory levels --item-id 123
shopify-gql-cli inventory adjust --item-id 123 --location-id 456 --delta 5
shopify-gql-cli inventory set --item-id 123 --location-id 456 --quantity 10

Raw GraphQL

shopify-gql-cli graphql execute '{ shop { name currencyCode } }'
shopify-gql-cli graphql execute \
  'query($id: ID!) { product(id: $id) { title } }' \
  -v '{"id": "gid://shopify/Product/12345"}'

Interactive REPL

Run without a subcommand to enter the REPL:

shopify-gql-cli

The REPL supports command history, auto-suggest, and all the same commands as the CLI.

Running as a module

python -m shopify_gql_cli --json shop info

ID handling

All commands accept both plain numeric IDs (12345) and full Shopify GIDs (gid://shopify/Product/12345).

Pagination

List commands support --first N (1–250) and --after CURSOR for pagination. When more results are available, the cursor is shown in the output.

Rate limiting

The client automatically retries once on HTTP 429 responses, respecting the Retry-After header.

Acknowledgements

This project was initially generated by CLI-Anything (MIT), a tool that auto-generates structured CLI harnesses from software APIs. The generated scaffolding, REPL interface, and test suite provided the foundation for this tool.

License

MIT