Automatisation et sortie de la CLI

Dans un terminal, la CLI affiche des tableaux lisibles. Lorsque la sortie est redirigée, elle produit du JSON, ce qui permet d’utiliser la même commande en mode interactif comme en automatisation.

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

Les erreurs sont envoyées sur la sortie d’erreur standard, tout comme les avertissements que l’appelant doit voir, par exemple lorsqu’une page de résultats est tronquée. La sortie standard peut donc être redirigée vers un autre programme sans risque.

Attendre la fin d’une traduction

Préparez d’abord le plan et vérifiez son périmètre, ses exclusions et le coût estimé. La CLI renvoie directement les objets uniques : lisez .id, .status et .plan, et non .data.id ou .data.status. Les commandes de liste utilisent toujours un tableau 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'

N’exécutez le bloc suivant qu’après avoir obtenu l’autorisation pour le plan, la qualité Standard sélectionnée et le coût estimé. Une autorisation existante suffit si elle couvre ces éléments. L’attente est limitée à 60 vérifications et s’arrête lorsque le traitement est terminé, échoue ou est annulé. En cas d’interruption ou de dépassement du délai, conservez l’identifiant du lot et reprenez son traitement sans créer une autre traduction.

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

Voici tous les statuts qu’une traduction peut renvoyer, ainsi que les trois qui y mettent fin. Chacun répond à la même question : qui attend, et quoi ?

Pagination

batches list et glossaries list utilisent un curseur. Renvoyez tel quel le next_cursor de la réponse précédente avec --cursor, ou laissez --all le suivre automatiquement jusqu’à ce que has_more soit false (avec une limite de 200 pages par mesure de précaution) :

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

Avec --output ndjson, --all affiche chaque ligne de chaque page au fur et à mesure de leur arrivée. En mode table et json, la commande affiche un seul résultat regroupé, avec has_more: false, next_cursor: null et un nombre pages_fetched à la place de request_id, puisqu’il n’est pas possible d’attribuer un identifiant unique à plusieurs requêtes.

Authentification en CI

Créez une clé API dédiée avec le périmètre minimal requis et stockez-la dans le gestionnaire de secrets de votre fournisseur CI :

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

La CLI vérifie les identifiants dans cet ordre : AIGLOT_API_KEY, trousseau de clés du système d’exploitation, puis fichier de configuration protégé.

Codes de sortie

Dans les scripts, fondez vos décisions sur le code de sortie ou sur la valeur structurée error.code, et non sur le texte du message d’erreur.

Nouvelles tentatives

Les nouvelles tentatives sont automatiques, mais uniquement lorsqu’elles ne présentent aucun risque. Les réponses 429 entraînent une nouvelle tentative pour toutes les commandes, en respectant Retry-After et avec un délai exponentiel plafonné. Les réponses 408 et 5xx entraînent une nouvelle tentative uniquement pour les requêtes idempotentes (RFC 9110 §9.2.2) : lectures, glossaries replace et glossaries delete.

Après une réponse 5xx, les commandes glossaries create, glossaries add, glossaries remove, batches rename et batches archive ne font pas l’objet d’une nouvelle tentative, car l’écriture a peut-être déjà été effectuée et une seconde tentative l’appliquerait deux fois. Ces échecs sont renvoyés à votre script avec le code de sortie 1 : relisez la ressource et décidez vous-même s’il faut réessayer, plutôt que de relancer la commande à l’aveugle.

Utilisez --no-retry si l’appelant gère lui-même les nouvelles tentatives, et --timeout <seconds> (60 par défaut) pour limiter la durée d’une requête. Les commandes destructives n’attendent jamais indéfiniment une réponse interactive : en mode non interactif, vous devez utiliser --force.

Profils

Utilisez des profils nommés pour séparer les identifiants de différents espaces de travail ou environnements :

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

Variables d’environnement