Skip to main content

​
AI Theme Workflows

This page shows how to combine the Theme Control Plane, the CLI, and the MCP server into one practical workflow.
This page is the more advanced AI guide. If you are new and want the simplest beginner path first, start with Build and Customize a Theme with AI.
The control plane is the safe backend, the CLI gives you direct commands, and MCP lets an AI assistant drive the same operations as tools.

​
Best Use Cases For AI

AI is a good fit when you want to:
  • inspect a large theme quickly
  • find the right files before editing
  • generate a new section or page scaffold
  • make a focused content or layout change
  • iterate with preview and validation
AI is a bad fit when you skip verification and ask for a huge blind rewrite. Good: “inspect the theme, find the hero section, then change only the CTA copy and button styles.” Risky: “rewrite the whole storefront from scratch in one step.”

​
1. Create An API Key

Use:
  • themes.read
  • themes.write
If the AI should only inspect and explain, themes.read is enough. If it should scaffold and publish, add themes.write.

​
2. Pick Your Surface

Use one of these:
  • dashboard session for built-in Shoppex editing
  • CLI for terminal-driven workflows
  • MCP for AI tool use
You can mix them because they hit the same backend workflow. You can mix surfaces freely — inspect with MCP, preview in the dashboard, and publish from the CLI.

​
CLI Workflow

​
Login

shoppex auth login --api-key shx_your_key

​
Inspect A Theme

shoppex theme inspect --theme theme_123
shoppex theme search --theme theme_123 --query hero
shoppex theme read-file --theme theme_123 --path src/pages/Home.tsx

​
Apply A Small Change

Create a JSON file with your changes: 
{
  "changes": [
    {
      "path": "src/pages/Home.tsx",
      "content": "// updated file content here"
    }
  ],
  "runTypecheck": true
}
Then apply it: 
shoppex theme apply --theme theme_123 --file changes.json
shoppex theme validate --theme theme_123 --include-typecheck
shoppex theme preview --theme theme_123

​
Publish

shoppex theme diff --theme theme_123
shoppex theme publish --theme theme_123

​
MCP Workflow

Set these environment variables before starting the MCP server: 
export SHOPPEX_API_URL=https://api.shoppex.io
export SHOPPEX_API_KEY=shx_your_key
Then start the Shoppex theme MCP server from your MCP client setup. The most useful tools are:
  • theme.inspect
  • theme.search_files
  • theme.read_file
  • theme.apply
  • theme.create_section
  • theme.create_page
  • theme.update_config
  • theme.validate
  • theme.preview
  • theme.publish

​
The End-To-End AI Loop

The recommended order, whether you use CLI or MCP:
  1. inspect the theme
  2. search_files for the relevant area
  3. read_file only the files that matter
  4. apply a small change
  5. validate
  6. preview
  7. publish
This is significantly safer than asking AI to patch unknown files all at once.

​
Workflow Examples

​
Update Existing Content

Change hero copy while keeping layout intact: inspect → search for the hero section → read the component file → apply a single-file patch → preview.

​
Add A New Section

Add testimonials to the homepage: inspect available sections → create_section → update_config to wire it in → validate and preview.

​
Add A New Static Page

Add /about: create_page → inspect the generated route → apply content edits → validate and preview.

​
Start A New Theme

Create from default: create → inspect → scaffold sections/pages → apply edits → validate and publish.

​
Prompt Patterns That Work Well

Good prompts are specific and constrained. These work well:
  • “Inspect this theme and list the sections I can safely edit on the homepage.”
  • “Search for the hero CTA, read the relevant files, and change only the button text and color.”
  • “Create a new testimonials section, wire it into the theme config, and then validate.”
These don’t: “Redesign everything”, “Rewrite the whole store”, “Change whatever you think looks bad.” Vague prompts lead to blind patches.

​
Review And Safety Rules

  • Use small batches
  • Validate before previewing
  • Preview before publishing
  • Use diff before final publish
  • Use rollback if a published change was wrong
If you are reviewing a dashboard-agent draft, use accept for that reviewed draft instead of re-applying the same change manually.

​
Suggested Team Workflow

The designer or merchant describes the desired outcome, the AI inspects and proposes the smallest change, the control plane validates it, a human reviews the preview, and you publish after approval. That gives you speed without turning theme editing into a blind code-generation loop.

​
Next Steps

Theme Control Plane

Learn the shared model behind dashboard, Dev API, CLI, and MCP.

Quickstart

Run a reference theme locally while you iterate.

Theme Config

Understand how settings and sections are defined.

Troubleshooting

Fix common local-development, data, and runtime issues.