Theme Installations
A theme installation is a store-scoped instance of a theme — a working copy with its own files, settings, and state. Your store has one that is productive (live on the storefront) and can have a second one that serves as a draft or experiment.
A store can have a maximum of two installations at any given moment. If you've reached the limit and want to start a new one, delete an existing non-productive installation first to free up the slot.
The Nuvemshop CLI lets you manage the full lifecycle of installations from your terminal:
create → pull → push/watch → fork (optional) → publish → delete
theme pull --theme-id <id> saves the installation ID in .nuvem, so subsequent commands target it without needing --theme-id each time.
Before using these commands, run theme authorize to connect the CLI to your store. See Fork workflow for setup instructions.
Theme installations and the fork workflow are available only for the Ipanema theme, which is still being rolled out and may not be available to every store yet. For legacy themes with FTP enabled, use the FTP workflow (legacy) .
List
List all theme installations on your store:
nuvemshop theme list
The output shows each installation's ID, title, theme version, whether it's productive (live), whether it's been forked, and whether it's archived. The archived column flags archived installations — older installations that have been shelved and are no longer in active use. Use --json for machine-readable output:
nuvemshop theme list --json
Options
| Option | Description |
|---|---|
--json | Output as JSON instead of a table |
--token <token> | Authentication token (CI use ) |
-v | Enable verbose output |
Create
Create a new installation from a theme code:
nuvemshop theme create --base-theme ipanema --title "My Theme"
This creates a fresh installation based on the specified base theme's default files and settings. Currently, the only supported value for --base-theme is ipanema. Support for additional themes is planned for future releases.
Options
| Option | Description |
|---|---|
--base-theme <name> | Required. Base theme to create the installation from (currently only ipanema) |
--title <name> | Required. A human-readable name for the installation |
--json | Output as JSON |
--token <token> | Authentication token (CI use ) |
-v | Enable verbose output |
Selecting the active installation
There is no separate checkout command. The CLI links a directory to an installation when you run:
nuvemshop theme pull --theme-id THEME_ID
After a successful pull, the installation ID is saved in .nuvem. Subsequent commands like theme push, theme watch, and theme publish/fork/clone/delete/preview automatically target this installation when --theme-id is omitted.
To check which installation the current directory is linked to:
nuvemshop theme current
Clone
Create an identical copy of an existing installation:
nuvemshop theme clone
Unlike create (which starts from the base theme's defaults), clone duplicates an existing installation — including any file modifications, settings changes, and customizations you've made. This is useful when you want to experiment with changes without affecting your current work.
Options
| Option | Description |
|---|---|
--theme-id <id> | The installation to clone (defaults to the installation linked to this directory) |
--title <title> | Title for the new installation (defaults to <source> (copy)) |
--published | Use the store's published theme instead of --theme-id or .nuvem |
--json | Output as JSON |
--token <token> | Authentication token (CI use ) |
-y | Skip confirmation prompts |
-v | Enable verbose output |
Fork
Forking installations is coming soon. We're finalizing a way to keep forked installations always up to date with the base theme, and the feature will be available shortly. For now, running nuvemshop theme fork returns a notice that forking isn't enabled yet.
In the meantime, you can already use the rest of the theme flow (create, pull, push, watch, and publish installations) and customize your store through the customization layer (templates/, custom/, and config/settings_data.json).
Fork an installation to unlock full file access:
nuvemshop theme fork
Why forking exists
An Ipanema theme installation separates theme code from customizations. The theme code is the core of the theme — the layouts, section templates, blocks, styles, and scripts that define how the storefront looks and behaves. Customizations are the parts that vary per store — which sections appear on each page, their settings, and any custom files.
The file tree of a pulled installation looks like this:
my-theme/
├── blocks/ ← Theme code: block templates (.tpl)
├── config/
│ ├── settings_schema.json ← Theme code: defines available settings
│ └── settings_data.json ← Customization: merchant's saved values
├── layouts/ ← Theme code: main HTML shell
├── locales/ ← Theme code: translation files
├── sections/ ← Theme code: section templates (.tpl)
├── snippets/ ← Theme code: shared partials (.tpl)
├── static/ ← Theme code: CSS, JS, assets
├── templates/ ← Customization: page templates (.json)
└── custom/ ← Customization: developer-added files
By default, a non-forked installation protects the theme code and only lets you modify the customization layer:
| Allowed without fork | What it contains |
|---|---|
templates/ | Page templates (.json) — define which sections appear on each page, their order, and their settings |
custom/ | Custom files added by the developer |
config/settings_data.json | The merchant's saved settings values |
This means you can rearrange sections on a page, change settings, or add custom files — but you can't touch the .tpl templates, styles, scripts, or any other core file.
Forking removes this restriction. Once forked, the CLI allows you to push any file in the theme — including layouts, sections, blocks, snippets, static assets, and the settings schema.
When to fork
Don't fork if you only need to:
- Change which sections appear on a page (edit
templates/*.json) - Adjust section settings (edit
templates/*.jsonorconfig/settings_data.json) - Add custom files (add files under
custom/)
This is the safer path — your installation stays compatible with future theme updates.
Fork when you need to:
- Edit a section's HTML/Twig logic (
sections/*.tpl) - Modify block templates (
blocks/*.tpl) - Change the layout shell (
layouts/layout.tpl) - Update styles or scripts (
static/) - Add or modify translations (
locales/) - Change the settings schema (
config/settings_schema.json)
Options
| Option | Description |
|---|---|
--theme-id <id> | The installation to fork (defaults to the installation linked to this directory) |
--published | Use the store's published theme instead of --theme-id or .nuvem |
--json | Output as JSON |
--token <token> | Authentication token (CI use ) |
-y | Skip confirmation prompts |
-v | Enable verbose output |
Forking is a one-way operation on the installation itself. A forked installation can't be turned back into a non-forked one in place — but you can use theme unfork to spin up a new non-forked draft from it while keeping your customizations. If you fork an already-forked installation, the CLI treats it as a no-op.
Only sections-based themes (like Ipanema) can be forked. The API will reject fork requests for non-sectionable themes.
Unfork
Reverse a fork by spinning up a new non-forked draft:
nuvemshop theme unfork
Unlike fork, unfork doesn't modify the source installation. It creates a new installation (draft) that keeps your templates and settings but drops the forked theme code — re-enabling automatic Nuvemshop theme updates. The source installation is left untouched.
Use unfork when you've forked an installation but want to go back to receiving automatic base-theme updates, without losing your customizations (templates/, custom/, and config/settings_data.json).
Options
| Option | Description |
|---|---|
--theme-id <id> | The installation to unfork (defaults to the installation linked to this directory) |
--title <title> | Title for the new installation (defaults to <source> (unforked)) |
--published | Use the store's published theme instead of --theme-id or .nuvem |
--json | Output as JSON |
--token <token> | Authentication token (CI use ) |
-y | Skip confirmation prompts |
-v | Enable verbose output |
Update
Update an installation to a newer version of its base theme, as a new draft:
nuvemshop theme update
update doesn't modify the source installation. It creates a new installation (draft) already on the version you chose, keeping your customizations. The current installation is left untouched, so you can preview the draft and only publish once you're confident.
When it finishes, the CLI reports the new installation's ID. Run theme pull --theme-id <new_id> to download the updated files.
Since update creates a new installation, your store needs a free slot. If two already exist, delete the non-productive one first.
Choosing the version
The available versions depend on the installation, so the CLI asks the API before anything else:
- On a non-forked installation, the target is a major (for example,
2) — it always tracks the latest release of that major. - On a forked installation, the target is an exact version (for example,
2.3.1).
Without --to, the CLI shows the list and asks you to pick. With --to, the value is validated against that same list, and the command fails naming the valid options if it isn't there. If the installation is already on the latest version, the CLI just reports that there is nothing to update.
Previewing first (--dry-run)
Before running it for real, see what the update would do:
nuvemshop theme update --dry-run
The report shows the source version, the target version, and the list of conflicting files — files you modified that will be replaced with the new version's ones. That same report is shown in the confirmation prompt of a real update, so you never confirm blind.
In a non-interactive environment (CI), --dry-run without --to acts as discovery: instead of demanding a target, it lists the current version and the available ones.
In CI
Outside an interactive terminal there's no way to pick from the list, so --to is required and -y skips the confirmation:
# Discover the available versions
nuvemshop theme update --dry-run --json
# Update to one of them
nuvemshop theme update --to 2 -y --json
Options
| Option | Description |
|---|---|
--theme-id <id> | The installation to update (defaults to the installation linked to this directory) |
--to <version> | Target version. A forked installation takes an exact version (2.3.1), a non-forked one a major (2). Omit to choose from the list |
--title <title> | Title for the new installation (defaults to <source> (v<version>)) |
--dry-run | Only report what the update would do, without changing anything |
--published | Use the store's published theme instead of --theme-id or .nuvem |
--json | Output as JSON |
--token <token> | Authentication token (CI use ) |
-y | Skip confirmation prompts |
-v | Enable verbose output |
Base-theme updates reach non-forked installations automatically. theme update is the path for forked installations, which no longer receive those updates, and for when you want to control exactly when the version changes.
Publish
Make an installation the productive (live) theme on your storefront:
nuvemshop theme publish
Publishing makes the installation visible to all visitors. The previously productive installation is demoted — it still exists but is no longer live.
Options
| Option | Description |
|---|---|
--theme-id <id> | The installation to publish (defaults to the installation linked to this directory) |
--json | Output as JSON |
--token <token> | Authentication token (CI use ) |
-y | Skip confirmation prompts |
-v | Enable verbose output |
Publishing replaces the currently live theme. Always test your changes with a preview before publishing.
Preview URL
Get a preview URL for an installation without making it live:
nuvemshop theme preview
This outputs a URL in the format:
https://yourstore.nuvemshop.com.br?theme_installation_id=INSTALLATION_ID
Open it in your browser to see how the installation looks on the storefront. The preview is only visible to you — it doesn't affect what visitors see.
Options
| Option | Description |
|---|---|
--theme-id <id> | The installation to preview (defaults to the installation linked to this directory) |
--published | Use the store's published theme instead of --theme-id or .nuvem |
--token <token> | Authentication token (CI use ) |
Performance
Run a performance report powered by Lighthouse against the current version of the theme:
nuvemshop theme performance
The command runs a Lighthouse audit against the store's preview URL for the installation in use and prints one report per device — mobile and desktop by default — with the overall performance score plus the key metrics (First Contentful Paint, Speed Index, Largest Contentful Paint, Total Blocking Time, Cumulative Layout Shift, and Time to Interactive).
The audit uses the Chromium bundled with the CLI (no extra setup), runs headless, and can take a minute or two.
The command needs the store_url saved in .nuvem. If it isn't present, run theme authorize again to save your storefront URL.
Pick the form factor with --device, include the report's recommendations with --detailed, or get machine-readable output with --json:
nuvemshop theme performance --device mobile
nuvemshop theme performance --detailed
nuvemshop theme performance --json
With --detailed, the report also lists Lighthouse's recommended changes (failing opportunities and diagnostics, worst impact first, with concrete examples). With --json, results are keyed by device under results.mobile and results.desktop.
Options
| Option | Description |
|---|---|
--theme-id <id> | The installation to analyze (defaults to the installation linked to this directory) |
--published | Use the store's published theme instead of --theme-id or .nuvem |
--device <both\|mobile\|desktop> | Which form factor to audit (defaults to both) |
--detailed | Include the recommended changes from the Lighthouse report |
--json | Output as JSON |
--token <token> | Authentication token (CI use ) |
Delete
Delete a theme installation:
nuvemshop theme delete
Options
| Option | Description |
|---|---|
--theme-id <id> | The installation to delete (defaults to the installation linked to this directory) |
--json | Output as JSON |
--token <token> | Authentication token (CI use ) |
-y | Skip confirmation prompts |
-v | Enable verbose output |
Deleting an installation is permanent and cannot be undone. You cannot delete the currently productive installation.
Quick reference
| Command | Description |
|---|---|
theme list | List all installations on the store |
theme create | Create a new installation from a theme code |
theme current | Show the installation linked to this directory |
theme clone | Duplicate an existing installation |
theme fork | Unlock full file access (one-way) |
theme unfork | Create a new non-forked draft, re-enabling updates |
theme update | Create a new draft on a newer base-theme version |
theme publish | Make an installation live on the storefront |
theme preview | Get a preview link without publishing |
theme performance | Run a Lighthouse performance report on the theme |
theme delete | Permanently remove an installation |