CLI Reference

The Shoppex CLI (@shoppexio/cli, command shoppex) is the terminal companion for Liquid theme development. It pulls a hosted theme into a local folder, runs a local Liquid dev server, pushes your draft source back to Shoppex, and drives validation, preview, and publish from the command line. It also installs the Shoppex MCP server into AI clients such as Claude Desktop, Claude Code, Cursor, Windsurf, and Codex.

Installation

Run it directly with npx:

npx @shoppexio/cli theme list

Or install it globally:

npm install -g @shoppexio/cli
shoppex theme list

Requirements

Node.js >= 18 for all commands.
Every command — including theme dev and theme screenshot — runs on Node alone when installed from npm. (Bun is only needed when running the dev server from a Shoppex monorepo checkout.)
Playwright is required for theme screenshot (optional peer dependency, not part of the default install): npm install -D playwright && npx playwright install chromium.

Authentication

Create an API key in the Dashboard under Settings → Developer → API Keys (“Theme Development” section) with the themes.read and themes.write scopes, then log in:

shoppex auth login
# browser device login: prints a short code, opens the dashboard approval
# page, and waits — approving mints a Theme-Development API key for the CLI.

shoppex auth login --manual            # masked key prompt instead
shoppex auth login --api-key shx_...   # explicit key
shoppex auth whoami

Instead of a stored login you can set environment variables:

Variable	Purpose
`SHOPPEX_API_KEY`	API key used when no stored login exists
`SHOPPEX_API_URL`	Override the API base URL

shoppex auth logout removes the stored credentials.

Command Reference

Auth

Command	Description
`shoppex auth login --api-key <key> [--api-url <url>]`	Store an API key for CLI use
`shoppex auth whoami`	Show the authenticated identity
`shoppex auth logout`	Remove stored credentials

MCP

Installs the Shoppex MCP server into an AI client so assistants can work on your themes.

Command	Description
`shoppex mcp install [--client <claude-desktop\|claude-code\|cursor\|windsurf\|codex>] [--api-key <key>] [--api-url <url>]`	Install the Shoppex MCP server into an AI client
`shoppex mcp uninstall [--client <...>]`	Remove the MCP server from a client
`shoppex mcp status [--client <...>]`	Show the MCP install state per client

On Windows, shoppex mcp install --client claude-desktop writes the config to every known Claude Desktop location, including the Microsoft Store install path. Quit and reopen Claude Desktop after installing.

Theme: local workflow

Command	Description
`shoppex theme list`	List the themes of your shop
`shoppex theme init --base <default\|classic\|nebula\|pulse> --out <dir> [--name <name>]`	One-step scaffold: create a theme from an official base on the server, then clone and link it into `--out` (must be empty or non-existent). If the clone fails after the create, the CLI prints the new theme id so you can finish with `shoppex theme clone --theme <id>`
`shoppex theme clone [--theme <themeId>] --out <dir> [--force]`	Clone a hosted theme into a new local folder
`shoppex theme pull [--theme <themeId>] [--out <dir>\|--dir <dir>] [--force]`	Download the hosted theme source; writes `.shoppex/theme.json` with the linked theme id and source revision
`shoppex theme open [<themeId>] [--editor\|--preview]`	Open a theme in the Dashboard editor or preview
`shoppex theme open [<themeId>] --client <cursor\|claude-code\|claude-desktop\|windsurf\|codex> [--out <dir>] [--api-key <key>] [--no-dev]`	Clone a theme and open it in an AI coding client
`shoppex theme status [--theme <themeId>] [--dir <dir>]`	Compare the linked local revision, local files, and remote source revision
`shoppex theme doctor [--theme <themeId>] [--dir <dir>] [--include-typecheck] [--no-preview] [--no-validate]`	Check auth, workspace link, remote source access, inspect, validation, and preview startup
`shoppex theme dev [--theme <themeId>] [--dir <dir>] [--shop-slug <slug>] [--port <port>] [--host <host>] [--no-msw]`	Start the local Liquid dev server (requires a Liquid `theme-package.json`); safely pushes idle source changes in the background
`shoppex theme screenshot [--theme <themeId>] [--dir <dir>] [--routes <csv>] [--out <dir>] [--viewport 1440x900]`	Capture visual checkpoints of local routes into `.shoppex-screenshots/` (uses Playwright Chromium)
`shoppex theme push [--theme <themeId>] [--dir <dir>] [--force] [--preview] [--include-typecheck]`	Upload the full local source snapshot; validates automatically, never publishes automatically

Theme: inspect and edit

Command	Description
`shoppex theme inspect --theme <themeId>`	Inspect the remote theme structure
`shoppex theme diff --theme <themeId>`	Diff local files against the remote draft source
`shoppex theme read-file --theme <themeId> --path <file>`	Read a single remote theme file
`shoppex theme search --theme <themeId> --query <text> [--limit <n>]`	Search remote theme source
`shoppex theme apply --theme <themeId> --file <changes.json>`	Apply a batch of file changes to the remote draft
`shoppex theme accept --theme <themeId> --run <runId> --message <assistantMessageId> [--variant <variantId>]`	Accept an AI builder run result
`shoppex theme create --base <default\|classic\|nebula\|pulse> [--name <name>] [--set-active]`	Create a new theme from an official base theme
`shoppex theme update-config --theme <themeId> --group <group> --key <key> --file <setting.json>`	Update a single theme config setting
`shoppex theme settings get --theme <themeId>`	Read theme settings
`shoppex theme settings update --theme <themeId> --file <settings.json>`	Replace theme settings from a JSON file

