Instalación
La CLI es un único binario sin dependencias: no necesita Node.js.
El instalador descarga la última versión para tu sistema y procesador (x64 o ARM), verifica su suma de comprobación SHA-256 y
añade el comando vertra a tu PATH. Abre una terminal nueva y compruébalo:
Para actualizar, ejecuta de nuevo el comando de instalación. Para instalar una versión concreta, define VERTRA_VERSION
(por ejemplo, VERTRA_VERSION=v0.3.0) antes de ejecutarlo. VERTRA_INSTALL_DIR cambia la ubicación del binario (por defecto
~/.vertracloud/bin, o %USERPROFILE%\.vertracloud\bin en Windows).
También puedes descargar el binario de tu plataforma directamente desde la
página de releases.
Conectar tu cuenta
Pega una clave de API creada en la página de claves de API del panel. En CI y en scripts, define la variable de entorno
VERTRA_API_KEY en su lugar: tiene prioridad sobre la clave guardada.
Primer despliegue
vertra upload (también vertra app upload o vertra app create) crea una aplicación nueva. Lee NAME, MEMORY, MAIN, VERSION, SUBDOMAIN, START y LANGUAGE de vertracloud.config y pide el nombre, la memoria y el archivo principal cuando faltan; en scripts, pasa --name, --memory y --main. Al terminar, guarda el ID de la nueva aplicación en vertracloud.config.
A partir de ahí, vertra deploy (un alias de vertra app commit) envía el directorio actual a esa aplicación existente. Nunca crea una: sin aplicación vinculada, pregunta cuál actualizar o falla en scripts si no pasas el ID de la aplicación.
Crear una aplicación es asíncrono: cuando vertra upload crea una aplicación nueva, la CLI espera
a que termine el build y muestra su resultado. Añade --no-wait para volver justo después de la subida; la aplicación sigue
compilándose en segundo plano.
Añade --json a cualquier comando para obtener una salida estructurada, lista para automatizar.
Para dar un mensaje a un despliegue en el historial de despliegues,
usa vertra app commit -m "fix login". Sin -m, dentro de un repositorio git, la CLI usa el asunto del último commit.
Vincular una carpeta a una aplicación
Una carpeta está vinculada a una aplicación cuando su vertracloud.config tiene una línea ID=. vertra upload la escribe
por ti. Los comandos que reciben un ID de aplicación (deploy, logs, app releases, app env…) usan la aplicación vinculada
cuando omites el ID.
Sin vínculo, una terminal interactiva muestra un selector y un script falla pidiendo el ID. Otros comandos que te pueden interesar: vertra projects lista tus aplicaciones y bases de datos juntas, con su estado, y vertra lang pt|en|es define el idioma de los mensajes de la CLI (--lang o VERTRA_LANG lo sustituyen en una sola ejecución).
Releases y rollback
Cada comando acepta un ID de aplicación opcional antes del ID de la release; sin él, la CLI usa la aplicación vinculada o te deja
elegir una. releases acepta --page y --limit, y muestra qué versiones todavía pueden restaurarse.
rollback está disponible desde el plan Pro. Antes de ejecutarse, la CLI muestra lo que va a pasar y te pide confirmación. Con
--env, solo lista los nombres de las variables que se añadirían, cambiarían o eliminarían, nunca sus valores. Sin --env,
tus variables actuales se mantienen. En CI, o en cualquier lugar sin terminal, pasa --yes (-y); sin él, el comando falla en
lugar de hacer rollback sin preguntar.
Listar y leer logs necesita una clave de API con el alcance apps:read. Hacer rollback necesita apps:write, además de
apps:envs para --env.
Dominios personalizados
Cada comando acepta el ID del dominio o su nombre de host. add también crea el complemento automático www/raíz, salvo que
pases --no-www; el complemento no cuenta para el límite de dominios de tu plan. --port va de 1 a 65535, --redirect-status
es 301, 302, 307 u 308 (por defecto 308), y --path-prefix es una ruta literal como /api. En update, un --path-prefix ""
o --redirect-to "" vacío borra el valor, y --primary convierte el dominio en el principal en lugar de su complemento. remove
pide confirmación y también elimina el complemento, salvo que el dominio que eliminas sea el propio complemento. Consulta
Dominio personalizado para saber cómo funcionan los dominios, los puertos y los prefijos de ruta.
app stop, db stop, app env remove y los comandos destructivos piden confirmación; pasa --yes en las automatizaciones.
Si se rechaza, el comando termina con estado 1 y “Operation cancelled.” (con --json, un error con código CANCELLED), nunca
como éxito.
Blob Storage
get acepta un ID de objeto o la ruta exacta. Los archivos grandes se envían por partes automáticamente, con una barra de
progreso. Listar, descargar, crear enlaces y consultar el uso necesitan una clave de API con el alcance blob:read; subir y
eliminar necesitan blob:write. Consulta Blob Storage.
Comportamiento de los despliegues
--zero-downtime: on necesita el plan Enterprise.--auto-rollback: necesita Intermediary o superior.--health-path: empieza por /, no contiene espacios y tiene hasta 200 caracteres. vertra app info muestra los valores actuales.
Consulta Rollbacks y despliegues sin interrupción para saber qué hace cada ajuste.Última modificación el 26 de octubre de 2026
