Часто задаваемые вопросы (FAQ)#

Ответы на часто задаваемые вопросы о Trisigma CLI.

Общие вопросы#

Что такое Trisigma CLI?#

Trisigma CLI — это инструмент командной строки для работы с репозиторием метрик в Trisigma. Он позволяет локально валидировать изменения, генерировать SQL, работать с Git и многое другое без необходимости создавать PR для каждой проверки.

Зачем мне нужен этот CLI?#

Без CLI:

Создаешь PR → ждешь CI/CD → видишь ошибку → правишь → повторяешь
Нужно понимать как работает компилятор метрик
Сложно быстро проверить SQL для конкретного источника

С CLI:

Валидируешь локально за секунды
Видишь сгенерированный SQL сразу
Получаешь AI-объяснения ошибок на русском
Автоматическая перекомпиляция при изменениях (watch режим)

Нужно ли мне знать Python чтобы использовать CLI?#

Нет! CLI работает как обычная консольная программа. Установка выполняется автоматическим скриптом.

Могу ли я использовать CLI в CI/CD?#

Да! CLI отлично подходит для автоматизации в CI/CD пайплайнах.

Подробнее см. Практические сценарии.

Какие операционные системы поддерживаются?#

✅ macOS (10.14+)
✅ Linux (Ubuntu 18.04+, Debian 10+, и другие современные дистрибутивы)
⚠️ Windows (через WSL2)

Установка и настройка#

Как установить CLI?#

sudo curl -sSL https://pastebin.com/raw/JwywS2A8 | tr -d '\r' | bash

Подробнее см. Установка.

Как обновить CLI?#

trisigma self-update

Где хранится конфигурация CLI?#

В директории ~/.trisigma/:

~/.trisigma/
├── config.json       # Основная конфигурация
└── cache/            # Кеш результатов валидации

Для сброса конфигурации:

trisigma config --clear

Безопасно ли хранить токен в конфигурации?#

Да. Токен хранится в ~/.trisigma/config.json с правами доступа 0600 (только твой пользователь может читать). Директория ~/.trisigma имеет права 0700.

Как переавторизоваться в Trisigma?#

trisigma login

CLI откроет браузер для повторной авторизации через OAuth.

Работа с CLI#

Как выбрать между интерактивным и командным режимом?#

Интерактивный режим (trisigma):

Исследование репозитория
Визуальный интерфейс
AI-объяснения прямо в интерфейсе
Git workflow с диалогами

Командный режим (trisigma sl <команда>):

Автоматизация и скрипты
CI/CD пайплайны
Сохранение результатов в файлы
Быстрое выполнение конкретной задачи

Подробнее см. Работа с Trisigma CLI.

Как валидировать репозиторий?#

trisigma sl validate

С AI-объяснением ошибок:

trisigma sl validate --ai-explain

Как сгенерировать SQL для источника?#

trisigma sl compile --source events

С параметрами:

trisigma sl compile --source events \
  --dimensions vertical,logical_category \
  --first-date 2025-01-01 \
  --last-date 2025-01-31 \
  --granularity day

Как сохранить сгенерированный SQL в файл?#

trisigma sl compile --source events --output events.sql

Что такое режим watch и как его использовать?#

Режим watch автоматически перекомпилирует SQL при изменении файлов:

trisigma sl compile --source events --watch

Очень удобно для отладки: редактируешь файл в редакторе → сохраняешь → CLI автоматически показывает результат!

Подробнее см. Командный режим.

Как работать с Git через CLI?#

# Создать ветку для задачи
trisigma sl task AB-1234 "Описание задачи"

# Сохранить изменения
trisigma sl save -m "Описание изменений"

# Опубликовать ветку
trisigma sl publish

Подробнее см. Git Workflow.

AI-объяснения#

Что такое AI-объяснения?#

AI-объяснения — это функция которая отправляет ошибки валидации в LLM и получает подробное объяснение на русском языке с рекомендациями по исправлению.

Как использовать AI-объяснения?#

В командном режиме:

trisigma sl validate --ai-explain

В интерактивном режиме:

Запусти валидацию
Если есть ошибки — нажми A
Получи AI-анализ в модальном окне

Обязательно ли настраивать LLM?#

Нет, LLM настройка полностью опциональна. CLI работает и без LLM, просто AI-объяснения будут недоступны.

Как настроить LLM?#

Интерактивный режим:

trisigma
# Выбери "Settings" → настрой LLM Provider URL и Token

Командный режим:

trisigma init
# При настройке укажи LLM Provider URL и Token

Какие данные CLI отправляет в LLM?#

CLI отправляет только:

Ошибки валидации
Содержимое файлов репозитория метрик (YAML, SQL) для контекста

CLI НЕ отправляет:

Личные данные
Историю команд
Содержимое других файлов на твоем компьютере

Валидация и компиляция#

Что проверяет валидация?#

Валидация проверяет:

