AI Glot websiteOpen AI Glot
CLI e MCPAutomação e saída da CLI

Automação e saída da CLI

Execute a CLI do AI Glot com segurança em scripts e CI usando JSON ou NDJSON, credenciais de ambiente, perfis, códigos de saída e novas tentativas limitadas.

A CLI exibe tabelas legíveis no terminal e JSON quando a saída é redirecionada, então o mesmo comando funciona tanto no uso interativo quanto na automação.

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

As falhas e os avisos que o chamador precisa ver, como os que indicam uma página de resultados truncada, são enviados para a saída de erro padrão. Assim, a saída padrão continua segura para redirecionar para outro programa.

Aguardar a conclusão de uma tradução

Primeiro, prepare o plano e confira o escopo, as exclusões e o custo calculado. A CLI retorna objetos individuais diretamente: leia .id, .status e .plan, não .data.id nem .data.status. Os comandos de listagem ainda usam um array 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'

Execute o próximo bloco somente depois que o plano, a qualidade Standard selecionada e o custo calculado forem autorizados. Uma autorização existente é suficiente se cobrir esses itens. A espera é limitada a 60 consultas e termina quando o status for completed, failed ou cancelled. Se o processo for interrompido ou atingir o tempo limite, guarde o ID do lote e retome-o sem criar outra tradução.

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

Estes são todos os status que uma tradução pode apresentar, incluindo os três que a encerram. Cada um responde à mesma pergunta: quem está aguardando e pelo quê?

StatusSignificadoQuem aguardaTerminal
analyzinga estrutura do arquivo está sendo lidanós, por alguns segundos
awaiting_instructionso arquivo foi lido; ainda não foi solicitado nadavocê
awaiting_approvalo plano está pronto e tem um preço definidovocê
translatingem andamento; único estado que consome créditosnós
completedconcluída, com um arquivo de resultado disponívelninguém✓
failedencerrada sem resultado; consulte error.codevocê, para tentar de novo✓
cancelledinterrompida de propósito; cobrança apenas pelo trabalho executadoninguém✓

Paginação

batches list e glossaries list usam cursores. Reenvie sem alterações o next_cursor da resposta anterior com --cursor ou deixe --all percorrer as páginas até has_more ser false (com limite de segurança de 200 páginas):

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

Com --output ndjson, --all exibe cada linha de todas as páginas à medida que chega. Nos modos table e json, exibe um único resultado combinado, com has_more: false, next_cursor: null e a contagem pages_fetched no lugar de request_id, pois não é possível atribuir um único nome à solicitação depois que várias foram feitas.

Autenticação em CI

Crie uma chave de API dedicada com o escopo mínimo necessário e armazene-a no gerenciador de segredos do provedor de CI:

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

A CLI verifica as credenciais nesta ordem: AIGLOT_API_KEY, chaveiro do sistema operacional e, por fim, arquivo de configuração protegido.

Códigos de saída

CódigoSignificado
0Sucesso
1Erro de API ou do servidor
2Comando ou argumentos inválidos
3Falha de autenticação ou permissão
4Recurso não encontrado
5Limite de solicitações atingido
6Conflito de estado do recurso

Os scripts devem tomar decisões com base no código de saída ou em error.code estruturado, não no texto da mensagem de erro.

Novas tentativas

As novas tentativas são automáticas, mas apenas quando são seguras. 429 é repetido em todos os comandos, respeitando Retry-After e usando intervalos crescentes limitados. 408 e 5xx só são repetidos em solicitações idempotentes (RFC 9110 §9.2.2): leituras, glossaries replace e glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename e batches archive não são repetidos após um 5xx, pois a alteração talvez já tenha sido aplicada e uma segunda tentativa a duplicaria. Essas falhas são informadas ao script com o código de saída 1: consulte novamente o recurso e decida por conta própria se deve tentar outra vez, em vez de repetir às cegas.

Use --no-retry quando o chamador controlar a política de novas tentativas e --timeout <seconds> (padrão: 60) para limitar uma solicitação. Comandos destrutivos nunca ficam aguardando indefinidamente uma confirmação interativa: no modo não interativo, é necessário passar --force.

Perfis

Use perfis nomeados para manter separadas as credenciais de diferentes espaços de trabalho ou ambientes:

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

Variáveis de ambiente

VariávelFinalidade
AIGLOT_API_KEYChave de API; substitui as credenciais armazenadas
AIGLOT_PROFILEPerfil de credenciais nomeado
AIGLOT_NO_TUIForça a saída legível por máquina
AIGLOT_NO_KEYCHAINIgnora o chaveiro do sistema operacional
NO_COLORPadrão (no-color.org). Desativa apenas as cores; não altera o formato da saída

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.