# themes (API)

> The 56 low-level Shoplazza CLI theme API commands for managing themes, theme files and versions, edit sessions, cards, templates, app embeds, and the theme market, plus the page-editing shortcuts.

Full API commands for theme management. 56 API commands and 6 shortcuts.

These are the low-level API commands for themes. For the local development workflow (`init`, `serve`, `pull`, `push`, `package`, `share`, `env`), see [theme](./theme).

All theme API commands share these flags:

| Flag | Short | Description |
|------|-------|-------------|
| `--params` | | Path/query parameters as JSON |
| `--data` | | Request body as JSON |
| `--jq` | `-q` | jq expression to filter output |
| `--dry-run` | | Preview the request without executing |

Path parameters such as `theme_id` always go in `--params`. Run `shoplazza schema themes.<command>` (for example `shoplazza schema themes.file.update`) to see a command's parameters and body.

## themes

```shell
shoplazza themes list
shoplazza themes get --params '{"theme_id":"123"}'
shoplazza themes rename --params '{"theme_id":"123"}' --data '{"name":"New name"}'
shoplazza themes duplicate --data '{"copy_theme_id":"123","copy_theme_name":"My theme copy"}'
shoplazza themes upgrade --params '{"theme_id":"123"}'
shoplazza themes publish --params '{"theme_id":"123"}'
shoplazza themes delete --params '{"theme_id":"123"}'
shoplazza themes task --params '{"task_id":"123"}'
```

## themes file

Manage individual theme files.

```shell
shoplazza themes file tree --params '{"theme_id":"123"}'
shoplazza themes file get --params '{"theme_id":"123","type":"layout","location":"theme.liquid"}'
shoplazza themes file create --params '{"theme_id":"123"}' --data @file.json
shoplazza themes file update --params '{"theme_id":"123"}' --data @file.json
shoplazza themes file delete --params '{"theme_id":"123"}' --data '{"type":"assets","location":"old.css"}'
shoplazza themes file rename --params '{"theme_id":"123"}' --data '{"doc":{"type":"assets","location":"a.css","new_location":"b.css"}}'
```

For `create` and `update`, `file.json` holds `{"doc":{"type":"assets","location":"new.css","content":"..."}}`.

## themes version

Manage theme versions.

```shell
shoplazza themes version list --params '{"theme_id":"123","type":"layout","location":"theme.liquid"}'
shoplazza themes version records --params '{"theme_id":"123"}'
shoplazza themes version get --params '{"theme_id":"123","version_id":"456"}'
```

## themes session

Work on a theme inside an edit session: read and write files, batch edits, global config, the card library, conflict checks, and saving to the draft.

```shell
shoplazza themes session create --params '{"theme_id":"123"}'
shoplazza themes session get-file --params '{"oseid":"<oseid>","doc_id":"<doc_id>"}'
shoplazza themes session update-file --params '{"oseid":"<oseid>","doc_id":"<doc_id>"}' --data @file.json
shoplazza themes session batch-ops --params '{"oseid":"<oseid>","doc_id":"<doc_id>"}' --data @ops.json
shoplazza themes session get-config --params '{"oseid":"<oseid>","doc_id":"<doc_id>"}'
shoplazza themes session update-config --params '{"oseid":"<oseid>","doc_id":"<doc_id>"}' --data @settings.json
shoplazza themes session card-list --params '{"oseid":"<oseid>"}'
shoplazza themes session check --params '{"oseid":"<oseid>"}'
shoplazza themes session promote --params '{"oseid":"<oseid>"}'
```

## themes section

Arrange the cards on a page.

```shell
shoplazza themes section cards --params '{"theme_id":"123"}'
shoplazza themes section list --params '{"oseid":"<oseid>","doc_id":"<doc_id>"}'
shoplazza themes section get --params '{"oseid":"<oseid>","doc_id":"<doc_id>","section_id":"<section_id>"}'
shoplazza themes section set-props --params '{"oseid":"<oseid>","section_id":"<section_id>"}' --data @props.json
shoplazza themes section remove --params '{"oseid":"<oseid>","section_id":"<section_id>"}' --data '{"doc_id":"<doc_id>"}'
```

