Skip to main content

​
Editing Themes

Edit a Shoppex theme from the dashboard, from your terminal, or from an AI agent. Every path goes through the same validate → preview → publish flow, so a change made by Claude looks identical to a change made in the dashboard.
New to Shoppex themes? Start with Build and Customize a Theme with AI or Hosted Theme Sync. This page is the reference that ties those workflows together.

​
Pick How You Want To Edit

Dashboard

Click-based editing with a built-in preview. Best for content, layout, and brand tweaks.

Local source sync

Pull the theme, edit in your editor, push back. Best for real development.

AI agent

Let Claude or another assistant drive the edits through MCP. Best for large inspections and focused refactors.

Dev API

Drive edits from your own backend or scripts. Best for automation and integrations.
All four paths call the same endpoints under the hood, so you can switch between them on the same theme without conflicts.

​
The Workflow

Every edit, no matter the surface, follows the same sequence: inspect → read → apply → validate → preview → publish
  1. Inspect the theme to see its sections, settings, and brand tokens.
  2. Read the files you plan to change.
  3. Apply a small, focused patch.
  4. Validate — the draft is checked automatically.
  5. Preview the draft in a real storefront.
  6. Publish when you’re happy, or rollback if something breaks in production.
You don’t have to call these steps by hand — the dashboard does it for you, the CLI bundles them into push, and AI agents have them as tools. But knowing the sequence helps when something goes wrong.

​
Quick Start: Local Source Sync

The most common path for developers: 
shoppex auth login --api-key shx_your_key
shoppex theme pull --theme theme_123 --out ./my-theme
cd ./my-theme
# edit files in your editor
shoppex theme push --preview
shoppex theme publish --theme theme_123
What happens:
  • pull downloads the current theme source and writes .shoppex/theme.json with the theme ID and revision.
  • push uploads your local snapshot, validates it, and optionally opens a preview.
  • publish promotes the current draft to live.
  • push is a full replace of the current draft — files you delete locally are deleted on the server too.
  • If the server draft moved since your last pull, push fails with a revision mismatch unless you use --force.
  • If validation fails, the draft is still saved, but publish stays blocked until the errors are fixed.
  • Blocked paths (node_modules/, dist/, .git/, lockfiles) are never part of source sync.
See Hosted Theme Sync for the full onboarding walkthrough.

​
Quick Start: AI Agent

If you’re using Claude Code, Codex, or another MCP-capable agent: 
shoppex auth login --api-key shx_your_key
# point your agent's MCP config at the Shoppex theme server
The agent gets tools like theme.inspect, theme.read_file, theme.apply, theme.create_section, and theme.publish. Ask it to inspect first, then make focused changes:
“Inspect the theme, find the hero section, then change only the CTA copy and button styles.”
See AI Theme Workflows for the full setup.

​
What You Can Do

​
Edit an existing theme

Tweak copy, layout, styles, or settings on a theme that’s already installed.
  • Change a headline, swap colors, adjust spacing
  • Toggle section settings, update brand tokens
  • Preview before publishing, rollback if needed

​
Extend a theme

Add new building blocks without leaving the platform.
  • create_section — scaffold a new section (e.g. Testimonials)
  • create_page — add a new route (e.g. /about)
  • update_config — register a new setting in theme.config.ts

​
Create a new theme

Start from one of the Shoppex base themes: default, classic, nebula, or pulse. Use create and optionally set it active with setAsActive.

​
Auth And Scopes

For CLI, Dev API, and MCP you need a Shoppex API key. Two scopes cover everything:
  • themes.read — inspect, read, diff, search, settings, backups, latest run. Enough for a read-only audit bot.
  • themes.write — apply, accept, preview, publish, rollback, scaffolding. Needed for any autonomous editing agent.
The dashboard uses your existing session, so no API key is needed there.

​
Safe Editing Checklist

A short checklist that works for all surfaces:
  1. inspect — learn the theme’s shape first
  2. search_files — find where the thing lives
  3. read_file — read only what you’ll change
  4. apply — small, focused patches, not blind rewrites
  5. validate — confirm the draft is shippable
  6. preview — see it in a real storefront
  7. publish — when you’re sure
Don’t start with a huge blind patch. Learn the shape, change one logical thing, verify, then move on.

​
apply vs accept

Two similar-sounding operations, different use cases:
  • apply — you (or your agent) directly edit source files. This is the normal path.
  • accept — you’re approving a draft patch that the in-dashboard agent already proposed. You review its suggestion, then call accept for the chosen run.
If you’re not using the dashboard agent’s suggestion flow, you won’t need accept.

​
diff Before Publishing

Changed a handful of files this morning and can’t remember what’s still unpublished? Call diff — it compares the current draft against the last published snapshot, file by file.

​
How It Works Under The Hood

All four surfaces — dashboard, Dev API, CLI, and MCP — talk to the same backend, internally called the Theme Control Plane. It’s the shared editing surface that guarantees every client behaves the same way: same validation, same preview, same publish semantics, same rollback. You don’t need to know the control plane exists to use Shoppex themes. But if you’re building your own integration or tooling, these are the 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/validate
POST /dev/v1/themes/{id}/control/preview
POST /dev/v1/themes/{id}/control/publish
POST /dev/v1/themes/{id}/control/rollback
Full reference: API Reference → Themes.

​
Next Steps

Hosted Theme Sync

Step-by-step local source sync, from API key to publish.

AI Theme Workflows

End-to-end workflow for AI-assisted editing.

Theme Config

How sections and settings are represented in theme.config.ts.

Build Pipeline

What happens after validate, preview, and publish.