Automatización y salida de la CLI
Ejecuta la CLI de AI Glot de forma segura en scripts y CI con JSON o NDJSON, credenciales de entorno, perfiles, códigos de salida y reintentos limitados.
La CLI muestra tablas legibles en el terminal y JSON cuando la salida se redirige, de modo que un mismo comando funciona tanto de forma interactiva como en procesos automatizados.
aiglot batches list # table on a terminal
aiglot batches list | jq '.data[0].id' # JSON when piped
aiglot batches list --output ndjson # one object per line
aiglot account --json # explicit JSONLos errores se envían a la salida de error estándar, al igual que las advertencias que aún debe ver quien ejecuta el comando, como la de una página de resultados truncada. Así, la salida estándar se puede canalizar de forma segura a otro programa.
Esperar a que termine una traducción
Prepara primero el plan y revisa su alcance, las exclusiones y el coste calculado.
La CLI devuelve los objetos individuales directamente: consulta .id, .status y .plan,
no .data.id ni .data.status. Los comandos de listado siguen usando una matriz data.
set -euo pipefail
batch=$(aiglot batches create catalogue.csv --instruction "Translate into French" --json)
id=$(printf '%s' "$batch" | jq -er '.id')
printf '%s\n' "$batch" | jq '.plan'Ejecuta el siguiente bloque solo cuando se hayan autorizado el plan, la calidad Standard seleccionada y el coste calculado. La autorización existente basta si los cubre. La espera tiene un límite de 60 consultas y termina cuando el estado es completed, failed o cancelled. Si se interrumpe o se agota el tiempo, conserva el ID del lote y reanúdalo sin crear otra traducción.
aiglot batches approve "$id" --quality standard --yes --json
for ((attempt = 0; attempt < 60; attempt++)); do
status=$(aiglot batches get "$id" --timeout 15 --json | jq -er '.status')
case "$status" in
completed)
aiglot batches download "$id" --output result.csv
break
;;
failed|cancelled)
printf 'Batch %s ended with status %s.\n' "$id" "$status" >&2
exit 1
;;
awaiting_instructions|awaiting_approval)
printf 'Batch %s needs a decision; inspect its plan before continuing.\n' "$id" >&2
exit 2
;;
esac
if ((attempt == 59)); then
printf 'Wait limit reached. Resume batch %s; do not create a duplicate.\n' "$id" >&2
exit 1
fi
sleep 5
doneEstos son todos los estados que puede devolver una traducción, y los tres que la dan por terminada. Cada uno responde a la misma pregunta: ¿quién está esperando y a qué?
| Estado | Significado | Quién espera | Terminal |
|---|---|---|---|
analyzing | se está leyendo la estructura del archivo | nosotros, unos segundos | |
awaiting_instructions | se ha leído el archivo, pero aún no se ha solicitado nada | tú | |
awaiting_approval | el plan está listo y tiene un precio | tú | |
translating | en curso; es el único estado que consume créditos | nosotros | |
completed | finalizada y con un archivo de resultado disponible | nadie | ✓ |
failed | finalizada sin resultado; consulta error.code | tú, para reintentar | ✓ |
cancelled | detenida deliberadamente; solo se cobra el trabajo realizado | nadie | ✓ |
Paginación
batches list y glossaries list usan cursores. Devuelve literalmente con --cursor el next_cursor de la respuesta anterior, o deja que --all lo siga automáticamente hasta que has_more sea false (con un límite preventivo de 200 páginas):
aiglot batches list --status completed --all
aiglot glossaries list --all --output ndjsonCon --output ndjson, --all muestra cada fila de todas las páginas a medida que llega. En los modos table y json, muestra un único resultado combinado con has_more: false, next_cursor: null y un recuento pages_fetched en lugar de request_id, ya que no se puede identificar una sola petición cuando se han ejecutado varias.
Autenticación en CI
Crea una clave de API específica con los permisos mínimos necesarios y guárdala en el gestor de secretos del proveedor de CI:
export AIGLOT_API_KEY="aig_live_…"
aiglot account --jsonLa CLI busca las credenciales en este orden: AIGLOT_API_KEY, el llavero del sistema operativo y, por último, su archivo de configuración protegido.
Códigos de salida
| Código | Significado |
|---|---|
| 0 | Correcto |
| 1 | Error de API o del servidor |
| 2 | Comando o argumentos no válidos |
| 3 | Error de autenticación o permisos |
| 4 | Recurso no encontrado |
| 5 | Límite de solicitudes alcanzado |
| 6 | Conflicto con el estado del recurso |
Los scripts deben actuar según el código de salida o el campo estructurado error.code, no según el texto del mensaje de error.
Reintentos
Los reintentos son automáticos, pero solo cuando es seguro repetir la operación. Se vuelve a intentar con 429 en todos los comandos, respetando Retry-After y aplicando un retroceso limitado. Los errores 408 y 5xx solo se reintentan en solicitudes idempotentes (RFC 9110 §9.2.2): lecturas, glossaries replace y glossaries delete.
No se vuelve a intentar glossaries create, glossaries add, glossaries remove, batches rename ni batches archive tras un 5xx, porque es posible que la escritura ya se haya aplicado y un segundo intento la duplicaría. Esos errores se comunican al script con el código de salida 1: vuelve a leer el recurso y decide si reintentar, en lugar de hacerlo a ciegas.
Usa --no-retry si quien ejecuta el comando gestiona los reintentos y --timeout <seconds> (60 de forma predeterminada) para establecer el límite de una solicitud. Los comandos destructivos no esperan indefinidamente una respuesta interactiva: para usarlos sin interacción, es obligatorio pasar --force.
Perfiles
Usa perfiles con nombre para mantener separadas las credenciales de distintos espacios de trabajo o entornos:
aiglot --profile client-a auth login --key "$CLIENT_A_KEY"
aiglot --profile client-a account
export AIGLOT_PROFILE=client-aVariables de entorno
| Variable | Finalidad |
|---|---|
AIGLOT_API_KEY | Clave de API; prevalece sobre las credenciales almacenadas |
AIGLOT_PROFILE | Perfil de credenciales con nombre |
AIGLOT_NO_TUI | Fuerza la salida legible por máquinas |
AIGLOT_NO_KEYCHAIN | Omite el llavero del sistema operativo |
NO_COLOR | Estándar (no-color.org). Desactiva solo el color; no cambia el formato de salida |