## themes block

Manage blocks inside a card and AI cards, and list public cards.

```shell
shoplazza themes block list
shoplazza themes block add --params '{"oseid":"<oseid>","section_id":"<section_id>"}' --data @block.json
shoplazza themes block set-props --params '{"oseid":"<oseid>","section_id":"<section_id>"}' --data @props.json
shoplazza themes block remove --params '{"oseid":"<oseid>","section_id":"<section_id>"}' --data @block.json
shoplazza themes block create-gen --params '{"oseid":"<oseid>"}' --data @card.json
shoplazza themes block get-gen --params '{"oseid":"<oseid>","type":"blocks/gen_1a0d523"}'
shoplazza themes block update-gen --params '{"oseid":"<oseid>"}' --data @card.json
shoplazza themes block delete-gen --params '{"oseid":"<oseid>","type":"blocks/gen_1a0d523"}'
shoplazza themes block revert-gen --params '{"oseid":"<oseid>"}' --data '{"revert_id":"<revert_id>"}'
```

## themes template

Manage custom templates bound to products, collections, and pages.

```shell
shoplazza themes template list --params '{"theme_id":"123"}'
shoplazza themes template create --params '{"theme_id":"123"}' --data @template.json
shoplazza themes template update --params '{"theme_id":"123","template_id":"456"}' --data @template.json
shoplazza themes template delete --params '{"theme_id":"123","template_id":"456"}'
```

## themes app

Manage app embeds on the storefront and list app extension cards.

```shell
shoplazza themes app list
shoplazza themes app extensions
shoplazza themes app enable --params '{"oseid":"<oseid>"}' --data @embed.json
shoplazza themes app disable --params '{"oseid":"<oseid>"}' --data @embed.json
```

## themes market

Browse the theme market and install a theme into the store.

```shell
shoplazza themes market list
shoplazza themes market install --params '{"remote_theme_id":"123"}'
```

## themes pb

Page-builder operations.

```shell
shoplazza themes pb list-blocks --params '{"event_type":"page-builder","source_ids":"<source_id>"}'
shoplazza themes pb save-block --data @block.json
shoplazza themes pb save-template --data @template.json
shoplazza themes pb delete-template --params '{"template_id":"456"}'
shoplazza themes pb summary --data @canvas.json
shoplazza themes pb update --data @canvas.json
```

## Shortcuts

Shortcuts for reading and editing template pages. They have their own flags; run `shoplazza themes <shortcut> --help` for details.

| Shortcut | Description |
|----------|-------------|
| `themes +page` | Read a template page: sections in render order and blocks with ready-to-copy targets |
| `themes +edit` | Apply a batch of edit operations to a template page in one edit session |
| `themes +preview` | Print a storefront preview URL for a theme (optionally an edit session) |
| `themes +card-schema` | Read the settings and blocks schema of up to 10 addable cards |
| `themes block +get` | Read a generated block: file info, reference count, and placements |
| `themes block +edit` | Write a generated block file and place it on a template page |

```shell
shoplazza themes +page --template index
shoplazza themes +edit --template index --session <oseid> --ops '[{"op":"update_slot","target":"<section_id>.blocks[0]","props":{"heading":"Summer sale"}}]'
shoplazza themes +edit --template index --session <oseid> --ops '[]' --promote
shoplazza themes +preview -t <theme_id>
shoplazza themes +card-schema -t <theme_id> --ids rich_text,collection_list
```

## Related

* [theme](./theme) — Theme development commands
* [Theme CLI guide](/docs/theme/developer-tools/shoplazza-cli/) — Theme-focused documentation