Referencia de CLIJSON y automatización

JSON y automatización

La CLI está hecha para automatizarse con scripts. Pasa --json para obtener salida legible por máquinas, contrólala desde CI con un token y descubre el esquema de cualquier comando en tiempo de ejecución.

El otro lector de esta salida es un agente de programación con IA: despliegue desde Claude Code muestra los comandos de log en JSON que ejecuta para comprobar un despliegue.

--json en todas partes

Añade --json a cualquier comando para obtener salida estructurada. La CLI también cambia a JSON automáticamente cuando stdout no es un TTY.

lizard ps --json
lizard secrets list --json
lizard metrics --json

Comandos en streaming

Para los comandos en streaming (lizard up sin --detach), --json emite un objeto JSON por línea:

{ "event": "log", "line": "Step 1/8 : FROM node:20" }
{ "event": "log", "line": "..." }
{ "event": "deployed", "status": "running", "url": "https://app.onlizard.com" }

El stream de la compilación termina con done o error. Después de done, lizard up sin --ci emite un evento final deployed, failed o deploying con status. Solo deployed incluye url (que puede ser null). Después de error no hay evento final y el comando sale con 1.

logs --json es una instantánea, no un stream

lizard logs --json devuelve las últimas 200 líneas (se puede cambiar con --tail N, máximo 1000) y sale. No esperes más salida de él.

Para un incidente específico, usa --restart latest o --restart <id>.

Errores

En modo JSON, un comando que falla imprime un objeto de error en stdout y sale con un código distinto de cero (consulta la tabla en Uso en CI / sin interfaz):

{
  "error": {
    "code": "ERROR",
    "status": null,
    "message": "Project \"my-projet\" not found.",
    "body": null
  }
}

code es el código de error de la API, un código de la CLI como NOT_AUTHENTICATED o PROJECT_DELETED, o ERROR para un error genérico; los errores en las banderas dan códigos como commander.unknownOption. status es el estado HTTP, o null cuando la CLI falló antes de que respondiera la API. body contiene la respuesta de la API, o null.

Sin una sesión iniciada, los comandos fallan con NOT_AUTHENTICATED y salen con 2. Fuera de CI, body.login contiene enlaces de inicio de sesión (authUrl, authUrls) y una instruction: un agente puede darle el enlace al usuario y luego volver a ejecutar el comando.

Descubrimiento de esquemas

Muestra los argumentos, opciones y códigos de salida exactos de cualquier comando:

lizard --help --json                 # whole tree + global flags + exit codes
lizard service set --help --json     # one command

La forma de la respuesta es { cli, version, agents, command: { arguments, options, subcommands }, globalOptions, exitCodes }. Como se genera a partir del binario instalado, siempre coincide con tu versión; úsala de preferencia en lugar de fijar flags manualmente.

Uso en CI / sin interfaz

Autentícate con un token y vincula el proyecto explícitamente. Si no, up sin interfaz despliega en el proyecto predeterminado de tu cuenta:

# Set LIZARD_TOKEN through your CI secret store.
lizard init --name my-project
lizard up --ci --service api --detach   # creates api on the first run

Comprueba los códigos de salida para decidir el flujo de tu pipeline:

CódigoSignificado
0éxito
1error genérico
2auth — token ausente/caducado
3no encontrado: la API no tiene nada con ese ID
4tiempo de espera agotado
5cancelado

Un nombre de proyecto o servicio que no coincide con nada sale con 1. lizard run, lizard sandbox exec y lizard sandbox ssh salen con el código del propio comando (127 si run no encuentra el comando).

--wait hace que redeploy espere a que termine la compilación y a que el nuevo despliegue esté listo. Sin él, el modo JSON sale con 0 en cuanto Lizard acepta la solicitud de compilación.

if lizard redeploy --service api --wait --json; then
  echo "Deploy succeeded"
else
  status=$?
  echo "Deploy failed with code $status" >&2
  lizard logs --build --json || true
  exit "$status"
fi
Resumenlogin

Actualizado