> ## 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.

# Hosted Theme Sync

> Pull a hosted Liquid theme locally, run the Liquid preview, push validated source, then preview and publish.

# Hosted Theme Sync

<Info>
  This workflow applies to **custom code themes** (forked or imported Liquid packages) hosted on Shoppex.
</Info>

Use this workflow when you want to edit your Liquid custom theme locally.

The loop is:

```text theme={"system"}
API key -> pull -> theme dev -> push -> preview -> publish
```

## What You Need

* Shoppex CLI
* a Shoppex API key with `themes.read` and `themes.write`

## Step 1: Create A Theme Development Key

In the Shoppex dashboard:

1. Open **Settings** -> **Developer**
2. Open **API Keys**
3. Click **Create API Key**
4. Choose the **Theme Development** preset
5. Copy the secret immediately

The key can inspect and update theme source. It does not need payment, order, customer, or product write scopes.

## Step 2: Login

```bash theme={"system"}
npx @shoppexio/cli auth login --api-key shx_your_key
```

## Step 3: Pull Source

```bash theme={"system"}
shoppex theme list
shoppex theme pull --theme 11111111-1111-4111-8111-111111111111 --out ./my-theme
cd ./my-theme
```

The pulled folder contains `.shoppex/theme.json`. That file links the local folder to the remote theme id and source revision.

## Step 4: Run Local Liquid Preview

```bash theme={"system"}
shoppex theme dev
```

This starts the Liquid dev server for the pulled package. It requires `theme-package.json`.

Use live shop data instead of fixtures:

```bash theme={"system"}
shoppex theme dev --shop-slug my-shop --no-msw
```

## Step 5: Push Draft Source

```bash theme={"system"}
shoppex theme push
```

What push does:

* uploads the full local source snapshot
* replaces the remote draft source
* deletes remote draft files that you deleted locally
* validates the draft
* never publishes automatically

Start a preview immediately after a successful push:

```bash theme={"system"}
shoppex theme push --preview
```

## Step 6: Preview And Publish

```bash theme={"system"}
shoppex theme preview
shoppex theme publish
```

Publish builds a new immutable live version and activates it for the storefront unless you pass a build-only option.

## Revision Mismatch

If someone changed the remote draft after your last pull, push stops with a revision mismatch.

Safe fix:

```bash theme={"system"}
shoppex theme pull --force
```

Only force push when you intentionally want to replace newer remote changes:

```bash theme={"system"}
shoppex theme push --force
```

## Recommended Daily Workflow

```bash theme={"system"}
shoppex theme pull --theme 11111111-1111-4111-8111-111111111111 --out ./my-theme
cd ./my-theme
shoppex theme dev
shoppex theme push --preview
shoppex theme publish
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Local Development" icon="sliders" href="/themes/local-development">
    Fixture data, live shop data, and local validation.
  </Card>

  <Card title="Editing Themes" icon="gear" href="/themes/editing">
    Dashboard, CLI, Dev API, and MCP workflow.
  </Card>
</CardGroup>