CLI - FailproofAI

AgentEye CLI (agenteye) — это терминальный клиент для вашего развёртывания AgentEye. Он запрашивает ваши данные (сеансы, журналы событий, оценки) и управляет организацией (ключи API, пользователи, параметры, оповещения, инциденты, сохранённые запросы) — всё, что делает панель управления, из скрипта или кодирующего агента. Каждая команда поддерживает флаг --json, поэтому она одинаково хорошо работает как для человека в терминале, так и для кодирующего агента (Claude Code, Cursor), который её вызывает и обрабатывает результат.

Это CLI agenteye, отличный от коллектора (agenteye-collector). CLI общается с вашей панелью управления; коллектор отправляет события на сервер. См. Установка коллектора для коллектора.

Установка

CLI опубликован в публичном PyPI как agenteye. Поскольку Python SDK AgentEye также использует имя дистрибутива agenteye, установите CLI в изолированной среде (pipx или uv tool), чтобы эти два инструмента никогда не конфликтовали в одном virtualenv:

pipx install agenteye
# или
uv tool install agenteye

Обычная установка через pip install agenteye также работает, если вы не устанавливаете Python SDK в ту же среду. CLI требует Python 3.10+ и не нуждается в токене GitHub; это публичный пакет. Установленная команда — agenteye:

agenteye --version
agenteye --help

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

CLI аутентифицируется на панели управления с помощью отправленного по почте одноразового кода:

agenteye login --email you@example.com
# На вашу почту отправится 6-значный код; вставьте его в приглашение.

Токен сеанса сохраняется в ~/.agenteye/cli.json (доступен только вам, права 0600) и по умолчанию действителен 24 часа. По истечении срока действия снова запустите agenteye login.

agenteye whoami     # показать текущего пользователя, активную организацию и права доступа
agenteye logout     # отозвать сеанс и удалить сохранённый токен

whoami никогда не вызывает ошибку при отсутствующем или истёкшем сеансе — вместо этого сообщает logged_in: false, поэтому скрипт или агент может безопасно проверить состояние аутентификации (но может завершиться с ненулевым кодом, если базовый URL не установлен или панель управления недоступна). Требования: ваша электронная почта должна быть разрешена для входа на панель управления (обратитесь к администратору AgentEye), и панель управления должна быть доступна по своему базовому URL (см. Конфигурация). Если вы запросили код и он не пришёл, ваша почта, вероятно, ещё не включена для доступа к панели управления.

Выбор организации (мультитенантность)

Если ваша учётная запись принадлежит нескольким организациям, выберите активную при входе — она будет сохранена и использоваться для всех последующих команд:

agenteye login --org acme           # аутентифицировать и установить активного тенанта в один шаг
agenteye orgs list                  # организации, к которым вы можете получить доступ (активная отмечена)
agenteye orgs switch globex         # изменить сохранённое значение по умолчанию
agenteye --org globex sessions      # переопределить для одной команды

Если вы принадлежите ровно одной организации, она выбирается автоматически и вы можете полностью игнорировать --org. Если вы принадлежите нескольким и не выбираете одну, CLI их список и просит переиспользовать --org <slug>. Активная организация отправляется на панель управления при каждом запросе, и ваши права решаются для каждой организации — agenteye whoami показывает активную организацию, ваши права в ней и все ваши членства.

Конфигурация

Параметр	Флаг	Переменная окружения	По умолчанию
Базовый URL панели управления	`--base-url`	`AGENTEYE_DASHBOARD_URL`	обязателен (нет значения по умолчанию)
Активная организация/тенант	`--org`	`AGENTEYE_ORG`	выбирается при входе; сохраняется в `~/.agenteye/cli.json`
Токен сеанса	`--token`	`AGENTEYE_CLI_TOKEN`	из `~/.agenteye/cli.json`
Вывод JSON	`--json`	`AGENTEYE_CLI_JSON`	выключен
Пропустить проверку TLS	`--insecure` / `--secure`	`AGENTEYE_INSECURE`	выключен (сохраняется при входе)
Тайм-аут запроса (секунды)	`--timeout`	—	30
Отключить телеметрию использования	(нет)	`AGENTEYE_ANALYTICS_DISABLED` (или `DO_NOT_TRACK`)	выключен (телеметрия включена)

