Theme commands
Start a theme, check it, pull and push it to a draft, preview it live, publish it and go back, all from the poltura command line.
On this page
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 edits the same drafts, so you can use both. Install and sign-in are on the CLI page. Not on 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. They take --api, --store, --dir <dir> (the theme folder, default the current one) and --json.
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.
Start and check a theme
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 runs this check together with the Poltura code rules in one verdict.
Pull, edit, push
poltura theme pull # the live theme into the current folder
poltura theme dev # a development copy, pushed on every savepull 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
poltura theme open --path /products/hat
poltura theme share
poltura theme publish --wait
poltura theme rollback
poltura theme rollback --revision <id> --waitopen 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.
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
poltura theme package [dir] zips the directory (without hidden files, node_modules and dist) into <name>.zip, or into the file --out <file> names.