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.

Two installations at a time

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 Tiendanube/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.

info

Before using these commands, run theme authorize to connect the CLI to your store. See Fork workflow for setup instructions.

Ipanema theme only

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:

tiendanube 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:

tiendanube 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:

tiendanube 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:

tiendanube 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:

tiendanube theme current

Clone

Create an identical copy of an existing installation:

tiendanube 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

Coming soon

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 tiendanube 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:

tiendanube 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/*.json or config/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

danger

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.

info

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:

tiendanube 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/Tiendanube 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

Publish

Make an installation the productive (live) theme on your storefront:

tiendanube 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

danger

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:

tiendanube theme preview

This outputs a URL in the format:

https://yourstore.mitiendanube.com?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:

tiendanube 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.

info

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:

tiendanube theme performance --device mobile
tiendanube theme performance --detailed
tiendanube 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:

tiendanube 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

danger

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 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