@shoppexio/cli

Shoppex CLI for theme development workflows.

Scope: custom code themes. The CLI theme tooling works with custom code themes — Liquid source packages, e.g. a theme forked from an official Shoppex theme. Themes built visually in the Shoppex Theme Builder are rendered and served by Shoppex and have no editable Liquid source; manage those in the Theme Builder. Pulling and pushing applies to code themes: pushing source to a visually built theme converts it into a code theme fork.

Use this package when you want to:

• pull a Shoppex code theme into a local folder
• push your local draft source back to Shoppex
• inspect, validate, preview, and publish from the terminal

Full reference: https://docs.shoppex.io/themes/cli-reference

Requirements

• Node.js >= 18 — 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 via bun run dev:liquid.)
• Playwright for theme screenshot (optional peer dependency, kept out of the default install to stay lightweight): npm install -D playwright && npx playwright install chromium

Key Commands

Install from npm:

npx @shoppexio/cli auth login --api-key shx_your_key

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

npx @shoppexio/cli theme init --base default --out ./my-theme --name "My Theme"
cd ./my-theme

Follow a publish job as a live status stream:

npx @shoppexio/cli theme logs --theme <themeId> --job <jobId> --follow

Or run it from this repo:

bun packages/cli/bin/shoppex.mjs auth login --api-key shx_your_key
bun packages/cli/bin/shoppex.mjs theme pull --theme 11111111-1111-4111-8111-111111111111 --out ./my-theme
cd ./my-theme
bun /absolute/path/to/shoppex/packages/cli/bin/shoppex.mjs theme status
bun /absolute/path/to/shoppex/packages/cli/bin/shoppex.mjs theme doctor
bun /absolute/path/to/shoppex/packages/cli/bin/shoppex.mjs theme dev
bun /absolute/path/to/shoppex/packages/cli/bin/shoppex.mjs theme screenshot --routes /home,/product/specter-license,/cart,/checkout
bun /absolute/path/to/shoppex/packages/cli/bin/shoppex.mjs theme push --preview
bun /absolute/path/to/shoppex/packages/cli/bin/shoppex.mjs theme publish --theme 11111111-1111-4111-8111-111111111111

theme publish activates the completed build on the live storefront. Use --build-only when you want to build and upload an artifact without changing the active storefront.

theme dev starts a local Liquid preview for pulled workspaces that contain theme-package.json. It does not start a remote preview sandbox or publish. The CLI still runs a safe background theme push after idle changes and once more on shutdown.

theme screenshot uses the same local Liquid preview surface to capture visual checkpoints into .shoppex-screenshots/. Run it after visual edits before push --preview or publish.

theme init creates a theme from an official base (default, classic, nebula, pulse) on the server and immediately clones it into --out as a linked workspace. The target directory must be empty or non-existent. If the clone fails after the server create, the CLI prints the new theme id so you can finish with shoppex theme clone --theme <id> — it never deletes the server theme.

theme logs streams job/run status as human-readable lines. With --job <jobId> it reads the publish job status; without --job it shows the latest AI builder run. This is an incremental status stream (the API exposes status snapshots, not full build logs): with --follow the CLI polls every 3 seconds, prints only new status changes, and exits 0 on COMPLETED or 1 on FAILED.

Safety Model

Simple rules:

• pull stores .shoppex/theme.json with the linked theme and source revision
• status compares the linked local revision, local files, and remote source revision
• doctor checks auth, workspace link, remote source access, inspect, validation, and preview startup
• dev requires a Liquid theme-package.json; legacy React/Vite workspaces fail fast
• screenshot captures local PNG evidence and fails on route errors
• push uploads the full local source snapshot
• push validates automatically
• push never publishes automatically
• Liquid workspaces with theme-package.json are checked locally before upload: dynamic render/include targets, script tags, executable files, and missing declared package files are rejected before the ZIP leaves your machine
• pull refuses to overwrite dirty linked workspaces unless you pass --force
• a revision mismatch blocks accidental overwrites unless you pass --force

Auth

The easiest way is the browser device login — no key copy-pasting:

shoppex auth login
# prints a short code, opens the dashboard approval page, and waits;
# approving mints a Theme-Development API key and hands it to the CLI.

Alternatives: shoppex auth login --manual (masked key prompt), shoppex auth login --api-key shx_your_key, or set SHOPPEX_API_KEY. Manually created keys live in the Shoppex dashboard under Settings → Developer → API Keys ("Theme Development" section) with scopes:

• themes.read
• themes.write

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Error (validation, auth, network, policy) | | 2 | Conflict halted — the remote theme changed; theme dev/theme open stopped auto-push instead of overwriting it |

Troubleshooting

• 401 Authentication failed — key missing/revoked: re-run shoppex auth login.
• 409 revision conflict on push — the remote draft changed since your pull. Check with the merchant, then shoppex theme pull --force and push again.
• "no bun binary was found" (monorepo checkouts only) — install Bun: https://bun.sh
• "theme screenshot requires Playwright" — npm install -D playwright && npx playwright install chromium.
• Package too large on push — convert PNG/JPEG assets to WebP, remove unused reference files, retry shoppex theme push --preview.

MCP install on Windows

shoppex mcp install --client claude-desktop writes Claude Desktop config to every known location:

• %APPDATA%\\Claude\\claude_desktop_config.json
• %LOCALAPPDATA%\\Packages\\Claude_*\\LocalCache\\Roaming\\Claude\\claude_desktop_config.json for Microsoft Store installs

Quit and reopen Claude Desktop after installing MCP servers.

Related Docs

• CLI Reference: https://docs.shoppex.io/themes/cli-reference
• Hosted Theme Sync: https://docs.shoppex.io/themes/hosted-theme-sync
• Theme Editing: https://docs.shoppex.io/themes/editing