CLI automation and output

The CLI prints readable tables to a terminal and JSON when output is piped, so the same command works interactively and in automation.

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

Failures go to standard error, and so do warnings the caller still needs to see, such as a truncated page of results. Standard output therefore remains safe to pipe into another program.

Waiting for a translation to finish

A script that starts a translation usually has to wait for it. Poll batches get and stop on a terminal status:

id=$(aiglot batches create catalogue.csv --instruction "Translate into French" --json | jq -r '.data.id')
aiglot batches approve "$id" --json > /dev/null

until status=$(aiglot batches get "$id" --json | jq -r '.data.status'); [ "$status" = "completed" ] || [ "$status" = "failed" ]; do
  sleep 5
done

[ "$status" = "completed" ] && aiglot batches download "$id" --output result.csv

These are every status a translation can report, and the three that end it. Each one answers the same question: who is waiting, and on what?

Pagination

batches list and glossaries list are cursor-based. Pass the next_cursor from the previous response back verbatim with --cursor, or let --all follow it for you until has_more is false (capped at 200 pages as a backstop):

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

In --output ndjson, --all prints every row from every page as it arrives. In table and json mode it prints one combined result with has_more: false, next_cursor: null and a pages_fetched count in place of request_id, since no single request can be named once several ran.

CI authentication

Create a dedicated, minimum-scope API key and store it in the CI provider’s secret manager:

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

The CLI checks credentials in this order: AIGLOT_API_KEY, OS keychain, then its protected config file.

Exit codes

Scripts should branch on the exit code or structured error.code, not error-message text.

Retries

Retries are automatic, but only where a retry is safe. 429 is retried for every command, honouring Retry-After with bounded backoff. 408 and 5xx are retried only for requests that are idempotent (RFC 9110 §9.2.2): reads, glossaries replace, glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename and batches archive are not retried after a 5xx, because the write may already have landed and a second attempt would apply it twice. Those failures surface to your script with exit 1: re-read the resource and decide for yourself whether to try again rather than retrying blindly.

Use --no-retry when the caller owns retry policy, and --timeout <seconds> (default 60) to cap a single request. Destructive commands never wait forever for an interactive prompt: non-interactive use must pass --force.

Profiles

Use named profiles to keep credentials for different workspaces or environments separate:

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

Environment variables