Структуру репозитория (наличие обязательных директорий и файлов)
Синтаксис YAML и SQL файлов
Корректность ссылок между источниками, дименшенами и метриками
Соответствие правилам именования
Полноту обязательных полей

Почему валидация выполняется долго?#

Валидация отправляет содержимое репозитория в Trisigma API для проверки. Скорость зависит от:

Размера репозитория
Скорости сетевого соединения
Нагрузки на API

CLI кеширует результаты валидации для ускорения повторных проверок.

Как работает компиляция SQL?#

CLI:

Собирает содержимое файлов репозитория (sources.yaml, dimensions.yaml, SQL-файлы)
Отправляет в Trisigma API с параметрами запроса
API генерирует SQL на основе метаданных и шаблонов
CLI получает и форматирует результат

Можно ли скомпилировать несколько метрик сразу?#

Да:

trisigma sl compile --metrics revenue,sessions,conversion_rate

Автоматизация#

Как использовать CLI в скриптах?#

CLI возвращает код выхода:

0 — успех
1 — ошибка

Пример:

#!/bin/bash

if trisigma sl validate; then
  echo "✓ Валидация прошла"
  trisigma sl save -m "Auto commit"
else
  echo "✗ Валидация не прошла"
  exit 1
fi

Как сохранить результаты в файл?#

# Сохранить вывод валидации
trisigma sl validate > validation.txt 2>&1

# Сохранить SQL
trisigma sl compile --source events --output events.sql

# Сохранить список источников
trisigma sl list-sources > sources.txt

Производительность#

Как часто CLI проверяет обновления?#

CLI проверяет обновления раз в 24 часа при запуске команд (кроме init, login, self-update). Проверка выполняется в фоне и не замедляет работу.

Можно ли отключить проверку обновлений?#

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

Почему интерактивный режим потребляет много памяти?#

TUI держит в памяти:

Содержимое репозитория (sources, dimensions, metrics)
Кеш результатов валидации
Мониторинг изменений файлов

Для больших репозиториев используй командный режим.

Интеграция с другими инструментами#

Как использовать CLI вместе с конфигуратором?#

CLI и конфигуратор могут работать параллельно:

CLI — для локальной валидации и генерации SQL
Конфигуратор — для визуального редактирования метрик

Установочный скрипт автоматически изолирует зависимости CLI от окружения конфигуратора.

Можно ли использовать CLI с разными репозиториями?#

Да! Для каждого репозитория:

cd ~/projects/repo1
trisigma init  # настроить для repo1

cd ~/projects/repo2
trisigma init  # настроить для repo2

Пример для ab-metrics:

Если репозиторий еще не склонирован:

# Клонируй репозиторий
git clone git@github.com:<your-company>/<your-company>_ab_metrics.git ~/projects/ab-metrics

# Перейди в репозиторий и настрой CLI
cd ~/projects/ab-metrics
trisigma init

Или создай алиасы:

alias ts-repo1='cd ~/projects/repo1 && trisigma'
alias ts-repo2='cd ~/projects/repo2 && trisigma'

Как интегрировать CLI в VS Code?#

Добавь задачи в .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Validate Metrics",
      "type": "shell",
      "command": "trisigma sl validate",
      "problemMatcher": []
    },
    {
      "label": "Compile SQL",
      "type": "shell",
      "command": "trisigma sl compile --source ${input:sourceName}",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "sourceName",
      "type": "promptString",
      "description": "Source name"
    }
  ]
}

Теперь можно запускать валидацию через меню Terminal → Run Task.

Безопасность#

Какие данные CLI отправляет на сервер?#

CLI отправляет:

Содержимое файлов репозитория метрик (YAML, SQL) для валидации
Параметры запросов для генерации SQL
Ошибки валидации для AI-объяснения (опционально)

CLI НЕ отправляет:

Личные данные
Историю команд
Содержимое других файлов на твоем компьютере

Как работает авторизация?#

CLI использует OAuth 2.0 localhost callback flow:

CLI открывает браузер со страницей авторизации Trisigma
После входа в систему, Trisigma генерирует JWT токен
Trisigma перенаправляет браузер обратно на localhost с токеном
CLI получает токен и сохраняет его в конфигурацию

Токен имеет срок действия 365 дней.

Что делать если токен утек?#

Немедленно обнови токен:
```
trisigma login
```
Старый токен автоматически станет невалидным
Обратись в безопасность если подозреваешь компрометацию

Обратная связь#

Как сообщить об ошибке?#

Соберите информацию:
Версия CLI (trisigma --version)
Команда которая вызвала ошибку
Полный текст ошибки
Логи (если доступны)
Обратись в поддержку:
Trisigma Support Channel
Trisigma Team Channel

Как предложить новую функцию?#

Напиши в:

Trisigma Support Channel
Trisigma Team Channel

Опиши:

Какую задачу ты хочешь решить
Как ты это делаешь сейчас
Как новая функция упростит работу

Где найти документацию?#

Вся документация находится в директории docs/ репозитория CLI или по адресу:

🏠 Вернуться к главной странице