Theme: preview, publish, and recovery

Command	Description
`shoppex theme preview --theme <themeId>`	Start a hosted preview session
`shoppex theme stop-preview --theme <themeId> --session <sessionId>`	Stop a hosted preview session
`shoppex theme validate --theme <themeId> [--include-typecheck]`	Validate the remote draft source
`shoppex theme publish --theme <themeId> [--build-only]`	Build and activate the theme on the live storefront; `--build-only` builds and uploads an artifact without changing the active storefront
`shoppex theme deploy --theme <themeId> [--build-only]`	Alias workflow for building and deploying the theme
`shoppex theme purge-cache --theme <themeId> [--force]`	Purge the storefront edge cache for the theme
`shoppex theme publish-status --theme <themeId> --job <jobId>`	Check the status of a publish job
`shoppex theme logs --theme <themeId> [--job <jobId>] [--follow]`	Stream job/run status as human-readable lines. With `--job` it follows a publish job; without `--job` it shows the latest AI builder run. This is an incremental status stream (the API exposes status snapshots, not full build logs): `--follow` polls every 3s, prints only new status changes, and exits `0` on `COMPLETED` or `1` on `FAILED`
`shoppex theme backups --theme <themeId>`	List theme backups
`shoppex theme rollback --theme <themeId> --backup <backupId>`	Roll the theme back to a backup
`shoppex theme latest-run --theme <themeId>`	Show the latest AI builder run for the theme

Most theme commands resolve the theme id from the local .shoppex/theme.json link when --theme is omitted. Outside a linked workspace, --theme is required.

Core Workflows

Start a brand-new theme in one step (create + clone + link):

shoppex theme init --base default --out ./my-theme --name "My Theme"
cd ./my-theme
shoppex theme dev                 # local Liquid preview
shoppex theme push --preview      # upload + validate + hosted preview

Follow a publish job as a status stream:

shoppex theme publish --theme 11111111-1111-4111-8111-111111111111
shoppex theme logs --theme 11111111-1111-4111-8111-111111111111 --job <jobId> --follow

Clone, develop locally, preview, publish:

shoppex auth login --api-key shx_your_key
shoppex theme clone --theme 11111111-1111-4111-8111-111111111111 --out ./my-theme
cd ./my-theme
shoppex theme dev                 # local Liquid preview
shoppex theme push --preview      # upload + validate + hosted preview
shoppex theme publish             # activate on the live storefront

Health-check a workspace:

shoppex theme doctor

Capture visual evidence after edits, before pushing:

shoppex theme screenshot --routes /home,/product/specter-license,/cart,/checkout

Use live shop data instead of fixtures in the dev server:

shoppex theme dev --shop-slug my-shop --no-msw

Exit Codes

Code	Meaning
`0`	Success
`1`	Error
`2`	Conflict halted — `theme dev` / `theme open` stop when the remote theme changed since your last pull, instead of overwriting it

Troubleshooting

401 Unauthorized

The stored API key is missing, expired, or revoked. Re-run shoppex auth login --api-key <key> with a valid key that has the themes.read and themes.write scopes, or check that SHOPPEX_API_KEY is set correctly.

409 revision conflict on push

Someone changed the remote draft after your last pull. Check with the merchant (or your team) what changed, then refresh your workspace with shoppex theme pull --force. Only use shoppex theme push --force when you intentionally want to replace the newer remote draft.

Liquid dev server unavailable

Reinstall @shoppexio/cli so the bundled dev server files are present. When running from a Shoppex monorepo checkout (not an npm install), the dev server runs via bun run dev:liquid — install Bun from bun.sh in that case.

Theme package is too large to push

Merchant themes may not exceed 10MB of custom (non-official) files uncompressed; unchanged official theme assets do not count toward the cap. The CLI warns before upload and the push error lists the largest files. Convert large PNG/JPG images under assets/ to WebP, remove unused images and authoring files from the theme folder, then re-run shoppex theme push --preview.

Start Here

Workflow & Runtime

Build & Deploy

Troubleshooting

CLI Reference

CLI Reference

Installation

Requirements

Authentication

Command Reference

Auth

MCP

Theme: local workflow

Theme: inspect and edit

Theme: preview, publish, and recovery

Core Workflows

Exit Codes

Troubleshooting

Next Steps

Local Development

Edit Themes with AI

​CLI Reference

​Installation

​Requirements

​Authentication

​Command Reference

​Auth

​MCP

​Theme: local workflow

​Theme: inspect and edit

​Theme: preview, publish, and recovery

​Core Workflows

​Exit Codes

​Troubleshooting

​Next Steps

Local Development

Edit Themes with AI

CLI Reference

Installation

Requirements

Authentication

Command Reference

Auth

MCP

Theme: local workflow

Theme: inspect and edit

Theme: preview, publish, and recovery

Core Workflows

Exit Codes

Troubleshooting

Next Steps