Uso con agentes

El CLI sureva está diseñado para usarse en agentes de IA, pipelines y scripts. Todos los comandos devuelven JSON por defecto y exponen un árbol de comandos legible por máquinas mediante --help --json.

JSON por defecto

El formato de salida por defecto es JSON. No es necesario pasar --output json explícitamente.

sureva apps list --org mi-org
# Devuelve: [{ "id": "...", "name": "...", ... }]

sureva deploys status mi-app-id deploy-123 --org mi-org
# Devuelve: { "id": "...", "status": "success", ... }

Pasá --output table solo cuando mostrés la salida a una persona en una terminal.

Introspección del árbol de comandos

Obtenés el árbol completo de comandos legible por máquinas para descubrir comandos disponibles, flags y tipos de argumentos:

sureva --help --json

Esto devuelve un documento JSON que describe cada comando, subcomando, flag y su tipo — útil para agentes que necesitan descubrir las capacidades del CLI en tiempo de ejecución.

Scripting con —output json

Combiná la salida JSON con herramientas estándar:

# Obtener el estado del último deploy
sureva deploys list mi-app-id --org mi-org | jq '.[0].status'

# Verificar qué variables de entorno están configuradas
sureva env get mi-app-id --org mi-org --reveal | jq 'keys'

# Activar un deploy y capturar el ID
DEPLOY_ID=$(sureva deploys trigger mi-app-id --org mi-org --tag v1.2.3 | jq -r '.id')

Patrones con códigos de salida

Usá los códigos de salida para manejar fallos sin parsear texto de error. El CLI siempre termina con 0 en caso de éxito y con un código distinto de cero en caso de fallo.

Código de salida	Condición	Acción sugerida para el agente
0	Éxito	Continuar el flujo
1	Error general / API	Registrar el cuerpo JSON del error; reintentar con backoff si es transitorio
2	Error de autenticación	Verificar SUREVA_TOKEN; informar el fallo al usuario
3	No encontrado	Detener; el recurso no existe
4	Error de validación	Detener; corregir la entrada antes de reintentar
5	Error de red	Reintentar con backoff exponencial

sureva deploys trigger mi-app-id --org mi-org --tag v1.2.3
EXIT_CODE=$?

case $EXIT_CODE in
  0) echo "Deploy activado correctamente" ;;
  2) echo "Error de autenticación — verificá SUREVA_TOKEN" >&2; exit 1 ;;
  4) echo "Error de validación — revisá --tag y --org" >&2; exit 1 ;;
  5) echo "Error de red — reintentando..." ;;
  *) echo "Error inesperado (código $EXIT_CODE)" >&2; exit $EXIT_CODE ;;
esac

Configuración para CI y automatización

Configurá SUREVA_TOKEN como secreto en tu entorno de CI:

# Ejemplo para GitHub Actions
steps:
  - name: Activar deploy
    env:
      SUREVA_TOKEN: ${{ secrets.SUREVA_TOKEN }}
      SUREVA_ORG: mi-org
    run: |
      sureva deploys trigger ${{ env.APP_ID }} --tag ${{ github.ref_name }}

Plantilla de instrucción para agentes

Usá el CLI sureva para gestionar recursos de Sureva Cloud.
Configurá SUREVA_TOKEN con un PAT válido (prefijo sapi_).
Todos los comandos devuelven JSON por defecto — parseá la salida JSON, no proceses texto de pantalla.
Usá los códigos de salida para detectar fallos: 0=éxito, 1=error API, 2=autenticación, 3=no encontrado, 4=validación, 5=red.
Ejecutá `sureva --help --json` para descubrir comandos y flags disponibles.
apps create y apps delete están disponibles; deploys cancel todavía no está implementado.
Usá --wait en apps create y deploys trigger para bloquear hasta que el recurso esté listo en CI.