Интерфейс командной строки (CLI)

Интерфейс командной строки (CLI) — это консольный инструмент для администрирования системы 5А. CLI построен как тонкий клиент к REST API системы и использует те же механизмы авторизации, контроля доступа и аудита, что и пользовательский интерфейс.

На текущем этапе CLI поддерживает только операции чтения (read-only). В будущем функциональность будет расширена.

Установка и доступность

Бинарный файл 5a поставляется в составе offline-инсталлятора системы 5А. В процессе установки он размещается в каталоге /usr/local/bin/ на хосте, где выполняется установка.

Если CLI отсутствует в системе, его можно скопировать из инсталлятора вручную или запросить у администратора.

Проверьте установленную версию:

5a version

Пример вывода:

Client Version: v0.1.1
Build Date: 2026-07-07T11:00:42Z
API Contract: v0.83.13-cli
Go Version: go1.24.0
Platform: linux/amd64

Конфигурация и авторизация

Для работы с CLI необходима авторизация с использованием персонального токена доступа (PAT). CLI не использует короткоживущие JWT, вся работа строится на долгоживущих PAT.

Команда login

Команда login выполняет аутентификацию пользователя и создаёт PAT, который сохраняется в локальный конфигурационный файл для последующих вызовов.

5a login --server <URL> --email <email>

Обязательные параметры:

• --server — URL API сервера (например, https://api.5a.local или http://172.27.1.19:8443).
• --email — логин учётной записи (email пользователя).

Пароль вводится интерактивно (приглашение Password:). Если флаг --email не указан, CLI запросит его интерактивно.

Дополнительные параметры:

• --name — задаёт имя создаваемого PAT (по умолчанию используется имя хоста). Это имя отображается в списке токенов в UI.
• --no-input — отключает интерактивный ввод; если какие-то обязательные параметры не указаны, команда завершается ошибкой.

После успешной аутентификации CLI создаёт PAT и сохраняет его в файл конфигурации ~/.5a/config.yml (права доступа 600). В дальнейшем все команды используют этот токен автоматически.

Если требуется сменить учётную запись, достаточно выполнить login заново — новый PAT перезапишет старый. При необходимости можно удалить файл ~/.5a/config.yml вручную.

Файл конфигурации

Настройки CLI хранятся в файле ~/.5a/config.yml. Пример содержимого:

server: "https://api.5a.local"
token: "pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
cluster: "prod-cluster"

Параметры:

• server — базовый URL API системы 5А.
• token — персональный токен доступа (PAT).
• cluster — имя или UUID кластера, используемое по умолчанию для команд, требующих указания кластера.

Переменная окружения

Для использования CLI в скриптах можно задать токен через переменную окружения A5_TOKEN. Если переменная определена, её значение имеет приоритет над токеном из конфигурационного файла, но уступает явно указанному флагу --token.

export A5_TOKEN="pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
5a get clusters

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

Все команды CLI поддерживают следующие глобальные флаги:

Обратите внимание: флаг --token используется только для текущего вызова, он не сохраняется в конфигурационный файл.

Команды

version

Выводит информацию о версии CLI, времени сборки, контракте API, версии Go и целевой платформе.

5a version

Флаг --verbose добавляет дополнительную диагностическую информацию (например, версию backend-контракта, хеш коммита и дату сборки).

login

Выполняет аутентификацию и создаёт PAT. Подробное описание — в разделе Конфигурация и авторизация.

5a login --server https://api.5a.local --email user@example.com

get clusters

Получает список всех кластеров балансировки, доступных текущему пользователю.

5a get clusters

get services

Получает список сервисов (конфигураций балансировки) для указанного кластера. Кластер обязательно должен быть задан через флаг -c или --cluster.

5a get services -c prod-cluster

Если в качестве значения -c передано имя кластера, CLI выполняет запрос к /clusters и фильтрует результат для получения UUID. Передача UUID также допустима.

get agents

Получает список агентов балансировки в указанном кластере.

5a get agents -c prod-cluster

get node-groups

Получает список групп узлов (node groups) в указанном кластере.

5a get node-groups -c prod-cluster

get monitors

Получает список мониторов здоровья, настроенных в указанном кластере.

5a get monitors -c prod-cluster

get tokens

Получает список персональных токенов доступа (PAT) текущего пользователя. Эта команда не требует указания кластера.

5a get tokens

Вывод содержит информацию об имени, дате создания, сроке действия и времени последнего использования каждого токена. Секретное значение токена не отображается.

get users

Получает список пользователей системы. Эта команда доступна только пользователям с соответствующими правами и не требует указания кластера.

5a get users

Форматы вывода

Для любой команды можно задать один из трёх форматов вывода с помощью флага -o или --output:

• table — человекочитаемая таблица (по умолчанию).
• json — структурированный JSON-документ.
• yaml — структурированный YAML-документ.

Примеры использования

1. Авторизация с указанием сервера и email

5a login --server https://api.5a.local --email admin@example.com
# Введите пароль

2. Просмотр кластеров

5a get clusters

3. Просмотр сервисов в кластере с выводом в YAML

5a get services -c prod-cluster -o yaml

4. Использование переменной окружения для токена

export A5_TOKEN=pat_xxxxxxxxxxxx
5a get clusters --server https://api.5a.local

5. Получение списка агентов в кластере

5a get agents -c 550e8400-e29b-41d4-a716-446655440000

6. Просмотр списка своих токенов

5a get tokens

7. Диагностика с подробными логами

5a get clusters --verbose

Связанные разделы:

• Управление доступом — информация о пользователях, ролях, группах и правах.
• API системы — описание REST API, с которым взаимодействует CLI.
• Лицензирование — управление лицензиями системы.