Exlogare CLI

Установка и использование `exl` для отправки CI-логов и чтения AI-разборов из терминала.

exl — командная строка Exlogare. Используйте её, когда нужно отправить лог из shell-шага CI, посмотреть AI-разборы из терминала или автоматизировать Exlogare без полноценной интеграции с конкретной CI-платформой.

CLI оборачивает те же публичные API, которые описаны отдельно:

Universal ingest API — отправка логов.
Read API — чтение списка и деталей разборов.

Установка

CLI распространяется как один Go-бинарь. Выберите способ, который удобен для вашей среды.

Ручная установка

Скачайте архив для вашей OS/arch на странице GitHub Releases, достаньте exl и положите его в директорию из $PATH.

exl version

Debian / Ubuntu package asset

curl -fsSL \
  https://github.com/exlogare/exlogare-cli/releases/latest/download/exlogare-cli_amd64.deb \
  -o exl.deb
sudo dpkg -i exl.deb

Fedora / RHEL package asset

sudo rpm -i \
  https://github.com/exlogare/exlogare-cli/releases/latest/download/exlogare-cli_amd64.rpm

Docker

Используйте Docker, если не хотите ставить бинарь внутрь runner image.

docker run --rm \
  -e EXLOGARE_TOKEN \
  ghcr.io/exlogare/exl:latest analyses list --since 24h

Аутентификация

Создайте API-токен в дашборде: Integration -> API tokens.

Для рабочей машины сохраните токен в keychain:

exl auth login

Вставьте токен в prompt. CLI сохранит его в OS-native secret store:

Linux: libsecret-compatible хранилище (GNOME Keyring, KWallet и т.п.).
macOS: Keychain.
Windows: Credential Manager.

Для CI-раннеров лучше использовать переменную окружения:

export EXLOGARE_TOKEN=exl_...

Проверить, видит ли CLI токен:

exl auth status

Выйти на рабочей машине:

exl auth logout

Приоритет настроек:

Настройка	Порядок выбора
Токен	`EXLOGARE_TOKEN` -> OS keychain
API URL	`--api-url` -> `EXLOGARE_API_URL` -> `https://api.exlogare.net`

Глобальные флаги

Эти флаги доступны на всех командах.

Флаг	Что делает	Когда использовать
`--api-url <url>`	Переопределяет API endpoint.	Локальная разработка, staging, self-hosted API.
`--json`	Печатает machine-readable JSON там, где команда это поддерживает.	Скрипты, `jq`, CI-автоматизация.

Команды auth

`exl auth login`

Сохраняет API-токен в OS keychain.

exl auth login

Можно передать токен без интерактивного prompt:

exl auth login --token exl_...

Флаг	Обязательный	Значение
`--token <token>`	Нет	API-токен. Если не указан, CLI сначала смотрит `EXLOGARE_TOKEN`, затем спрашивает токен интерактивно.

`exl auth status`

Показывает, настроен ли токен, не вызывая API.

exl auth status

Команда маскирует токен и показывает источник: EXLOGARE_TOKEN env или keychain.

`exl auth logout`

Удаляет токен из keychain. Если в окружении всё ещё задан EXLOGARE_TOKEN, он продолжит иметь приоритет.

exl auth logout

Отправить лог упавшей CI

exl ingest читает лог из --log-file, либо из stdin, если файл не указан.

make test 2>&1 | tee build.log

if [ "${PIPESTATUS[0]}" -ne 0 ]; then
  exl ingest \
    --provider buildkite \
    --project myorg/web \
    --status failed \
    --commit "$BUILDKITE_COMMIT" \
    --branch "$BUILDKITE_BRANCH" \
    --pipeline-url "$BUILDKITE_BUILD_URL" \
    --log-file build.log
fi

Основные флаги:

Флаг	Значение
`--provider`	Метка CI-провайдера: например `jenkins`, `buildkite`, `teamcity`, `generic`.
`--project`	Идентификатор проекта или репозитория для группировки.
`--status`	Статус CI. По умолчанию `failed`.
`--log-file`	Путь к логу упавшего шага. Если не указан, `exl` читает stdin.

CLI ограничивает лог 4 МиБ до отправки запроса. Очень большие логи лучше заранее обрезать до проблемного участка.

Полная расшифровка `exl ingest`

exl ingest \
  --provider buildkite \
  --project myorg/web \
  --status failed \
  --pipeline-id "$BUILDKITE_BUILD_ID" \
  --job-id "$BUILDKITE_JOB_ID" \
  --job-name "unit tests" \
  --branch "$BUILDKITE_BRANCH" \
  --commit "$BUILDKITE_COMMIT" \
  --pipeline-url "$BUILDKITE_BUILD_URL" \
  --build-number "$BUILDKITE_BUILD_NUMBER" \
  --log-file build.log

