@tiendanube/cli

An Official CLI to automate theme development and interact with Tiendanube / Nuvemshop backend.

Both tiendanube and nuvemshop run the same CLI. Examples below use tiendanube; substitute nuvemshop freely.

Table of contents

• Requirements
• Installation
• Quick start
• Commands
  • Theme, FTP
  • End-to-end example: FTP workflow
  • Theme, Fork (Public API)
  • End-to-end example: Fork workflow
• OS compatibility
• Official documentation
• Uninstallation
• Legal

Requirements

• Node.js 24.15 or newer.

Installation

npm install -g @tiendanube/cli

Verify (either binary):

tiendanube --help
tiendanube --version
nuvemshop --help

Run without a global install:

npx --package=@tiendanube/cli tiendanube --help
npx --package=@tiendanube/cli nuvemshop --help

(Use npx @tiendanube/cli instead of tiendanube in the examples below when using npx.)

Quick start

1. Create a folder for your theme and open a terminal there.
2. Pick a sync mode (see CLI Official Documentation to choose):
   • FTP: run tiendanube theme ftp setup (FTP credentials and store URL).
   • Fork (Public API): run tiendanube theme authorize (sign in via the browser and paste the token).
3. Download the theme (required before push or watch, so the local folder mirrors the remote state):
   • FTP: tiendanube theme ftp pull.
   • Fork: find the installation id with tiendanube theme installation list, then run tiendanube theme pull --installation-id <id>. The id is saved as the default in .nube, so later commands do not need --installation-id again. If you do not have an installation yet, create one first with tiendanube theme installation create --theme-code "<code>" --title "<title>" and use the id it prints.
4. Edit files locally.
5. Push or watch your changes:
   • FTP: tiendanube theme ftp push or tiendanube theme ftp watch.
   • Fork: tiendanube theme push or tiendanube theme watch.

For a full examples, see End-to-end example: Fork workflow and End-to-end example: FTP workflow.

Commands

Theme (FTP)

| Command | Description | |--------|-------------| | theme ftp setup | Configure FTP and store URL | | theme ftp pull | Download theme files from FTP | | theme ftp push | Upload local files to FTP | | theme ftp watch | Watch files, sync to FTP, optionally reload the storefront in a browser |

Run tiendanube theme --help (or nuvemshop theme --help) to list subcommands.

theme ftp setup

Required: --ftp-server, --ftp-username, --ftp-password, --store-url

Optional: -y (skip non-empty directory warning), -v (verbose FTP)

tiendanube theme ftp setup \
  --ftp-server ftp.nuvemshop.com.br \
  --ftp-username my_username \
  --ftp-password my_password \
  --store-url https://mystore.lojavirtualnuvem.com.br/

Tip: Find your FTP credentials in the FTP Workflow Official Documentation.

theme ftp setup writes .nube with FTP settings and your store URL. It is obfuscated, not encrypted.

Do not commit or share it. Add .nube to .gitignore.

theme ftp pull / theme ftp push

Optional: -y (skip overwrite confirmation), -v (verbose FTP)

theme ftp watch

Optional: --no-browser (FTP sync only, no Puppeteer), -v (verbose FTP)

Paths that include a hidden segment (a folder or file name starting with ., other than . / ..) are not uploaded or watched — for example .nube, .git, or foo/.bar/file. That keeps local secrets and tooling off the server.

1. File watcher — The CLI watches the theme folder. When you add, change, or delete a file, it uploads or deletes that file on the FTP server (after a short “write finished” debounce so editors that save in multiple steps are handled more safely).
2. Storefront tab (default) — If you do not pass --no-browser, the CLI opens a Chromium window (via Puppeteer), sends you to admin so you can sign in, then navigates to the storefront. After each successful FTP sync, it runs a full page reload on that storefront tab so you see updated theme files from the server.
3. --no-browser — Only step 1 runs: FTP stays in sync; you refresh the store yourself in any browser you prefer.

So “live” feedback = FTP sync + manual full reload of the storefront tab (automated when the browser flow is enabled), not incremental hot patching of CSS/JS inside the page.

If you close the Puppeteer storefront tab, FTP watching continues; the CLI logs that reload was skipped until you use --no-browser or restart.

End-to-end example: FTP workflow

A realistic session, from a fresh folder to start modifying the theme using FTP commands.

# 1. Create a folder and ftp setup the CLI
mkdir my-theme && cd my-theme
tiendanube theme ftp setup --ftp-server "<ftp-server>" --ftp-username "<ftp-username>" --ftp-password "<ftp-password>" --store-url "<store-url>"

# 2. Pull the files locally; this is required before push/watch
tiendanube theme ftp pull 

# 3. Start modifying
# 3.1 Iterate: edit files in your editor while watch syncs and reloads the storefront
tiendanube theme ftp watch

# 3.2 Edit files and run push to completely update the storefront
tiendanube theme ftp push

Theme Fork (Public API)

Use these commands when syncing a sections-based theme via the Public API.

Flow: theme authorize → theme installation list / theme installation create → theme pull / theme push / theme watch → theme installation preview-url for a storefront preview link → theme installation clone to duplicate an installation → theme installation fork to set fork (full theme paths on push) → theme installation publish when the installation should become productive (live theme for the store). Use theme installation delete to remove an installation (destructive).

[!NOTE] The Fork workflow (Public API) is available only for sectionable themes (e.g., Ipanema).

