# theme

> Shoplazza CLI theme development commands for a Shoplazza Theme: scaffold from Nova 2023, serve with live reload, pull, push, package, share a preview link, and manage environments.

Theme development commands for scaffolding, previewing, and publishing themes. They are subcommands of `shoplazza themes` with no `+` prefix, listed next to the [theme API commands](./themes-api).

`pull`, `push`, `serve`, and `share` accept `-e, --environment <name>` to run against an environment defined in `shoplazza.theme.toml`. See [env](#env).

## init

Scaffold a new theme based on Nova 2023.

```shell
shoplazza themes init --name <dir>
```

### Flags

| Flag | Type | Description |
|------|------|-------------|
| `--name <dir>` | string | Target directory name for the new theme (required) |

Clones the Nova 2023 template to your local machine as a starting point for theme development. No login is required. The target directory must not exist or must be empty.

## serve

Upload the current theme to a store and preview it with live reload.

```shell
shoplazza themes serve [flags]
```

### Flags

| Flag | Type | Description |
|------|------|-------------|
| `--theme-id, -t <THEME_ID>` | string | Theme ID to serve and overwrite. If omitted, uses the directory's development theme. |
| `--environment, -e <NAME>` | string | Environment from `shoplazza.theme.toml` (store, profile, theme) |
| `--port <PORT>` | int | LiveReload server port (default: 21647) |
| `--skip-push` | bool | Skip the startup full upload and watch right away; only files changed while serve runs are sent |
| `--task-id <TASK_ID>` | string | Resume waiting for an earlier upload task instead of uploading again |
| `--timeout <SECONDS>` | int | Stop watching after this many seconds and exit (default: 0, watch until interrupted) |

Without `--theme-id`, the first run creates a development theme named `Development - <theme name>` and saves its ID in `.shoplazza/theme-state.json` (one per store); later runs reuse it.

This command prints:

* A preview link to share with other developers
* A link to the theme editor in the Shoplazza admin

Each file change is synced to the theme and reloads connected browsers. Syncing is one-way (local to remote); run `themes pull` to fetch changes made in the theme editor. The command runs until you press Ctrl-C.

The startup upload replaces the theme's files on the server with your local files, so it removes files that exist only on the server and overwrites theme editor changes, including `config/settings_data.json`. Use `--skip-push` to keep them.

:::note
You can only run this command in a directory that matches the [default Shoplazza theme directory structure](/docs/theme/architecture/overview#directory-structure-and-component-types) (one that contains `config/settings_schema.json`).
:::

## pull

Download theme files from a Shoplazza store.

```shell
shoplazza themes pull [flags]
```

### Flags

| Flag | Type | Description |
|------|------|-------------|
| `--theme-id, -t <THEME_ID>` | string | Theme ID to pull. Required unless `-e` provides it; in a terminal, you can pick a theme from a list instead. Run `shoplazza themes list` to discover. |
| `--environment, -e <NAME>` | string | Environment from `shoplazza.theme.toml` (store, profile, theme) |
| `--dry-run` | bool | Print what would be downloaded and which local files it can overwrite, without sending anything |

Files are unpacked into the current directory. The store and theme are then recorded in `shoplazza.theme.toml` (the `default` environment, or the one named by `-e`); the file is created if absent, and changing an existing environment asks first.

## push

Upload local theme files to a Shoplazza store, overwriting the remote version.

```shell
shoplazza themes push [flags]
```

### Flags

| Flag | Type | Description |
|------|------|-------------|
| `--theme-id, -t <THEME_ID>` | string | Theme ID to overwrite. Required unless `-e` provides it; in a terminal, you can pick a theme from a list instead. Run `shoplazza themes list` to discover. |
| `--environment, -e <NAME>` | string | Environment from `shoplazza.theme.toml` (store, profile, theme) |
| `--task-id <TASK_ID>` | string | Resume waiting for an earlier upload task instead of uploading again (the `task_id` from a timeout error) |
| `--dry-run` | bool | Print what would be uploaded and where, without packaging or sending anything |

In a terminal, `push` asks you to confirm before it overwrites the theme. It then waits up to 10 minutes for the server to process the upload; if the wait times out, re-run with `--task-id` to keep waiting. Like `pull`, it records the store and theme in `shoplazza.theme.toml`.

## package

Package local theme files into a ZIP file.

```shell
shoplazza themes package [flags]
```

### Flags

| Flag | Type | Description |
|------|------|-------------|
| `--no-ignore` | bool | Ignore .themeignore rules (default: false) |

The ZIP file is named `theme_name-theme_version.zip` based on your `settings_schema.json`.

## share

Upload your theme as a new, unpublished theme and return a shareable preview link. It never overwrites an existing theme.

```shell
shoplazza themes share [flags]
```

### Flags

| Flag | Type | Description |
|------|------|-------------|
| `--environment, -e <NAME>` | string | Environment from `shoplazza.theme.toml` (store, profile) |
| `--dry-run` | bool | Print what would be uploaded as a new preview, without packaging or sending anything |

## env

Inspect and edit the environments in `shoplazza.theme.toml`, which the CLI finds by searching up from the current directory.

```shell
shoplazza themes env <command> [name] [flags]
```

| Command | Description |
|---------|-------------|
| `themes env list` | List the environments |
| `themes env show [name]` | Show one environment (default: `default`) |
| `themes env check [name]` | Validate offline that each environment resolves to a logged-in profile; omit the name to check all |
| `themes env add [name] --store <domain> [--theme <id>]` | Add an environment |
| `themes env set [name] [--store <domain>] [--theme <id>]` | Change an existing environment; only the flags you pass change |
| `themes env remove [name]` | Remove an environment |

```toml title="shoplazza.theme.toml"
[environments.default]
store = "my-store.myshoplaza.com"
theme = "123456"

[environments.staging]
store = "staging.myshoplaza.com"
theme = "654321"
```

Select an environment with `-e <name>` or the `SHOPLAZZA_CLI_ENVIRONMENT` environment variable. When neither is set, the `default` environment applies automatically. The file holds no credentials; the environment's store must have a logged-in profile. `add`, `set`, and `remove` rewrite the file without comments.

## Related

* [Theme CLI guide](/docs/theme/developer-tools/shoplazza-cli/) — Theme-focused documentation
* [themes-api](./themes-api) — Full API commands for themes (list, get, publish, delete, duplicate, upgrade, files, versions, edit sessions)