Como instalar e usar a CLI da Nuvemshop para editar layouts?
Instale a CLI da Nuvemshop, conecte a loja por FTP ou por autorização no navegador, edite os arquivos do tema localmente e publique depois de revisar na pré-visualização.
Última atualização: 18/09/2026
A CLI da Nuvemshop é a ferramenta de linha de comando oficial para desenvolver layouts na Nuvemshop. Com ela, você edita os arquivos do tema no seu editor, sincroniza as alterações com a loja, gera um link de pré-visualização para aprovação e publica o tema quando estiver pronto, sem depender de um cliente FTP de terceiros.
Importante
A CLI tem dois modos de sincronização. O modo Fork, que usa a API pública, funciona apenas em temas baseados em seções, como o Ipanema. Para temas legados, o modo disponível é o FTP.
O que preciso antes de instalar a CLI?
Confira estes três itens antes de começar:
Node.js 24.15 ou superior instalado na sua máquina;
Uma pasta local vazia para receber os arquivos do tema;
As credenciais de FTP da loja, no modo FTP, ou acesso ao painel administrador para autorizar a CLI, no modo Fork.
Como instalar a CLI da Nuvemshop?
Vamos aos passos!
1. Abrir o terminal do seu computador.
2. Executar o comando de instalação: npm install -g @tiendanube/cli
3. Conferir se a instalação funcionou com nuvemshop --version
Pronto!
A CLI está instalada e disponível no seu terminal.
Observação
Os comandos nuvemshop e tiendanube executam a mesma CLI, então você usa o que preferir. Para testar sem instalar globalmente, execute npx --package=@tiendanube/cli nuvemshop --help.
Como conectar a CLI à minha loja?
A conexão vale para a pasta em que você executa os comandos, então crie a pasta do tema e abra o terminal nela antes de começar. Escolha o modo conforme o layout da loja:
Neste modo, o CLI se conecta com a loja utilizando as mesmas credenciais de FTP já existentes no painel. Ele baixa o tema atual e sincroniza automaticamente as alterações.
O desenvolvedor deve usar o seguinte passo a passo:
1. Executar nuvemshop theme ftp setup informando os parâmetros --ftp-server, --ftp-username, --ftp-password e --store-url.
2. Baixar os arquivos do tema com nuvemshop theme ftp pull. Esse passo é obrigatório antes de enviar ou acompanhar alterações, para que a pasta local reflita o que está na loja.
Para temas desenvolvidos a partir do Ipanema, o desenvolvedor trabalha em um Fork (cópia isolada) e valida as mudanças antes do go-live.
O desenvolvedor deve usar o seguinte passo a passo:
1. Executar nuvemshop theme authorize.
2. Fazer login na página que abre no navegador e copiar o token exibido na tela.
3. Colar o token no terminal quando ele for solicitado.
4. Listar os temas da loja com nuvemshop theme list e localizar o id do tema que vai editar.
5. Baixar os arquivos com nuvemshop theme pull --theme-id <id>. O id fica salvo como padrão, então os comandos seguintes não precisam dele.
Se a loja ainda não tem um tema para editar, crie um antes com nuvemshop theme create --base-theme "ipanema" --title "<título>" e use o id que o comando devolve.
Dica
A configuração fica salva no arquivo .nuvem da pasta do layout. Ele é ofuscado, e não criptografado, então inclua .nuvem no .gitignore e não compartilhe nem versione esse arquivo.
Como editar e enviar as alterações do tema?
Com os arquivos na pasta local, você edita no seu editor e usa os comandos abaixo para sincronizar. Clique em cada tarefa para ver os detalhes:
Executar nuvemshop theme watch, no modo Fork, ou nuvemshop theme ftp watch, no modo FTP.
A CLI observa a pasta do tema e, a cada arquivo salvo, envia a alteração para a loja. Por padrão ela também abre uma janela do Chromium, leva você ao painel para fazer login e depois navega até a loja, recarregando a página a cada sincronização.
Para sincronizar sem abrir o navegador, acrescentar --no-browser e recarregar a loja por conta própria.
Arquivos e pastas que começam com ponto, como .nuvem e .git, não são enviados nem observados.
Executar nuvemshop theme diff para ver quais arquivos seriam criados, atualizados ou removidos, sem enviar nada para a loja.
Para ver também o que mudou dentro de cada arquivo, acrescentar --detailed.
Os arquivos que o envio ignoraria aparecem como ignorados, e não como alterações. Esse comando está disponível no modo Fork.
Executar nuvemshop theme push, no modo Fork, ou nuvemshop theme ftp push, no modo FTP.
A CLI compara os arquivos locais com os da loja e envia apenas o que mudou. Para enviar todos os arquivos sem essa comparação, acrescentar --force.
Executar nuvemshop theme fork.
Sem esse comando, o envio fica restrito a algumas pastas e arquivos do tema. Depois de ativar o modo fork, o envio pode incluir a árvore completa do tema, o que é necessário quando você edita arquivos fora de custom/, templates/ e settings_data.json.
O terminal confirma a operação informando que o tema foi forkado e que fork agora é verdadeiro.
Como pré-visualizar e publicar o tema?
Antes de deixar o tema no ar, você consegue revisar o resultado e medir a performance dele. Clique em cada tarefa para ver os detalhes:
Executar nuvemshop theme preview.
O comando devolve um link da loja com o identificador do tema, que você pode compartilhar para aprovação sem que o tema fique no ar para quem compra.
Executar nuvemshop theme performance.
A CLI roda uma auditoria de performance na pré-visualização do tema, para celular e para computador, e mostra um relatório por dispositivo com a nota geral e as métricas principais.
Para receber também a lista de recomendações de melhoria, acrescentar --detailed. A auditoria pode levar alguns minutos.
Executar nuvemshop theme publish.
A publicação torna esse tema o tema produtivo da loja, ou seja, o que os clientes passam a ver. O terminal confirma informando que o tema foi publicado.
Importante
Antes de publicar em loja de cliente, confirme que ninguém está editando o tema que está no ar, e use o link de pré-visualização para aprovar o resultado.
Como gerenciar os temas da loja pela CLI?
Além de editar, a CLI cria, duplica, atualiza e exclui temas. Clique em cada tarefa para ver os detalhes:
O comando devolve o id do tema criado. No momento, o tema base aceito é o ipanema.
Executar nuvemshop theme clone.
A CLI cria um tema idêntico ao de origem e devolve o id do novo tema. É o caminho para trabalhar em uma cópia sem tocar no tema que está no ar.
Executar nuvemshop theme update.
A atualização cria um rascunho novo em uma versão mais recente do tema base, e o tema de origem permanece intacto. Antes de criar qualquer coisa, a CLI informa quais edições locais seriam descartadas.
Para apenas ver esse relatório, sem criar o rascunho, acrescentar --dry-run.
Executar nuvemshop theme delete.
A exclusão é permanente e não tem volta. Ela remove o tema da loja, mas não apaga os arquivos da sua pasta local.
Perguntas frequentes
Depende do tema da loja. O modo Fork, que usa a API pública, funciona apenas em temas baseados em seções, como o Ipanema, e é onde estão os comandos de pré-visualização, diff, performance e publicação.
O modo FTP atende os temas legados e cobre configuração, download, envio e acompanhamento das alterações.
Os dois modos gravam a configuração no mesmo arquivo .nuvem, então é possível ter as duas configurações na mesma pasta.
Sim, a CLI coleta dados anônimos de uso por padrão, para identificar quais comandos as pessoas usam e quais falham.
São coletados o comando executado, se ele funcionou ou falhou, quanto tempo levou, as versões da CLI, do Node.js e do sistema operacional, e um identificador aleatório gerado na sua máquina.
Não são coletados dados da loja ou da conta, nomes ou conteúdos de arquivos, credenciais, tokens, configuração de FTP, argumentos de comando nem mensagens de erro.
Para conferir a configuração atual, executar nuvemshop telemetry status. Para desativar, executar nuvemshop telemetry disable.
A CLI é baseada em Node.js e funciona em Windows, macOS e Linux da mesma forma que qualquer outro pacote npm instalado globalmente.
Se você instalou globalmente, executar npm uninstall -g @tiendanube/cli.
Se você usou apenas o npx, não há nada para remover, basta parar de usar o comando.
Para a referência completa dos comandos e dos parâmetros de cada um, consultar a documentação oficial da CLI.