Порядок разрешения: флаг → переменная окружения → файл конфигурации. По умолчанию нет; вы должны указать CLI на вашу панель управления, либо для каждой команды (--base-url https://agenteye.example.com), либо один раз через окружение (она также сохраняется после первого login):

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com

Каталог конфигурации учитывает AGENTEYE_HOME (то же соглашение, используемое SDK и коллектором); если задано, cli.json находится в $AGENTEYE_HOME/cli.json.

Самоподписанные или внутренние сертификаты TLS

Если ваша панель управления обслуживается по HTTPS с самоподписанным или внутренним сертификатом (например, имя хоста сырого load-balancer’а), проверка TLS его отклонит с ошибкой CERTIFICATE_VERIFY_FAILED. Передайте --insecure для пропуска проверки сертификата:

agenteye --base-url https://agenteye.internal --insecure login

--insecure сохраняется в cli.json при входе, поэтому более поздние команды автоматически пропускают проверку; вам не нужно повторять флаг. Передайте --secure для единоразового проверяемого вызова или для повторного включения проверки при следующем входе. CLI выводит предупреждение в stderr перед любой командой, которая обращается к панели управления с отключённой проверкой. Пропуск проверки устраняет защиту от атак «человек посередине»; убедитесь, что вы доверяете сетевому пути к вашей панели управления (VPN, приватная подсеть и т.д.), прежде чем на неё полагаться.

Телеметрия и конфиденциальность

CLI отправляет анонимную аналитику использования на сервис аналитики Exosphere (PostHog): какие команды запускаются (например, sessions, keys create), прошли ли они успешно и сколько времени заняло. Этот сигнал использования информирует о приоритизации функций.

Данные агента, сеанса или события никогда не покидают вашу инфраструктуру. Сообщается только использование CLI: имя команды и подкоманды (например, keys create), имена используемых флагов (никогда не их значения), статус успеха/выхода и длительность — плюс событие за действие для мутаций (например, api_key_created, query_run), содержащее только статические имена/перечисления и приблизительные счёты. Ваш URL панели управления, токен сеанса, почта, slug организации, идентификаторы ресурсов, SQL, секреты ключей и фильтры запросов никогда не отправляются. Операторы идентифицируются только по непрозрачному внутреннему id, никогда по почте.
Телеметрия включена по умолчанию. Чтобы её отключить, установите AGENTEYE_ANALYTICS_DISABLED=1 в окружении CLI (CLI также учитывает кроссутильное соглашение DO_NOT_TRACK=1).
CLI отправляет напрямую на PostHog (https://us.i.posthog.com). Машине, на которой работает CLI, нужен исходящий доступ к этому хосту; если он заблокирован, телеметрия молча ничего не делает (отправка ограничена по времени, поэтому никогда не задерживает и не ломает команду) и CLI не затронут.

Глобальные опции и соглашения

Прочитайте это один раз; это применяется к каждой команде.

Глобальные опции идут ДО команды. agenteye --json sessions верно; agenteye sessions --json — ошибка использования. Глобальные — это --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet и --no-color.
--json выводит чистый JSON в stdout и больше ничего. Строки статуса человека, предупреждения и ошибки идут в stderr, поэтому захват stdout --json остаётся чистым для передачи в jq даже когда показана строка статуса. Без --json вы получаете оформленный, раскрашенный вид для человеческих глаз.
Открывайте с помощью --help. Каждая команда и подкоманда имеет --help (и псевдоним -h): agenteye -h, agenteye sessions -h, agenteye keys create -h. Справка верхнего уровня также перечисляет коды выхода и глобальные опции. Нет глобального машиночитаемого дампа поверхности; используйте для каждой команды --help, плюс специфичные для домена agenteye query schema и agenteye settings schema.
Подтверждения автоматически пропускаются для скриптов и агентов. Команды create/update/delete подсказывают «вы уверены?» в интерактивном терминале, но автоматически пропускают подсказку при --json или когда stdin — не TTY — поэтому скрипты и агенты никогда не зависают. Передайте --yes/-y для явного пропуска. Поскольку подсказка не сработает для агента, агент должен сначала подтвердить деструктивные действия с человеком.
Постраничный вывод: результаты новые первые и курсор-постраничные. --limit N (псевдоним -n) ограничивает строки и по умолчанию 50; --all автопостраничивает (порциями по 200 строк) вплоть до --limit — поэтому простой --all всё равно останавливается в 50. Для полного сканирования передайте высокий явный лимит: --all --limit 1000. --page-size N контролирует порцию на запрос (максимум 200); --cursor <id> возобновляет с next_cursor предыдущей страницы.
Фильтры времени: --since принимает относительное окно — 15m, 1h, 6h, 24h, 7d, 30d или all (предустановки панели управления). --from/--to принимают явные временные метки ISO-8601 UTC с T и временной зоной (например, 2026-06-01T00:00:00Z) для пользовательского диапазона и переопределяют --since; разделённое пробелом или без временной зоны значение — ошибка использования.
--fields a,b,c (на events, sessions, evals, errors) ограничивает вывод этими ключами, для таблицы и --json. Неизвестные имена отклоняются с действительным списком — дешёвый способ открыть имена полей.
--file payload.json (или --file - для чтения stdin) поставляет полное тело JSON запроса где ресурс имеет сложную форму — на alerts create/update, settings set и users create/update. SQL сохранённого запроса использует --sql @file.sql.
Фильтры с несколькими значениями разделены запятыми → сопоставлены как набор (объединение в одном фильтре, AND через фильтры): --event-type tool_use,tool_result. Опции Click не вариадичны, поэтому --add a b ломает — используйте --add a,b, повторите флаг (--add a --add b) или кавычки (--add "a b").

Справочник команд

CLI имеет 18 команд верхнего уровня. Все команды чтения принимают --json и глобальные опции выше; запустите agenteye <command> -h (или <command> <subcommand> -h) для исчерпывающего списка флагов и формы JSON любой из них.

agenteye login --email you@example.com [--org acme]   # одноразовый код по почте; сохраняет сеанс
agenteye logout                                       # очистить сохранённый сеанс на этой машине
agenteye whoami                                       # текущий пользователь, активная организация, права
agenteye version                                      # вывести версию CLI (то же, что --version)
agenteye help                                         # справка верхнего уровня (то же, что --help)

orgs проверяет и переключает активного тенанта:

agenteye orgs list        # ваши организации + ваша роль в каждой (активная отмечена)
agenteye orgs switch acme # изменить сохранённую активную организацию (пропустите slug для выбора списка на TTY)
agenteye orgs current     # карточка идентификации активной организации
agenteye orgs perms       # ваши права в активной организации, сгруппированные по ресурсам

Наблюдение (только чтение) — `events` · `sessions` · `evals` · `errors` · `list`

Ни один из них не нуждается в подтверждении. Общие фильтры: --session-id, --agent-id, --env (не --environment) и временной диапазон (--since / --from / --to).

# события (псевдоним: след на этапе) — новые первые
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000
agenteye --json events --since 1h --search timeout --all | jq '.events[].payload'

# сеансы — одна строка на запуск агента (время/окружение/агент/сеанс/статус; без фильтра оценки)
agenteye --json sessions --since 24h --status error
agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000

# оценки — результаты оценки + оценки; --score фильтрует по метрике, --aggregate сводит
agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
agenteye --json evals --aggregate --since 7d --env prod        # микс статусов + статистика оценок по ключам

# ошибки — события с ошибками; --aggregate для счётов/сеансов/агентов/последнего-видел
agenteye --json errors --since 24h --aggregate
agenteye --json errors --since 24h --error-type timeout --all --limit 1000

# list — открыть действительные значения фильтров перед фильтрацией
agenteye list envs        # также: agents event_types score_filters models hooks triggers tools error_types

--score KEY:MIN..MAX (на evals, не sessions) повторяется и AND-комбинируется; граница опциональна (..0.5 означает ≤ 0.5, 0.9.. означает ≥ 0.9). До 20 фильтров оценок на запрос. evals --scores-full возвращает полный объект оценки вместо сводки. Для чтения одного сеанса конец-в-конец, объедините тропу события с его оценкой:

agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
agenteye --json evals  --session-id run-001                       # его оценки + статус

Управление (ограничено правами) — `keys` · `users` · `settings` · `alerts` · `incidents`

keys — ключи API. Секрет генерируется локально, отправляется на сервер (который хранит только хэш) и показывается один раз на create/regenerate — захватите его тогда. При --json он появляется только в поле key. На что ссылаются по имени.

agenteye keys list                                   # активные ключи первые, затем отозванные
agenteye keys show ci-bot
agenteye keys create ci-bot --add events:read.add    # область охвата, что вам нужно; выводит секрет ОДИН РАЗ
agenteye keys create ops --permission-set standard --remove queries:run   # инициализируйте предустановкой, затем обрежьте
agenteye keys update ci-bot --add evaluations:read --yes
agenteye keys regenerate ci-bot --yes                # ротация секрета (старый переходит в стоп)
agenteye keys disable ci-bot --yes                   # отозвать

Права работают как (permission-set ∪ --add) − --remove. Токены — это slug:action (например, events:read) или slug:action.action для расширения нескольких на одном ресурсе (events:read.add → events:read, events:add). Предустановки: read-only, standard, admin. Права только для человека (keys:update) не могут быть выданы ключу. users — члены организации, на которых ссылаются по почте (UUID id также принимается).

agenteye users list [--active-only]
agenteye users show dev@corp.com
agenteye users create dev@corp.com --permission-set standard
agenteye users update dev@corp.com --add alerts:write --remove queries:delete   # предсказывает + подтверждает
agenteye users disable dev@corp.com --yes            # имеет защищённые/самозащитные охраны
agenteye users enable dev@corp.com

settings — фиксированный реестр (вы читаете и изменяете существующие ключи; вы не можете создавать новые).

agenteye settings list                               # ключ · значение · тип · обновлено (секреты скрыты)
agenteye settings schema                             # что каждый ключ принимает (тип · диапазон · описание)
agenteye settings set session_ttl_secs --value 86400 --yes

alerts — определения оповещений, на которые ссылаются по имени. create принимает позиционное ИМЯ плюс флаги или полное тело JSON через --file.

agenteye alerts list
agenteye alerts show high-errors
agenteye alerts create high-errors --file alert.json          # ИМЯ обязательно (позиционный)
agenteye alerts update high-errors --severity critical --yes
agenteye alerts test high-errors --yes                        # отправить тестовое уведомление
agenteye alerts delete high-errors --yes

incidents — инциденты оповещений, на которые ссылаются по id (короткие id приняты). show выводит полный журнал активности — прочитайте его перед действием.

agenteye incidents list --state firing                # также: acknowledged, resolved
agenteye incidents count
agenteye incidents show <id>
agenteye incidents ack <id>
agenteye incidents assign <id> you@corp.com           # назначенный должен быть оператором
agenteye incidents resolve <id> --yes
agenteye incidents open --alert-id <id> --severity critical    # открыть один вручную против оповещения
agenteye incidents comment-add <id> "root cause: upstream 5xx"
agenteye incidents comment-list <id> ; agenteye incidents comment-delete <id> <comment-id>
agenteye incidents subscribe <id> ; agenteye incidents unsubscribe <id> ; agenteye incidents subscribers <id>

Аналитика и помощник — `query` · `agent`

query — сохранённый SQL ClickHouse плюс ad-hoc runner. Сохранённые запросы на которые ссылаются по имени; SQL проверяется на стороне сервера (только SELECT/WITH, тайм-аут оператора, ограничение строк).

agenteye query schema [TABLE]                         # раскладка столбцов аналитических представлений
agenteye query run --sql "select count(*) from analytics.events"
agenteye query run errs --arg prod --limit 100        # запустить сохранённый запрос + позиционный $1
agenteye query list ; agenteye query show errs
agenteye query create errs --sql @errs.sql --description "errored events (24h)"
agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes

agent — встроенный помощник панели управления (тот же аналитик только для чтения, с которым вы можете общаться в панели управления). Чаты на которые ссылаются по короткому chat-id (разрешение префиксом).

agenteye agent health                                 # помощник настроен/доступен
agenteye agent models                                 # модели, которые вы можете передать в --model (по умолчанию отмечена)
agenteye agent ask "which agents errored most in the last day?"    # запускает чат; выводит его короткий id
agenteye agent ask --chat <short-id> "and which tools did they call?"   # продолжить тот чат
agenteye agent chats ; agenteye agent show <short-id>
agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>

Коды выхода

Код	Значение
0	Успех
1	Неожиданная ошибка (например, панель управления вернула 5xx)
2	Ошибка использования (неправильные аргументы, неизвестная команда/флаг, коллизия имён)
3	Невозможно достичь панель управления
4	Не вошли или сеанс истёк; запустите `agenteye login`
5	Аутентифицированы, но вашей учётной записи не хватает требуемого права (сообщение его называет)
6	Запрошенный ресурс не найден (например, неизвестный id сеанса или инцидента)

Это делает CLI безопасным для скриптов: кодирующий агент может ветвиться на 4 для подсказки вам переаутентифицироваться, или на 5 для поверхности отсутствующего права. См. CLI рецепты для агентов для обработки кодов выхода и форм вывода JSON.

См. также

CLI рецепты для агентов — скопируйте-вставьте шаблоны запросов, одноразовые jq, проекции --fields, обработка кодов выхода и формы вывода JSON, написанные для кодирующих агентов, управляющих CLI.
Навык CLI AgentEye — упакуйте этот CLI как устанавливаемый навык Claude Code / Codex, чтобы кодирующий агент управлял AgentEye из запросов на простом английском.
Ключи API — модель прав за keys create --add ….
ИИ помощник — включение помощника, с которым общается agent ask.

​Установка

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

​Выбор организации (мультитенантность)

​Конфигурация

​Самоподписанные или внутренние сертификаты TLS

​Телеметрия и конфиденциальность

​Глобальные опции и соглашения

​Справочник команд

​Идентификация — login · logout · whoami · orgs · version · help

​Наблюдение (только чтение) — events · sessions · evals · errors · list

​Управление (ограничено правами) — keys · users · settings · alerts · incidents

​Аналитика и помощник — query · agent

​Коды выхода

​См. также