Флаг	Обязательный	Значение
`--provider <slug>`	Да	Название CI или источника. Подойдут `jenkins`, `buildkite`, `drone`, `teamcity`, `circleci`, `generic`.
`--project <id>`	Да	Стабильный идентификатор проекта: `org/repo`, `team/service`, slug пайплайна.
`--status <status>`	Нет	Статус запуска. По умолчанию `failed`. Обычно: `failed`, `success`, `cancelled`, `timeout`, `error`.
`--pipeline-id <id>`	Нет	Уникальный id запуска внутри CI. Нужен для дедупликации.
`--job-id <id>`	Нет	Id конкретного job/step. Вместе с `pipeline-id` помогает не плодить дубликаты.
`--job-name <name>`	Нет	Человекочитаемое имя шага: `unit tests`, `build image`, `deploy staging`.
`--branch <ref>`	Нет	Ветка или ref.
`--commit <sha>`	Нет	SHA коммита.
`--pipeline-url <url>`	Нет	Ссылка на CI run. Exlogare покажет её в разборе.
`--build-number <n>`	Нет	Номер сборки. Используется как run identifier, если `pipeline-id` пустой.
`--log-file <path>`	Нет	Файл с логом. Если не указан, лог читается из stdin.

Лучше всегда передавать pipeline-id и job-id, если CI их даёт. Это делает повторный запуск команды идемпотентным для одного и того же упавшего шага.

stdin вместо файла

cat build.log | exl ingest \
  --provider generic \
  --project myorg/web \
  --status failed

Или так:

exl ingest \
  --provider jenkins \
  --project myorg/web \
  --status failed < build.log

Как правильно вставлять в CI

Хороший паттерн: сначала сохранить лог в файл, потом отправить его только при падении команды.

set -o pipefail
make test 2>&1 | tee build.log
status=$?

if [ "$status" -ne 0 ]; then
  exl ingest \
    --provider generic \
    --project "$CI_PROJECT" \
    --status failed \
    --branch "$CI_BRANCH" \
    --commit "$CI_COMMIT_SHA" \
    --log-file build.log
fi

exit "$status"

Так pipeline остаётся красным, а Exlogare получает лог для разбора.

Читать разборы

Список последних разборов:

exl analyses list --since 24h

JSON для автоматизации:

exl analyses list --since 24h --severity high --json \
  | jq -r '.items[] | "[\(.severity)] \(.project_path): \(.root_cause)"'

Один конкретный разбор:

exl analyses show <analysis-id>

`exl analyses list`

Список разборов использует cursor pagination и поддерживает фильтры Read API.

exl analyses list \
  --since 24h \
  --until 2026-04-28T00:00:00Z \
  --severity high \
  --project myorg/web \
  --source generic_ingest \
  --limit 50

Флаг	Значение
`--since <time>`	Нижняя граница времени. Можно ISO timestamp или duration: `24h`, `7d`, `2026-04-01T00:00:00Z`.
`--until <time>`	Верхняя граница времени. Обычно ISO timestamp.
`--severity <level>`	Фильтр по severity: `low`, `medium`, `high`.
`--project <id>`	Фильтр по проекту.
`--source <source>`	Фильтр по источнику ingestion, например `generic_ingest`, `github_webhook`, `circleci_ingest`.
`--limit <n>`	Размер страницы, от 1 до 100. По умолчанию `20`.
`--cursor <token>`	Курсор следующей страницы из предыдущего ответа.

Без --json команда печатает табличный summary. Если есть следующая страница, в конце будет строка:

next_cursor=...

С JSON удобно проходить все страницы в скрипте:

exl analyses list --since 7d --limit 100 --json

`exl analyses show <analysis-id>`

Показывает полный RCA payload:

exl analyses show 9d3c2c41-...

С JSON:

exl analyses show 9d3c2c41-... --json

В обычном выводе команда показывает id, время, provider/source, project, CI ids, severity, confidence, ссылки на pipeline/job, root_cause, explanation и fix_suggestion, если они есть.

Создавать короткоживущие токены для раннеров

Один раз используйте долгоживущий admin-токен, затем выпускайте короткие ingest-токены для CI:

exl tokens create \
  --name buildkite-prod \
  --scope ingest \
  --expires-in-days 7 \
  --json

Скопируйте токен сразу. Exlogare показывает raw token только один раз.

Полная расшифровка `exl tokens create`

Флаг	Обязательный	Значение
`--name <name>`	Да	Человекочитаемое имя токена: `jenkins-prod`, `buildkite-nightly`, `grafana-readonly`.
`--scope <scope>`	Да	Scope токена. Можно повторять или передать CSV через Cobra string-slice. Поддерживаются `ingest`, `read`.
`--expires-in-days <n>`	Нет	TTL в днях. `0` или отсутствие флага означает без срока действия.
`--json`	Нет	Вернуть полный JSON-ответ, удобно для секрет-менеджеров и автоматизации.

Примеры:

# Только отправка логов из CI
exl tokens create --name jenkins-prod --scope ingest --expires-in-days 30

# Read-only токен для Grafana/cron-отчётов
exl tokens create --name grafana --scope read --json

# Токен с двумя scope
exl tokens create --name automation --scope ingest --scope read --expires-in-days 7

Токен, которым вы вызываете tokens create, должен иметь право создавать токены. Первый seed-токен обычно создаётся в дашборде вручную.

Вывод и exit codes

При успехе команды возвращают exit code 0.
Ошибки валидации флагов, отсутствие токена, сетевые ошибки и API 4xx/5xx возвращают non-zero exit code.
Для CI-скриптов используйте --json, чтобы не парсить человекочитаемый вывод.
Если токен не найден, CLI подскажет: run exl auth login or set EXLOGARE_TOKEN.

Полезные проверки

exl version
exl auth status
exl --help
exl ingest --help
exl analyses list --help
exl tokens create --help

Исходники

CLI открыт под Apache-2.0: