# Theme commands (/themes/cli)

`poltura theme` works with a store's themes from your own machine and your own editor: pull a theme into a folder, edit it, and push it to a draft that a preview link shows. The browser [code editor](/themes) edits the same drafts, so you can use both. Install and sign-in are on the [CLI page](/apps/cli). (Not published to npm yet.)

| Command | Does |
| --- | --- |
| `poltura theme init <dir>` | Starts a theme from the Poltura starter theme. |
| `poltura theme check <dir>` | Validates a theme directory: layout, sections, settings and types. |
| `poltura theme list` | Lists the store's themes. |
| `poltura theme pull` | Downloads a theme's files and their hashes into a folder. |
| `poltura theme push` | Uploads changed files to a draft theme. |
| `poltura theme dev` | Pushes every save to a development copy of the live theme and prints its preview link. |
| `poltura theme open` | Prints the preview link of a draft. |
| `poltura theme share` | Prints the preview link of a draft, like `open` without a path. |
| `poltura theme publish` | Publishes a draft, or prints the link where a person approves it. |
| `poltura theme rollback` | Restores an earlier version into a draft. |
| `poltura theme package [dir]` | Zips a theme directory for the theme store. |

`init`, `check` and `package` work on files only and need no sign-in. The others talk to a store with a credential: `--token`, then `POLTURA_TOKEN`, then your `poltura login` sign-in, as described under [Sign in or use a token](/apps/cli#sign-in-or-use-a-token). They take `--api`, `--store`, `--dir <dir>` (the theme folder, default the current one) and `--json`.

## Permissions [#permissions]

What the credential needs depends on the command:

| Command | Permission | Asks a person? |
| --- | --- | --- |
| `list`, `pull`, `rollback` without `--revision` | `theme.read` | No. |
| `open`, `share`, and the preview link `dev` prints | `theme.code.write` and `theme.write` | No. |
| `push`, `dev` | `theme.code.write`, and `theme.write` for the development copy | Writing files does not. Deleting files does: the CLI says so and prints the approval link. |
| `rollback --revision <id>` | `theme.write` | Yes, always. |
| `publish` | `theme.publish` | Yes, always. |

An API token holds these permissions as you set them when you create it. A `poltura login` sign-in asks for every read permission by default; add the write permissions you need with `poltura login --permissions theme.read,theme.code.write,theme.write,theme.publish` and approve them in the browser. A person approves a request in the store admin under **Agent requests**. How approval works is on [How agents act on your store](/ai/agents#approval).

## Start and check a theme [#start-and-check-a-theme]

```bash
poltura theme init my-theme --name "My theme"
cd my-theme
poltura theme check .
```

`init` writes the starter theme into an empty directory. `check` is the same check that runs after every save in the code editor, and every problem points at its file, line and column.

| Option | Meaning |
| --- | --- |
| `--types <packRoot>` | Type pack used to typecheck the theme. Also read from `POLTURA_THEME_TYPES`. |
| `--json` | Print the report as one JSON line. |
| `--base <dir>` | The tree before your change. Element files that differ from it are held to the authoring rules. |
| `--task-pack <file>` | Used by Poltura's AI theme jobs. Needs `--done-summary`. |
| `--done-summary <text>` | Used by Poltura's AI theme jobs. Needs `--task-pack`. |

The check needs the theme type pack: without `--types` or `POLTURA_THEME_TYPES` (or a pack installed at `/opt/theme-types`) it fails with `Requested typecheck did not run`. The type pack is not published yet, so for now the code editor, which runs the same check on every save, is where types are checked. The command exits with code 1 when the theme has errors. [`poltura check`](/apps/cli#check-before-you-publish) runs this check together with the Poltura code rules in one verdict.

## Pull, edit, push [#pull-edit-push]

```bash
poltura theme pull            # the live theme into the current folder
poltura theme dev             # a development copy, pushed on every save
```

`pull` downloads the live theme (or `--theme <id>`) and writes `.poltura/theme.lock.json`, which remembers the hash of every file as you pulled it. Commands work from any subfolder of a pulled theme. The live theme takes no pushes.

`dev` creates a development copy of the live theme the first time and keeps its id in the lock file. It pushes your files, prints the preview link, then watches the folder and pushes each saved file after a short pause. The preview shows a save once the draft has built. Ctrl+C stops it.

`push` uploads what changed to a draft: the development copy, else the pulled theme, else `--theme <id>`. It is safe against the editor and against other people: if a file changed in the store after you pulled it, the push stops with a `conflict` line for each file and writes nothing. Pull again, or use `--force`, which only works on a draft this checkout created. A deleted local file is deleted in the draft only after a person approves it.

## Preview, share, publish, roll back [#preview-share-publish-roll-back]

```bash
poltura theme open --path /products/hat
poltura theme share
poltura theme publish --wait
poltura theme rollback
poltura theme rollback --revision <id> --wait
```

`open` prints the preview link of the draft, and `--path` points it at a storefront path such as `/products/hat`. `share` prints the same link without a path. The link comes from the draft's current build, so the command fails with a message when the draft is still building; run it again a minute later.

`publish` asks Poltura to publish the draft. Publishing always needs a person: the command prints the approval link, the expiry and the run id, and exits with code 3. With `--wait` it waits for the decision and then prints the result. The approval card shows the theme by name, the changed file paths, the preview link and any new outside hosts; there is no separate code review step. See [Approval](/ai/agents#approval).

> **Publish code changes from the theme editor or Klea**
>
> Publishing a draft whose code changed is refused for every API token, `poltura login` sign-in and MCP connection with `permission_denied`. Leave the draft ready and publish it from the theme editor or ask Klea. A draft that changes only settings, texts or layout publishes normally.

`rollback` without `--revision` lists the draft's earlier versions. With `--revision <id>` it restores that version into the draft, after a person approves it. The live store does not change until you publish.

## Package for the theme store [#package-for-the-theme-store]

`poltura theme package [dir]` zips the directory (without hidden files, `node_modules` and `dist`) into `<name>.zip`, or into the file `--out <file>` names.