> ## Documentation Index > Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Full command reference for the Shoppex Theme CLI (@shoppexio/cli) — auth, MCP setup, and theme development workflows. # 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`: ```bash theme={"system"} npx @shoppexio/cli theme list ``` Or install it globally: ```bash theme={"system"} 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: ```bash theme={"system"} 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 [--api-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 ] [--api-key ] [--api-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 --out [--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 ` | | `shoppex theme clone [--theme ] --out [--force]` | Clone a hosted theme into a new local folder | | `shoppex theme pull [--theme ] [--out \|--dir ] [--force]` | Download the hosted theme source; writes `.shoppex/theme.json` with the linked theme id and source revision | | `shoppex theme open [] [--editor\|--preview]` | Open a theme in the Dashboard editor or preview | | `shoppex theme open [] --client [--out ] [--api-key ] [--no-dev]` | Clone a theme and open it in an AI coding client | | `shoppex theme status [--theme ] [--dir ]` | Compare the linked local revision, local files, and remote source revision | | `shoppex theme doctor [--theme ] [--dir ] [--include-typecheck] [--no-preview] [--no-validate]` | Check auth, workspace link, remote source access, inspect, validation, and preview startup | | `shoppex theme dev [--theme ] [--dir ] [--shop-slug ] [--port ] [--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 ] [--dir ] [--routes ] [--out ] [--viewport 1440x900]` | Capture visual checkpoints of local routes into `.shoppex-screenshots/` (uses Playwright Chromium) | | `shoppex theme push [--theme ] [--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 ` | Inspect the remote theme structure | | `shoppex theme diff --theme ` | Diff local files against the remote draft source | | `shoppex theme read-file --theme --path ` | Read a single remote theme file | | `shoppex theme search --theme --query [--limit ]` | Search remote theme source | | `shoppex theme apply --theme --file ` | Apply a batch of file changes to the remote draft | | `shoppex theme accept --theme --run --message [--variant ]` | Accept an AI builder run result | | `shoppex theme create --base [--name ] [--set-active]` | Create a new theme from an official base theme | | `shoppex theme update-config --theme --group --key --file ` | Update a single theme config setting | | `shoppex theme settings get --theme ` | Read theme settings | | `shoppex theme settings update --theme --file ` | Replace theme settings from a JSON file | ### Theme: preview, publish, and recovery | Command | Description | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `shoppex theme preview --theme ` | Start a hosted preview session | | `shoppex theme stop-preview --theme --session ` | Stop a hosted preview session | | `shoppex theme validate --theme [--include-typecheck]` | Validate the remote draft source | | `shoppex theme publish --theme [--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 [--build-only]` | Alias workflow for building and deploying the theme | | `shoppex theme purge-cache --theme [--force]` | Purge the storefront edge cache for the theme | | `shoppex theme publish-status --theme --job ` | Check the status of a publish job | | `shoppex theme logs --theme [--job ] [--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 ` | List theme backups | | `shoppex theme rollback --theme --backup ` | Roll the theme back to a backup | | `shoppex theme latest-run --theme ` | 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): ```bash theme={"system"} 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: ```bash theme={"system"} shoppex theme publish --theme 11111111-1111-4111-8111-111111111111 shoppex theme logs --theme 11111111-1111-4111-8111-111111111111 --job --follow ``` Clone, develop locally, preview, publish: ```bash theme={"system"} 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: ```bash theme={"system"} shoppex theme doctor ``` Capture visual evidence after edits, before pushing: ```bash theme={"system"} shoppex theme screenshot --routes /home,/product/specter-license,/cart,/checkout ``` Use live shop data instead of fixtures in the dev server: ```bash theme={"system"} 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 The stored API key is missing, expired, or revoked. Re-run `shoppex auth login --api-key ` with a valid key that has the `themes.read` and `themes.write` scopes, or check that `SHOPPEX_API_KEY` is set correctly. 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. 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](https://bun.sh) in that case. 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`. ## Next Steps CLI sync, fixture data, live shop data, and common local setup issues. Use the Edit with AI workflow and MCP-connected assistants on your theme.