Automatización y salida de la CLI

La CLI imprime tablas legibles en la terminal y JSON cuando la salida se redirige (piping), permitiendo que el mismo comando funcione tanto de forma interactiva como en automatizaciones.

aiglot batches list                    # tabla en la terminal
aiglot batches list | jq '.data[0].id' # JSON al redirigir
aiglot batches list --output ndjson    # un objeto por línea
aiglot account --json                  # JSON explícito

Los errores se envían a la salida de error estándar (stderr), al igual que las advertencias que el usuario debe conocer, como una página de resultados truncada. Por lo tanto, la salida estándar (stdout) es segura para redirigirse a otro programa.

Paginación

Los comandos batches list y glossaries list se basan en cursores. Pase el next_cursor de la respuesta anterior mediante el parámetro --cursor, o utilice --all para que la CLI lo gestione automáticamente hasta que has_more sea false (limitado a 200 páginas como medida de seguridad):

aiglot batches list --status completed --all
aiglot glossaries list --all --output ndjson

Con --output ndjson, --all imprime cada fila de cada página a medida que llega. En modo table y json, imprime un único resultado combinado con has_more: false, next_cursor: null y un recuento de pages_fetched en lugar de request_id, ya que no se puede asignar un único ID de solicitud cuando se han ejecutado varias.

Autenticación en CI

Cree una clave de API dedicada con el alcance mínimo necesario y almacénela en el gestor de secretos de su proveedor de CI:

export AIGLOT_API_KEY="aig_live_…"
aiglot account --json

La CLI verifica las credenciales en este orden: AIGLOT_API_KEY, el llavero (keychain) del SO y, por último, su archivo de configuración protegido.

Códigos de salida

Los scripts deben ramificarse según el código de salida o el error.code estructurado, no basándose en el texto del mensaje de error.

Reintentos

Los reintentos son automáticos, pero solo cuando es seguro realizarlos. El error 429 se reintenta en todos los comandos, respetando el encabezado Retry-After con un retroceso (backoff) limitado. Los errores 408 y 5xx solo se reintentan en solicitudes idempotentes (RFC 9110 §9.2.2), como las lecturas, glossaries replace y glossaries delete.

Los comandos glossaries create, glossaries add, glossaries remove, batches rename y batches archive no se reintentan tras un error 5xx, ya que la escritura podría haberse completado y un segundo intento la aplicaría dos veces. Estos fallos se notifican al script con el código de salida 1: vuelva a leer el recurso y decida si debe intentar la operación de nuevo en lugar de reintentar a ciegas.

Utilice --no-retry cuando el programa que llama gestione la política de reintentos, y --timeout <segundos> (predeterminado: 60) para limitar una única solicitud. Los comandos destructivos nunca esperan indefinidamente una respuesta interactiva: el uso no interactivo debe incluir --force.

Perfiles

Utilice perfiles con nombre para mantener separadas las credenciales de diferentes espacios de trabajo o entornos:

aiglot --profile client-a auth login --key "$CLIENT_A_KEY"
aiglot --profile client-a account
export AIGLOT_PROFILE=client-a

Variables de entorno