Theme Development

Use theme pull, theme push, and theme watch to sync files between your local machine and a theme installation on your store via the Fork workflow.

info

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

Pull

Download all theme files from a theme installation to your local working directory:

tiendanube theme pull

The CLI fetches every file in the installation and writes them to your current directory, preserving the theme's folder structure:

my-theme/
├── blocks/            ← Block templates (.tpl)
├── config/            ← Settings schema and merchant settings
├── layouts/           ← Main HTML shell
├── locales/           ← Translation files
├── sections/          ← Section templates (.tpl)
├── snippets/          ← Shared partials (.tpl)
├── static/            ← CSS, JS, and other assets
├── templates/         ← Page templates (.json)
└── manifest.json      ← Generated by the CLI (not part of the theme)

manifest.json

After pulling, the CLI generates a manifest.json file in your working directory with metadata about the installation:

{
  "theme": "ipanema",
  "theme_version": "1.0.0",
  "forked": false,
  "revision_token": "<REVISION_TOKEN>",
  "installation_id": "4541834"
}

This file is local only — it's never uploaded when you push or watch. It helps you keep track of which installation and revision your local files came from.

Options

Option	Description
--installation-id <id>	Target a specific installation (defaults to the installation linked to this directory in .nube)
-y	Skip confirmation prompts
-v	Enable verbose output

danger

Pulling overwrites local files. If you have uncommitted changes, commit or stash them before pulling.

Push

Upload your local theme files to the theme installation:

tiendanube theme push

The CLI reads each local file, determines its format based on the file extension, and uploads it to the installation:

Extension	Upload format
.json	Parsed and sent as JSON
.tpl, .css, .js, .svg	Sent as text
Everything else	Sent as base64-encoded binary

Options

Option	Description
--installation-id <id>	Target a specific installation (defaults to the installation linked to this directory in .nube)
-y	Skip confirmation prompts
-v	Enable verbose output

What gets uploaded

The CLI uploads all files in your working directory, with these exclusions:

• Dot-prefixed paths — files and directories starting with . (like .nube, .git, .vscode) are always skipped
• manifest.json — the local manifest is never uploaded
• Fork-restricted paths — if the installation is not forked, only custom/, templates/, and config/settings_data.json can be pushed (see below)

Empty files (zero bytes) are not exclusions — they trigger a per-file upload error, and the overall push reports as failed.

Fork rules

Before pushing, the CLI checks whether the target installation is forked. This determines which files you're allowed to upload:

Non-forked installation — you can only push customization files:

• custom/** — custom files
• templates/** — page templates (.json)
• config/settings_data.json — merchant settings

Forked installation — you can push any file in the theme.

Files outside the allowed paths are silently skipped. If you need to modify layouts, sections, blocks, or other theme code, fork the installation first.

Watch

Watch your local files and automatically push changes on save:

tiendanube theme watch

Watch mode monitors your working directory for changes. When you save a file, it's uploaded to the installation immediately. When you delete a file locally, it's deleted from the installation too.

The same upload rules and fork restrictions from theme push apply — watch mode won't upload files that push would skip.

Browser reload

By default, the CLI opens a Puppeteer-driven browser window showing the storefront with the ?theme_installation_id=<id> preview parameter, so you see the installation you're working on (not the productive one). After each successful push or delete, the page is automatically reloaded. Use --no-browser to skip this.

tip

The browser feature uses Puppeteer, which may need to download Chromium on first run. Use --no-browser to skip this and rely on manual browser testing instead.

Options

Option	Description
--installation-id <id>	Target a specific installation (defaults to the installation linked to this directory in .nube)
--no-browser	Don't open or reload a browser window
-v	Enable verbose output

Typical development workflow

A common development cycle looks like this:

1. Create or clone an installation to work on: tiendanube theme installation clone
2. Pull the installation files (links the directory to that installation): tiendanube theme pull --installation-id ID
3. Fork if you need to edit theme code: tiendanube theme installation fork
4. Start watch mode: tiendanube theme watch
5. Edit templates, sections, and settings in your editor — changes sync automatically
6. Preview with the auto-reloading browser, or generate a link: tiendanube theme installation preview-url
7. Publish when ready: tiendanube theme installation publish