Instalação
A CLI é um único binário sem dependências — não é preciso ter Node.js.
O instalador baixa a última release para o seu sistema e processador (x64 ou ARM), verifica o checksum SHA-256 dela e
adiciona o comando vertra ao seu PATH. Abra um novo terminal e confira:
Para atualizar, execute o comando de instalação novamente. Para instalar uma versão específica, defina VERTRA_VERSION
(por exemplo VERTRA_VERSION=v0.3.0) antes de executá-lo. VERTRA_INSTALL_DIR altera o local do
binário (padrão ~/.vertracloud/bin, ou %USERPROFILE%\.vertracloud\bin no Windows).
Você também pode baixar o binário da sua plataforma diretamente na
página de releases.
Conectando sua conta
Cole uma chave de API criada na página de chaves de API do painel. Em CI e scripts, defina a variável de ambiente
VERTRA_API_KEY no lugar — ela tem prioridade sobre a chave salva.
Primeiro deploy
vertra upload (também vertra app upload ou vertra app create) cria uma aplicação nova. Ele lê NAME,
MEMORY, MAIN, VERSION, SUBDOMAIN, START e LANGUAGE do vertracloud.config e pergunta
o nome, a memória e o arquivo principal quando eles faltam; em scripts, passe --name, --memory e --main.
Ao terminar, ele salva o ID da nova aplicação no vertracloud.config.
Daí em diante, vertra deploy (um alias de vertra app commit) envia o diretório atual para essa aplicação existente.
Ele nunca cria uma: sem uma aplicação vinculada, pergunta qual atualizar ou falha em scripts, a menos que você passe o
ID da aplicação.
Criar uma aplicação é assíncrono: quando vertra upload cria uma aplicação nova, a CLI espera o build terminar e
mostra o resultado. Adicione --no-wait para voltar logo após o upload; a aplicação continua sendo construída em
segundo plano.
Adicione --json a qualquer comando para obter uma saída estruturada, pronta para automação.
Para dar uma mensagem a um deploy no histórico de deploys,
use vertra app commit -m "fix login". Sem -m, dentro de um repositório git, a CLI usa o assunto do último commit.
Vincular uma pasta a uma aplicação
Uma pasta fica vinculada a uma aplicação quando o vertracloud.config dela tem uma linha ID=. O vertra upload
a escreve para você. Os comandos que recebem um ID de aplicação (deploy, logs, app releases, app env…) usam
a aplicação vinculada quando você omite o ID.
Sem vínculo, um terminal interativo mostra um seletor e um script falha pedindo o ID. Outros comandos que você pode
querer: vertra projects lista suas aplicações e bancos de dados juntos, com o status, e vertra lang pt|en|es
define o idioma das mensagens da CLI (--lang ou VERTRA_LANG substituem isso por uma execução).
Releases e rollback
Cada comando aceita um ID de aplicação opcional antes do ID da release; sem ele, a CLI usa a aplicação vinculada ou
deixa você escolher uma. releases aceita --page e --limit, e mostra quais versões ainda podem ser restauradas.
rollback está disponível a partir do plano Pro. Antes de executar, a CLI mostra o que vai acontecer e pede
confirmação. Com --env, ela lista apenas os nomes das variáveis que seriam adicionadas, alteradas ou removidas,
nunca os valores. Sem --env, suas variáveis atuais permanecem como estão. Em CI, ou em qualquer lugar sem terminal,
passe --yes (-y); sem ele, o comando falha em vez de fazer o rollback sem pedir.
Listar e ler logs exige uma chave de API com o escopo apps:read. Fazer rollback exige apps:write, além de
apps:envs para --env.
Domínios personalizados
Cada comando aceita o ID do domínio ou o seu hostname. add também cria o complemento automático www/raiz, a menos que
você passe --no-www; o complemento não conta no limite de domínios do seu plano. --port vai de 1 a 65535,
--redirect-status é 301, 302, 307 ou 308 (padrão 308), e --path-prefix é um caminho literal, como /api. Em
update, um --path-prefix "" ou --redirect-to "" vazio limpa o valor, e --primary torna o domínio o principal no
lugar do seu complemento. remove pede confirmação e também remove o complemento, a menos que o domínio removido seja
o próprio complemento. Veja Domínio personalizado para entender como domínios, portas e prefixos de caminho funcionam.
app stop, db stop, app env remove e os comandos destrutivos pedem confirmação; passe --yes em automações.
Recusar encerra com status 1 e “Operation cancelled.” (com --json, um erro com o código CANCELLED), nunca como sucesso.
Blob Storage
get aceita um ID de objeto ou o caminho exato. Arquivos grandes são enviados em partes automaticamente, com barra de progresso.
Listar, baixar, gerar links e consultar o uso exigem uma chave de API com o escopo blob:read; enviar e excluir
exigem blob:write. Veja Blob Storage.
Comportamento do deploy
--zero-downtime: on exige o plano Enterprise.--auto-rollback: exige Intermediary ou superior.--health-path: começa com /, não tem espaços e tem até 200 caracteres. vertra app info mostra os valores atuais.
Veja Rollback e deploy sem downtime para entender o que cada configuração faz.Última modificação em 26 de outubro de 2026
