Перейти к основному содержимому

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

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

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

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

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

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

Без CLI:

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

С CLI:

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

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

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

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

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

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

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

  1. macOS (10.14+)
  2. Linux (Ubuntu 18.04+, Debian 10+, и другие современные дистрибутивы)
  3. 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):

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

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

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

Подробнее см. Работа с 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

CLI:

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

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

Да:

trisigma sl compile --metrics revenue,sessions,conversion_rate

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

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

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

  1. 0. успех
  2. 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 держит в памяти:

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

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

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

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

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

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

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

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

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

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

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

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

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

# Клонируй репозиторий
git clone git@github.com:&lt;your-company&gt;/&lt;your-company&gt;_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 отправляет:

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

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

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

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

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

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

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

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

  1. Немедленно обнови токен:

    trisigma login

  2. Старый токен автоматически станет невалидным

  3. Обратись в безопасность если подозреваешь компрометацию

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

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

  1. Соберите информацию:

    1. Версия CLI (trisigma --version)
    2. Команда которая вызвала ошибку
    3. Полный текст ошибки
    4. Логи (если доступны)

  2. Обратись в поддержку:

    1. Trisigma Support Channel
    2. Trisigma Team Channel

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

Напиши в:

  1. Trisigma Support Channel
  2. Trisigma Team Channel

Опиши:

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

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

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

  1. Настройка Trisigma CLI
  2. Работа с Trisigma CLI
  3. Решение проблем

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