Salida JSON y automatización

La CLI está construida para ser leída por scripts y agentes. JSON es la salida predeterminada; las tablas y el JSON delimitado por líneas son opcionales.

La envoltura

Cada comando correcto imprime un objeto JSON en la salida estándar:

{
  "ok": true,
  "schema_version": "1",
  "workspace": "yourworkspace",
  "domain": "yourworkspace.hansa.chat",
  "changed": false,
  "data": { }
}

changed le dice si el comando realmente modificó algo; un false significa que el estado deseado ya existía. data contiene el resultado: listas de canales o mensajes, un mensaje con su contenido como JSON anidado real, confirmaciones de comandos.

Los errores van a la salida de error estándar como JSON y nunca tocan la salida estándar:

{
  "ok": false,
  "schema_version": "1",
  "error": { "code": "unauthenticated", "message": "…", "retryable": false }
}

Códigos de salida

Código	Significado
0	Éxito, incluida una operación nula (`changed: false`)
1	Error interno
2	Error de uso o de configuración
3	Autenticación requerida o fallida
4	Permiso denegado o condición previa fallida
5	No encontrado o conflicto
6	Tiempo de espera agotado, no disponible o límite de solicitudes alcanzado

Un patrón de script robusto:

if hansa chat channels ensure --name Deploy --type public >/dev/null 2>&1; then
  echo "channel ready"
fi

Formatos de salida

hansa chat channels list -o json    # default, one envelope
hansa chat channels list -o jsonl   # one JSON object per line
hansa chat channels list -o table   # aligned text columns for humans

Opciones globales útiles

--workspace <alias-or-domain>   # override the workspace for one command
--timeout 30s                   # network timeout
--config /path/config.json      # custom context file (default: OS config dir)
--verbose                       # diagnostics to stderr, secrets filtered

La variable de entorno HANSA_CONFIG reubica todo el archivo de contextos, lo que permite a los trabajos en paralelo usar contextos aislados. El suministro de tokens headless y el comportamiento del llavero se describen en autenticación.

Notas de seguridad

Las credenciales viven solo en el llavero del sistema operativo o en el entorno del proceso, nunca en la salida, los registros ni el archivo de contextos.
Los diagnósticos de --verbose filtran las cabeceras de autorización, la entrada de credenciales y las respuestas de renovación.
Todos los identificadores se emiten como cadenas JSON y las marcas de tiempo como UTC RFC3339; el contenido de los mensajes aparece como JSON anidado real, no como una cadena entre comillas.