| Command | Description | |---------|-------------| | theme authorize | Authorize the CLI via browser or --token for CI | | theme installation list | List theme installations for the current store | | theme pull | Download all files from an installation | | theme installation get-current | Print the default installation ID | | theme installation create | Create a new installation (--theme-code, --title) | | theme installation clone | Clone an installation to a new one | | theme installation delete | Permanently delete an installation | | theme push | Upload local theme files to an installation | | theme watch | Watch files and push via API on each change | | theme installation fork | Enable fork mode (full theme paths on push) | | theme installation preview-url | Print the store preview URL for the installation | | theme installation publish | Make the installation live (productive) |

.nube: Same file as FTP, it's obfuscated, not encrypted. It can hold either FTP config or API config, or both blocks merged if you switch modes. Do not commit it.

theme authorize

Default: opens your default browser (macOS, Linux, or Windows). Sign in, then paste the token the page shows when prompted. The CLI saves the configuration locally.

Optional: --token <token> — same string you would paste after the browser step; skips the browser and the prompt (typical for scripts or CI). --token must be the full value from the page (JSON with store_id and access_token, Base64-encoded), not only the raw API access token.

Optional: -y (skip non-empty directory warning), -v (verbose HTTP).

If verification fails, you’ll see an error after the file is written — fix the token or API settings and run again.

tiendanube theme authorize --token "<token-from-authorize-page>" -y

theme installation list

Default: Prints an aligned table (id, store_id, title, theme_id, version, theme_type, prod, fork).

Optional: --json (full API JSON), -v (verbose HTTP).

tiendanube theme installation list --json

theme pull

Required on first run: --installation-id — saves as default on success; subsequent runs use the saved value automatically.

Optional: -y (skip publish confirmation), -v (verbose HTTP).

tiendanube theme pull --installation-id "1234567"

theme installation get-current

Print the default installation ID (saved by theme pull)

tiendanube theme installation get-current

theme installation create

Create a new installation. Print the created resource JSON (includes the new installation id).

Required: --theme-code, --title
Optional: -v (verbose HTTP).

tiendanube theme installation create --theme-code "123" --title "My New Installation"

theme installation clone

Creates a new installation identical to the source; JSON in the response is printed (often includes the new installation ID).

Optional: --installation-id (defaults to the id saved by theme pull), -y (skip clone confirmation), -v (verbose HTTP).

tiendanube theme installation clone

theme installation delete

DELETE an installation. Permanent — removes from default if it pointed at this ID. It does not remove local files.

Optional: --installation-id (defaults to the id saved by theme pull), -y (skip delete confirmation), -v (verbose HTTP).

tiendanube theme installation delete

theme push

Upload local theme files to an installation.

Optional: --installation-id (defaults to the id saved by theme pull), -y (skip publish confirmation), -v (verbose HTTP).

tiendanube theme push

theme watch

Watch files and push via API on each file change. If browser enabled, full-reload page.

Hidden path segments (.nube, .git, etc.) are ignored, same as FTP.

Optional: --installation-id (defaults to the id saved by theme pull), --no-browser (no Chromium, no reload; API sync only), -v (verbose HTTP).

tiendanube theme watch

theme installation fork

Sets fork to true so pushes may include the full theme tree (see theme pull / theme push fork rules).

Optional: --installation-id (defaults to the id saved by theme pull), -y (skip fork confirmation), -v (verbose HTTP).

tiendanube theme installation fork

theme installation preview-url

Prints one line — your store preview URL for the installation in use.

Optional: --installation-id (defaults to the id saved by theme pull)

tiendanube theme installation preview-url

theme installation publish

Publishing turns the installation PRODUCTIVE (live theme for customers; aligns with the prod column in theme installation list).

Optional: --installation-id (defaults to the id saved by theme pull), -y (skip publish confirmation), -v (verbose HTTP).

tiendanube theme installation publish

End-to-end example: Fork workflow

A realistic session, from a fresh folder to publishing a new theme. Replace <id-from-output> with the id printed by theme installation create.

# 1. Create a folder and authorize the CLI (browser flow)
mkdir my-theme && cd my-theme
tiendanube theme authorize

# 2a. Either list existing installations and pick one
tiendanube theme installation list
#     ...or create a new one from a theme code
tiendanube theme installation create --theme-code "123" --title "Dev"

# 3. Pull the files locally; this is required before push/watch
#    and it saves the id as the default
tiendanube theme pull --installation-id "<id-from-step-2>"

# 4. (Optional) lift push restrictions if you'll edit outside custom/, templates/, settings_data.json
tiendanube theme installation fork -y

# 5. Iterate: edit files in your editor while watch syncs and reloads the storefront
tiendanube theme watch

# 6. Share a preview link with your team
tiendanube theme installation preview-url

# 7. Ship it: make this installation the live theme
tiendanube theme installation publish -y

For CI or scripts, swap step 1 for tiendanube theme authorize --token "<token>" to skip the browser entirely.

OS compatibility

The CLI is Node.js-based and is intended to work on Windows, macOS, and Linux the same way you run any global npm binary.

Official documentation

For guides on stores, themes, FTP, and the platform (language and region may vary):

• Tiendanube / Nuvemshop: CLI DevHub Documentation

Search those sites for FTP, tema, or theme to reach the articles that match your storefront product.

Uninstallation

If you installed globally:

npm uninstall -g @tiendanube/cli

If you only used npx, there is nothing to remove globally; stop using the command or clear npm’s cache if you need to reclaim disk space from cached packages (npm cache clean --force — affects all cached packages, not only this CLI).

Legal

Use of this package is subject to your agreements with Tiendanube / Nuvemshop. Distribution terms for the published artifact are defined in the license field of package.json on the registry.