Getting started
Fork a theme, edit it locally with the CLI, and publish your first change.
This walkthrough takes you from nothing to a published change in a custom theme.
1. Get a Theme Access token
A merchant grants you a scoped API key from their dashboard under
Settings → Developer access. The key is scoped to themes only — it can edit
and publish theme code but can never flip the live theme, buy a paid theme, or
touch orders or customers. See Authentication.
You’ll receive a store URL and a key that begins with sk_.
2. Install the CLI
npm install -g @cartisto/cli
cartisto --version
3. Log in and pull a theme
cartisto login --store your-store.cartisto.app --key sk_xxxxxxxxxxxx
cartisto theme list
cartisto theme pull # downloads the active custom theme into ./
pull writes the theme’s files into your working directory and a
.cartisto/theme.json mapping so subsequent push/pull know which theme and
which file versions you have.
4. Edit with live preview
cartisto theme dev
dev watches your files and pushes each save as a draft, then prints a
?previewTheme=<id> URL. The live storefront is untouched — only you, previewing
with that URL, see the draft.
5. Validate and publish
cartisto theme validate # runs the same checks the server enforces
cartisto theme push --publish
validate runs the Quality Gate locally so
you find problems before the server does. push --publish uploads your changes
and promotes the draft to live — but only if it passes the gate.
Fork from scratch
No theme yet? cartisto theme init my-theme creates a fresh custom theme (a
fork of the platform starter), pulls it locally, and leaves you ready to edit.
What you just learned
- Themes are code you edit locally and publish through a gate.
- Every edit is a draft until you publish — the money path and the live store are never at risk from a work-in-progress.
- The CLI, the dashboard editor, and the server publish path all enforce the same contract — see Quality gate.