@tiendanube/cli

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

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

Requirements

Node.js 24.15 or newer.

Installation

npm install -g @tiendanube/cli

Verify (either binary):

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

Run without a global install:

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

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

Quick start

Create a folder for your theme and open a terminal there.
Set up a sync mode (see CLI Official Documentation to choose):
- FTP: run nuvemshop theme ftp setup (FTP credentials and store URL).
- Fork (Public API): run nuvemshop theme authorize (sign in via the browser and paste the token).
You can run both in the same folder — they are not exclusive. That is useful even for a classic theme, since the theme management commands (theme list, theme create, theme publish, theme delete) exist only in the Fork family.
Download the theme (required before push or watch, so the local folder mirrors the remote state):
- FTP: tiendanube theme ftp pull.
- Fork: find the theme id with tiendanube theme list, then run tiendanube theme pull --theme-id <id>. The id is saved as the default in .nuvem, so later commands do not need --theme-id again. If you do not have a theme yet, create one first with tiendanube theme create --base-theme "ipanema" --title "<title>" and use the id it prints.
Edit files locally.
Push or watch your changes:
- FTP: nuvemshop theme ftp push or nuvemshop theme ftp watch.
- Fork: nuvemshop theme push or nuvemshop 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 nuvemshop theme --help (or tiendanube 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)

nuvemshop 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 .nuvem with FTP settings and your store URL. It is obfuscated, not encrypted. It does not remove Public API credentials already in the file, and the Fork commands keep working alongside it — see Theme Fork (Public API).

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

`theme ftp pull`

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

`theme ftp push`

Optional: -y (skip overwrite confirmation), -v (verbose FTP), --force (skip remote comparison and upload all files; also overrides the refusal to push a tree pulled over the Public API)

`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 .nuvem, .git, or foo/.bar/file. That keeps local secrets and tooling off the server.

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).
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.
--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
nuvemshop 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
nuvemshop theme ftp pull 

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

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

Theme Fork (Public API)

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

Flow: theme authorize → theme list / theme create → theme pull / theme diff / theme push / theme watch → theme preview for a storefront preview link → theme clone to duplicate a theme → theme fork to set fork (full theme paths on push) → theme publish when the theme should become productive (the live theme for the store). Use theme delete to remove a theme (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 list`	List the themes available for the current store
`theme pull`	Download all files from a theme
`theme current`	Print the default theme ID
`theme create`	Create a new theme (`--base-theme`, `--title`)
`theme clone`	Clone a theme to a new one
`theme delete`	Permanently delete a theme
`theme diff`	Show what a push would change, without uploading
`theme push`	Upload local files to a theme
`theme watch`	Watch files and push via API on each change
`theme fork`	Enable fork mode (full theme paths on push)
`theme update`	Update a theme to a newer base-theme version, as a new draft
`theme preview`	Print a shareable preview URL for the theme
`theme performance`	Run a Lighthouse performance report on the current theme
`theme publish`	Make the theme live (productive)

.nuvem: Same file as FTP, it's obfuscated, not encrypted. Do not commit it.

It holds the FTP block, the API block, or both — and both command families work from the same directory, so you can run theme list or theme create while syncing a classic theme over FTP. Each family needs only its own credentials: an API command that finds no API block tells you to run theme authorize, it does not declare the directory an FTP-only one.

To keep the two from mixing, the CLI records which family last pulled, and a push refuses a tree that came from the other one — uploading a sections-based theme to a classic one (or the reverse) would overwrite it with the wrong kind of files. Run the matching pull first, or pass --force to upload anyway; the confirmation says when --force is doing that. watch refuses outright, since it pushes on every save. A workspace that has never pulled — a fresh clone from git, for example — is not blocked.

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

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

`theme list`

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

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

nuvemshop theme list --json

`theme pull`

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

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

nuvemshop theme pull --theme-id "1234567"

`theme current`

Print the default theme ID (saved by theme pull)

nuvemshop theme current

`theme create`

Create a new theme. Prints the new theme id on success.

Currently only ipanema is accepted as --base-theme. Support for additional base themes is planned.

Required: --base-theme, --title
Optional: --base-theme-variant (letters only, first letter uppercase, e.g. Clothing; when omitted, the API defaults to Clothing), --json (machine-readable JSON output), -v (verbose HTTP).

