Despliega y gestiona una app con el CLI de Sureva

De un equipo existente a una app web en funcionamiento con URL pública usando el CLI sureva v0.1.0. Cada paso está verificado contra el código fuente del CLI y es seguro para ejecutar textualmente en agentes de IA y pipelines de CI.

Camino rápido

1. Verificá tu equipo — sureva teams list --org <slug>
2. Creá la app — sureva apps create --name my-app --type web --region us-east-1 --org <slug>
3. Configurá variables de entorno (opcional) — sureva env set <app-id> --org <slug> CLAVE=valor
4. Disparar y observar el primer deploy — sureva deploys trigger <app-id> --org <slug> --wait
5. Obtener la URL pública — sureva apps get <app-id> --org <slug> | jq -r '.url'
6. Verificar estado y logs según necesidad

Antes de empezar

• GitHub App instalada — la instalación es solo desde la web en cloud.sureva.com. No existe ruta por CLI.
• Equipo existente — tu org debe tener al menos un equipo. Los equipos se crean únicamente en la interfaz web; el CLI solo puede listarlos.
• PAT exportado — exportá tu token de acceso personal:

  export SUREVA_TOKEN=sapi_<tu-token>
  export SUREVA_ORG=<slug-de-tu-org>  # opcional; evita repetir --org

  Consultá Autenticación para saber cómo crear un PAT.

1. Verificá tu equipo

sureva teams list --org <slug>

Extraer los slugs de equipos con jq:

sureva teams list --org <slug> | jq -r '.[].slug'

Si la org no tiene equipos, creá uno en cloud.sureva.com antes de continuar. El código de salida 4 indica que no se cumplió una precondición.

2. Creá la app web

sureva apps create \
  --name my-app \
  --type web \
  --region us-east-1 \
  --org <slug>

Capturá el ID de la app de inmediato:

APP_ID=$(sureva apps create \
  --name my-app \
  --type web \
  --region us-east-1 \
  --org <slug> | jq -r '.id')

Una respuesta exitosa se ve así (simplificada para reconocimiento):

{
  "id": "app_01abc...",
  "name": "my-app",
  "type": "web",
  "subdomain": "my-app-a1b2",
  "domain_status": "pending",
  "url": null
}

domain_status está en pending y url está ausente al momento de la creación. La URL queda disponible después del primer deploy exitoso, cuando se activa la infraestructura DNS/CDN.

Cuándo usar —wait en apps create

Para apps web, domain_status se activa alrededor del primer deploy exitoso. Agregar --wait a apps create bloquea hasta que el dominio esté activo (timeout 10m). Si el dominio no se activa en 10m, el comando termina con código 1 y error wait_timeout; si la provisión falla, termina con código 1 y error domain_failed.

El camino resiliente principal es crear sin --wait y bloquear en deploys trigger --wait (paso 4), que usa el timeout más largo de 15m.

3. Configurá variables de entorno (opcional)

sureva env set $APP_ID --org <slug> \
  DATABASE_URL=postgres://... \
  REDIS_URL=redis://...

env set realiza un reemplazo completo tipo PUT — cualquier clave no incluida en el comando se elimina. Verificá después de configurar:

sureva env get $APP_ID --org <slug> | jq 'keys'

4. Disparar y observar el primer deploy

sureva deploys trigger $APP_ID --org <slug> --wait

--wait bloquea hasta que el deploy llega a un estado terminal (timeout 15m). Códigos de salida:

Código de salida	Código de error	Significado
0	—	Deploy exitoso
1	deploy_failed	El deploy llegó a un estado terminal fallido o cancelado
1	wait_timeout	El deploy no completó en 15m

Para apps web, --tag no es requerido. El deploy usa la rama de GitHub, el comando de build y el directorio de salida configurados.

5. Obtener la URL pública

Después de que el paso 4 termina con código 0, el dominio está activo:

sureva apps get $APP_ID --org <slug> | jq -r '.url'
# https://my-app-a1b2.sureva.com

El sufijo de host por defecto es sureva.com. El campo url es null / ausente hasta que domain_status es active.

6. Verificar estado y logs

# Listar deploys recientes
sureva deploys list $APP_ID --org <slug>

# Obtener el estado de un deploy específico
sureva deploys status $APP_ID <deploy-id> --org <slug>

# Obtener un snapshot de logs
sureva logs $APP_ID --org <slug>

Obtener el ID y estado del último deploy en un solo comando:

sureva deploys list $APP_ID --org <slug> | jq -r '.[0] | "\(.id) \(.status)"'

Eliminar una app

sureva apps delete $APP_ID --org <slug> --yes

En caso de éxito, la API devuelve {"status": "deleting"} y el proceso de eliminación corre de forma asincrónica. Códigos de salida:

Código de salida	Código de error	Significado
0	—	Eliminación despachada
1	teardown_dispatch_failed	La API aceptó la solicitud pero el proceso de eliminación de infraestructura no pudo iniciarse
4	validation_error	No se pasó --yes

Usá sureva apps get $APP_ID --org <slug> para verificar el estado de la eliminación.

Tipos de app más allá de web

Para apps api, sse y web-ssr se aplican dos requisitos adicionales:

• --runtime al crear — requerido: nodejs24, python314 o go126.
• --tag al desplegar — desplegá un tag de release que creás externamente:

  gh release create v1.0.0 --repo mi-org/mi-app
  sureva deploys trigger $APP_ID --org <slug> --tag v1.0.0 --wait

Ejemplo para una app de tipo API:

APP_ID=$(sureva apps create \
  --name my-api \
  --type api \
  --runtime nodejs24 \
  --region us-east-1 \
  --org <slug> | jq -r '.id')

gh release create v1.0.0 --repo mi-org/my-api
sureva deploys trigger $APP_ID --org <slug> --tag v1.0.0 --wait

Códigos de salida y manejo de errores

Códigos de salida clave para el recorrido de esta guía:

Código de salida	Código de error	Disparador
0	—	Éxito
1	wait_timeout	apps create --wait o deploys trigger --wait superaron el timeout
1	domain_failed	apps create --wait — falló la provisión del dominio
1	deploy_failed	deploys trigger --wait — el deploy falló o fue cancelado
1	teardown_dispatch_failed	apps delete — el proceso de eliminación de infraestructura no pudo iniciarse
4	validation_error	Falta --yes, --runtime, --team u otra precondición

Consultá Uso con agentes para patrones de scripting y la referencia completa de códigos de salida.

Guías relacionadas

• Desplegar una landing web desde GitHub — ciclo de vida DNS/CDN del primer deploy para apps web.
• Referencia del CLI — referencia completa de flags y códigos de salida.
• Autenticación — crear y gestionar tokens de acceso personal.