Automatisation et sortie du CLI

Le CLI affiche des tableaux lisibles dans un terminal, mais utilise le format JSON lorsque la sortie est redirigée (piped). Ainsi, une même commande fonctionne aussi bien de manière interactive qu’automatisée.

aiglot batches list                    # tableau dans le terminal
aiglot batches list | jq '.data[0].id' # JSON lors d'une redirection
aiglot batches list --output ndjson    # un objet par ligne
aiglot account --json                  # JSON explicite

Les erreurs sont envoyées vers la sortie d’erreur standard (stderr), tout comme les avertissements importants, tels que la notification d’une page de résultats tronquée. La sortie standard (stdout) reste donc sûre pour être redirigée vers un autre programme.

Pagination

Les commandes batches list et glossaries list fonctionnent avec des curseurs. Transmettez le next_cursor de la réponse précédente via l’option --cursor, ou utilisez --all pour automatiser le processus jusqu’à ce que has_more soit égal à false (limité à 200 pages par sécurité) :

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

Avec --output ndjson, l’option --all affiche chaque ligne de chaque page au fur et à mesure de leur réception. En mode table et json, elle affiche un résultat combiné avec has_more: false, next_cursor: null et un compte pages_fetched à la place de request_id (puisqu’une seule requête ne peut être nommée lorsque plusieurs ont été exécutées).

Authentification CI

Créez une clé API dédiée avec des privilèges restreints et stockez-la dans le gestionnaire de secrets de votre fournisseur CI :

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

Le CLI vérifie les identifiants dans l’ordre suivant : AIGLOT_API_KEY, le trousseau (keychain) de l’OS, puis son fichier de configuration protégé.

Codes de sortie

Les scripts doivent se baser sur le code de sortie ou le code structuré error.code, et non sur le texte du message d’erreur.

Tentatives de reconnexion (Retries)

Les tentatives sont automatiques, mais uniquement lorsqu’elles sont sûres. L’erreur 429 est systématiquement retentée pour chaque commande, en respectant le header Retry-After avec un délai exponentiel limité. Les erreurs 408 et 5xx ne sont retentées que pour les requêtes idempotentes (RFC 9110 §9.2.2) — lectures, glossaries replace, glossaries delete.

Les commandes glossaries create, glossaries add, glossaries remove, batches rename et batches archive ne sont pas retentées après une erreur 5xx, car l’écriture a pu être prise en compte et une seconde tentative pourrait l’appliquer deux fois. Ces échecs sont remonté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 aveuglément.

Utilisez --no-retry lorsque le programme appelant gère sa propre politique de tentative, et --timeout <secondes> (par défaut 60) pour limiter la durée d’une seule requête. Les commandes destructives n’attendent jamais indéfiniment une réponse interactive : l’utilisation non interactive doit passer l’option --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