nuvemshop theme create --base-theme "ipanema" --title "My New Theme" --base-theme-variant "Clothing"

`theme clone`

Creates a new theme identical to the source; prints the new theme id on success.

Optional: --theme-id (defaults to the id saved by theme pull), --published (resolve the store's published theme via API), -y (skip clone confirmation), --json (machine-readable JSON output), -v (verbose HTTP).

nuvemshop theme clone

`theme delete`

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

Optional: --theme-id (defaults to the id saved by theme pull), -y (skip delete confirmation), --json (machine-readable JSON output), -v (verbose HTTP).

nuvemshop theme delete

`theme diff`

Shows what a theme push would change — which files are new, which would be updated, and which would be deleted — without uploading anything. Files that push would skip (like custom/, or theme code on a theme that is not forked) are listed as skipped, not as changes. Reformatting a JSON file does not count as a change.

Default: prints a summary grouped by change type, with one line per file.

Optional: --theme-id (defaults to the id saved by theme pull), --published (resolve the store's published theme via API), --detailed (also show a git-style diff of what changed inside each file), --json (machine-readable JSON output; with --detailed each file also carries its diff as a patch string), -v (verbose HTTP).

nuvemshop theme diff
nuvemshop theme diff --detailed
nuvemshop theme diff --json --detailed

`theme push`

Upload local files to a theme.

Optional: --theme-id (defaults to the id saved by theme pull), -y (skip publish confirmation), -v (verbose HTTP), --force (upload all files without remote comparison, skipping unchanged detection; also overrides the refusal to push a tree pulled over FTP).

nuvemshop theme push

`theme watch`

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

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

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

nuvemshop theme watch

`theme fork`

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

Optional: --theme-id (defaults to the id saved by theme pull), --published (resolve the store's published theme via API), -y (skip fork confirmation), --json (machine-readable JSON output), -v (verbose HTTP).

nuvemshop theme fork

`theme update`

Updates a theme to a newer version of its base theme by creating a new draft — the source theme is left untouched. The CLI asks the API which versions the theme can move to (they differ per theme: an exact version for a forked theme, a major for a non-forked one), then dry-runs the update to report which local edits would be discarded before doing anything.

Optional: --theme-id (defaults to the id saved by theme pull), --to <version> (target version; a forked theme takes an exact version like 2.3.1, a non-forked one a major like 2; omit to pick from the available versions), --title <title> (title for the new draft; defaults to '<source> (<version>)'), --dry-run (only report which local edits the update would discard, without creating anything), -y (skip the update confirmation), --json (machine-readable JSON output), -v (verbose HTTP).

nuvemshop theme update
nuvemshop theme update --to 2 --dry-run
nuvemshop theme update --to 2.3.1 -y

`theme preview`

Prints one line — a shareable preview URL for the theme in use. Use it before theme publish to review the storefront without making the theme live.

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

nuvemshop theme preview

`theme performance`

Runs a Lighthouse performance audit against the storefront preview URL for the theme in use, for both mobile and desktop, and prints a separate report per device with the overall performance score plus the key metrics (First Contentful Paint, Speed Index, Largest Contentful Paint, Total Blocking Time, Cumulative Layout Shift, Time to Interactive). Uses the Chromium bundled with the CLI, so no extra setup is needed. The audit runs headless and can take a minute or two.

Default: prints a human-friendly, color-coded report for each device.

Optional: --theme-id (defaults to the id saved by theme pull), --published (resolve the store's published theme via API), --detailed (also list the recommended changes from the Lighthouse report — failing opportunities/diagnostics, worst impact first, each with concrete examples of the offending URLs/elements and their per-item savings), --json (machine-readable JSON output; results are keyed by device under results.mobile and results.desktop, with a recommendations array — including examples — per device when combined with --detailed).

nuvemshop theme performance
nuvemshop theme performance --detailed
nuvemshop theme performance --json

`theme publish`

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

Optional: --theme-id (defaults to the id saved by theme pull), -y (skip publish confirmation), --json (machine-readable JSON output), -v (verbose HTTP).

nuvemshop theme 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 create.

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

# 2a. Either list existing themes and pick one
nuvemshop theme list
#     ...or create a new one from a base catalog theme
nuvemshop theme create --base-theme "ipanema" --title "Dev"

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

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

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

# 5b. (Optional) review what a push would change before uploading
nuvemshop theme diff --detailed

# 6. Share a preview link with your team
nuvemshop theme preview

# 6b. (Optional) check the theme's performance before shipping
nuvemshop theme performance

# 7. Ship it: make this theme the live one
nuvemshop theme publish -y

For CI or scripts, swap step 1 for nuvemshop 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.

Anonymous usage data

The CLI collects anonymous usage data by default. It starts reporting on the first command and keeps doing so until you opt out.

Opting out is one command:

nuvemshop telemetry disable

The goal of collecting it is narrow: know which commands people actually use and which ones fail, so we fix the right things.

What is collected

the command you ran, such as theme push
whether it succeeded, failed, or was cancelled, and how long it took
for failures: the error class and its stable code, for example ThemeApiError / THEME_NOT_SECTIONABLE
the CLI, Node.js, and operating system versions, the CPU architecture, and whether the run was in CI
a random id, generated on your machine, that identifies the installation and nothing else

What is never collected

store ids, account data, or anything identifying you or your shop
file names, file contents, or directory listings
credentials, tokens, or FTP configuration
command arguments, flag values, or error messages

Error messages are excluded deliberately: they can contain file paths and ids, so only the error class and code are reported.

Managing it

nuvemshop telemetry status     # show the current setting, id, and config file location
nuvemshop telemetry disable    # stop sending anything
nuvemshop telemetry enable     # start again

tiendanube telemetry ... does the same thing — both bins share one setting. disable deletes the random id, so disable followed by enable gives you a brand new one.

Environment variables override the stored setting for whatever environment they are set in:

export NUVEMSHOP_CLI_TELEMETRY_ENABLED=0     # force off, including in CI
export NUVEMSHOP_CLI_TELEMETRY_ENABLED=1     # force on, even where something else turned it off
export DO_NOT_TRACK=1                        # respected by many developer tools

TIENDANUBE_ works as a prefix everywhere NUVEMSHOP_ does, and ..._CLI_TELEMETRY_DISABLED=1 is accepted as an alias for ..._ENABLED=0. Variables never change the stored setting — unset them and your original choice is back.

Continuous integration

CI runs report like any other run, and by default they are treated as one-off executions rather than as people: the random id is generated per run and never written to disk, and every event is tagged so it counts as activity and never as a returning user.

To turn it off for a pipeline, set this in that environment:

NUVEMSHOP_CLI_TELEMETRY_ENABLED=0

One exception, for self-hosted runners: if the machine already has an id stored — because someone ran the CLI on it by hand — that id is reused instead of a per-run one, and its runs are tagged as a returning user like any other run from that machine. It is still marked as CI, so it can be filtered out separately. A stored opt-out is respected there too, and takes precedence over this per-run default — though ..._CLI_TELEMETRY_ENABLED=1 still overrides it, as everywhere else.

Non-interactive runs

Nothing is ever printed about telemetry and nothing is ever asked, so scripted, piped, and --yes runs behave exactly like interactive ones: never blocked, and never with stdout corrupted for | jq.

The setting lives in one file per user, shared by the tiendanube and nuvemshop commands:

OS	Location
Linux	`$XDG_CONFIG_HOME/tiendanube-cli/config.json`, or `~/.config/tiendanube-cli/config.json`
macOS	`~/.config/tiendanube-cli/config.json`
Windows	`%APPDATA%\tiendanube-cli\config.json`

Deleting that file clears your choice, which means collection returns to being on, with a new random id.

Official documentation

The developer portal holds the full guides for the CLI, themes, and the platform:

CLI documentation — a page per workflow, Fork (Public API) and FTP, plus theme development and theme installations.

Use the language selector in the portal to read it in Portuguese, Spanish, or English.

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 Nuvemshop / Tiendanube. Distribution terms for the published artifact are defined in the license field of package.json on the registry.

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
README.md		README.md
biome.json		biome.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.js		tsup.config.js
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

@tiendanube/cli

Table of contents

Requirements

Installation

Quick start

Commands

Theme (FTP)

theme ftp setup

theme ftp pull

theme ftp push

theme ftp watch

End-to-end example: FTP workflow

Theme Fork (Public API)

theme authorize

theme list

theme pull

theme current

theme create

theme clone

theme delete

theme diff

theme push

theme watch

theme fork

theme update

theme preview

theme performance

theme publish