Automatización y salida de la CLI

La CLI muestra tablas legibles en el terminal y JSON cuando la salida se canaliza, por lo que el 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 JSON

Los errores y los avisos que el usuario necesita conocer, como una página de resultados truncada, se envían a la salida de error estándar. Así, la salida estándar se puede canalizar a otro programa sin problemas.

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 después de autorizar el plan, la calidad Standard seleccionada y el coste calculado. La autorización existente es suficiente si los cubre. La espera está limitada a 60 consultas y termina cuando el estado es completed, failed o cancelled. Si el proceso se interrumpe o agota el tiempo, conserva el ID del lote y reanúdalo sin crear otra traducción.

aiglot batches approve "$id" --quality standard --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
done

Estos son todos los estados que puede mostrar una traducción, incluidos los tres que la finalizan. Todos responden a la misma pregunta: ¿quién está esperando y a qué?

Paginación

batches list y glossaries list usan cursores. Pasa sin modificar a --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 de 200 páginas como medida de seguridad):

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

Con --output ndjson, --all muestra cada fila de cada página 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 asignar una sola petición cuando se han ejecutado varias.

Autenticación en CI

Crea una clave de API exclusiva con los permisos mínimos necesarios y guárdala en el gestor de secretos de tu proveedor de CI:

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

La 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

Los scripts deben basarse en el código de salida o en error.code estructurado, no en el texto del mensaje de error.

Reintentos

Los reintentos son automáticos, pero solo cuando son seguros. Los errores 429 se reintentan con todos los comandos, respetando Retry-After y aplicando una espera progresiva limitada. Los errores 408 y 5xx solo se reintentan en solicitudes idempotentes (RFC 9110 §9.2.2): lecturas, glossaries replace y glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename y batches archive no se reintentan tras un error 5xx, porque es posible que la escritura ya se haya aplicado y un segundo intento la aplicaría dos veces. Estos errores se devuelven al script con el código de salida 1: vuelve a leer el recurso y decide si quieres intentarlo de nuevo, en lugar de reintentarlo a ciegas.

Usa --no-retry cuando el control de los reintentos corresponda a quien realiza la llamada y --timeout <seconds> (60 de forma predeterminada) para establecer el tiempo máximo de una solicitud. Los comandos destructivos nunca esperan indefinidamente a que se responda a una solicitud interactiva: en un entorno no interactivo, debes 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-a

Variables de entorno