AI Glot websiteOpen AI Glot
CLI y MCPAutomatización y salida de la CLI

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.

Terminal
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 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.

Terminal
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.

Terminal
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
done

Estos 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é?

EstadoSignificadoQuién esperaTerminal
analyzingse está leyendo la estructura del archivonosotros, unos segundos
awaiting_instructionsse ha leído el archivo, pero aún no se ha solicitado nadatú
awaiting_approvalel plan está listo y tiene un preciotú
translatingen curso; es el único estado que consume créditosnosotros
completedfinalizada y con un archivo de resultado disponiblenadie✓
failedfinalizada sin resultado; consulta error.codetú, para reintentar✓
cancelleddetenida deliberadamente; solo se cobra el trabajo realizadonadie✓

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):

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

Con --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:

Terminal
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

CódigoSignificado
0Correcto
1Error de API o del servidor
2Comando o argumentos no válidos
3Error de autenticación o permisos
4Recurso no encontrado
5Límite de solicitudes alcanzado
6Conflicto 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:

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

Variables de entorno

VariableFinalidad
AIGLOT_API_KEYClave de API; prevalece sobre las credenciales almacenadas
AIGLOT_PROFILEPerfil de credenciales con nombre
AIGLOT_NO_TUIFuerza la salida legible por máquinas
AIGLOT_NO_KEYCHAINOmite el llavero del sistema operativo
NO_COLOREstándar (no-color.org). Desactiva solo el color; no cambia el formato de salida

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search AI Glot Docs documentation and read it in full, instead of answering from memory.

https://ai-glot.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://ai-glot.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.