Skip to main content

​
Theme Control Plane

The Theme Control Plane is the shared editing surface for Shoppex themes.
This is an advanced platform page. If you are new and just want to customize a theme with Claude Code or Codex, start with Build and Customize a Theme with AI.
Every Shoppex surface — the dashboard, the Dev API, the CLI, and the MCP server — uses the same control plane. That means you can use the same workflow from a human UI, a script, or an AI agent.

​
What Problem It Solves

Without a shared control plane, theme editing usually splits into separate paths:
  • one path for the dashboard
  • one path for CLI scripts
  • one path for AI tools
That becomes hard to reason about. With the Theme Control Plane, all clients speak the same language:
  • inspect the theme
  • read or search files
  • apply changes
  • validate or preview
  • publish or rollback

​
The Mental Model

Think of a Shoppex theme like a source project with a safe editing API in front of it. The workflow is always: inspect → read → apply → validate → preview → publish.

​
Supported Operations

​
Inspect And Read

Use these first:
  • inspect
  • read_file
  • search_files
  • settings.get
  • latest_run
Use inspect to see sections, settings groups, brand tokens, and constraints. Use search_files to find where a headline, component, or setting lives. Use read_file only for the files you actually plan to edit.

​
Edit Existing Themes

Use these to customize an existing theme:
  • apply
  • validate
  • preview
  • publish
  • rollback
  • diff
For example: update a hero headline in src/pages/Home.tsx, run validate, open preview, then publish.

​
Extend Themes

Use these when you want to add new building blocks:
  • create_section
  • create_page
  • update_config
For example: scaffold a new Testimonials section, add a /about page, or register a new layout.show_badge setting in theme.config.ts.

​
Create New Themes

Use create when you want to scaffold a new theme from a Shoppex base theme. Supported bases:
  • default
  • classic
  • nebula
  • pulse
Create a new theme from default and either set it active later or immediately with setAsActive.

​
Access Modes

You can use the same control plane in four ways:

​
Dashboard

Use the Shoppex dashboard if you want a built-in UI and preview flow.

​
Dev API

Use the Dev API if you want backend automation or your own tooling. Typical endpoints:
  • POST /dev/v1/themes/control/create
  • GET /dev/v1/themes/{id}/control/inspect
  • POST /dev/v1/themes/{id}/control/apply
  • POST /dev/v1/themes/{id}/control/publish

​
CLI

Use the CLI if you want terminal workflows. If you want the end-to-end onboarding path for API key setup, pull, local dev, push, preview, and publish, start with Hosted Theme Sync. 
shoppex auth login --api-key shx_your_key
shoppex theme pull --theme theme_123 --out ./my-theme
shoppex theme push --dir ./my-theme
shoppex theme inspect --theme theme_123
shoppex theme preview --theme theme_123
shoppex theme publish --theme theme_123

​
Local Push And Pull

For classic local theme development, use pull and push. 
shoppex auth login --api-key shx_your_key
shoppex theme pull --theme theme_123 --out ./my-theme
cd ./my-theme
shoppex theme push --preview
How it works:
  • pull downloads the current theme source ZIP
  • pull writes .shoppex/theme.json with the themeId and sourceRevision
  • push uploads the full local source snapshot
  • push always validates the uploaded draft
  • push never publishes automatically
  • push is a full replace of the current draft source
  • files deleted locally are deleted on the server draft too
  • blocked paths like node_modules/, dist/, .git/, and lockfiles are not part of source sync
  • if the server draft changed after your last pull, push fails with a source revision mismatch unless you use --force
  • if validation fails, the draft is still saved, but publish stays blocked until the errors are fixed

​
MCP

Use the MCP server if you want an AI assistant to drive the workflow through tools like:
  • theme.inspect
  • theme.read_file
  • theme.apply
  • theme.create_section
  • theme.publish

​
Auth And Scopes

For Dev API, CLI, and MCP, use a Shoppex API key. Recommended scopes:
  • themes.read for inspect, diff, search, read, settings get, backups, latest run
  • themes.write for create, apply, accept, preview, publish, rollback, and scaffolding
A read-only audit bot needs themes.read. An autonomous editing agent needs both themes.read and themes.write.
  1. inspect
  2. search_files
  3. read_file
  4. apply in small batches
  5. validate
  6. preview
  7. publish
Don’t start with a huge blind patch. Learn the theme shape first, then change one logical thing at a time.

​
When To Use accept

accept is for draft patches that already came from a dashboard-agent run. The dashboard agent suggests a change, you review it, and you call accept for the chosen run/message/variant. If you are directly editing source files through the control plane, you usually use apply, not accept.

​
When To Use diff

Use diff when you want to compare the current draft against the latest published snapshot. Changed 4 files this morning and want to confirm what’s still unpublished? Call diff before publishing.

​
Next Steps

Hosted Theme Sync

Follow the local source sync workflow from dashboard API key creation to push, preview, and publish.

AI Theme Workflows

See the full recommended workflow for AI-assisted editing with CLI and MCP.

Theme Config

Learn how sections and settings are represented inside theme.config.ts.

Build Pipeline

Understand what happens after validate, preview, and publish.

API Reference

Browse the Dev API reference for the theme control endpoints.