Bucket

Reflag CLI

Интерфейс командной строки для взаимодействия с сервисами Reflag. CLI позволяет управлять приложениями, флагами, аутентификацией и генерировать TypeScript-типы для ваших Reflag-флагов. С помощью этого инструмента вы можете оптимизировать рабочий процесс управления флагами прямо из терминала.

Установка

Установите CLI как зависимость для разработки в вашем проекте:

# npm
npm install --save-dev @reflag/cli

# yarn
yarn add --dev @reflag/cli

Выполните команду new из корневого каталога вашего проекта, чтобы инициализировать CLI, создать флаг и сгенерировать TypeScript-типы одним шагом:

# npm
npx reflag new

# yarn
yarn reflag new

Миграция с Bucket SDK

Если вы переходите с Bucket CLI, вот ключевые изменения, о которых следует знать:

• Название команды: изменено с bucket на reflag
• Файл определений типов: переименован с features.d.ts на flags.d.ts (вручную удалите старый файл, если он был закоммичен)
• Файл аутентификации: изменён с .bucket-auth на .reflag-auth (переименуйте или удалите старый файл)
• Файл конфигурации: изменён с bucket.config.json на reflag.config.json (переименуйте или удалите старый файл)
• Команда: команда features теперь называется flags
• Переменная окружения: используйте REFLAG_API_KEY вместо BUCKET_API_KEY

Важно: Обновите ваши скрипты, шаги сборки и шаблоны .gitignore, чтобы учесть эти изменения.

Отдельные команды

Для большего контроля вы можете запускать каждую команду отдельно:

# Initialize Reflag in your project (if not already setup)
npx reflag init

# Create a new flag
npx reflag flags create "My Flag"

# Generate TypeScript types for your flags
npx reflag flags types

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

CLI создаёт файл reflag.config.json в каталоге вашего проекта при запуске reflag init. Этот файл содержит все необходимые настройки для вашей интеграции с Reflag.

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

Вот все доступные параметры конфигурации в файле reflag.config.json:

{
  "$schema": "https://unpkg.com/@reflag/cli@latest/schema.json",
  "baseUrl": "https://app.reflag.com",
  "apiUrl": "https://app.reflag.com/api",
  "appId": "ap123456789",
  "typesOutput": [
    {
      "path": "gen/flags.d.ts",
      "format": "react"
    }
  ]
}

Параметр	Описание	По умолчанию
$schema	Автодополнение для конфигурации. latest можно заменить на конкретную версию.	" https://unpkg.com/@reflag/cli@latest/schema.json "
baseUrl	Базовый URL для сервисов Reflag.	" https://app.reflag.com "
apiUrl	API URL для сервисов Reflag (переопределяет baseUrl для API-вызовов).	" https://app.reflag.com/api "
appId	Идентификатор вашего приложения Reflag.	Обязательно
typesOutput	Путь(и), куда будут генерироваться TypeScript-типы. Может быть строкой или массивом объектов со свойствами path и format. Доступные форматы: react и node.	"gen/flags.ts" с форматом "react"

Вы можете переопределить эти настройки с помощью параметров командной строки для отдельных команд.

Команды

reflag init

Инициализация новой конфигурации Reflag в вашем проекте. Эта команда создаёт файл reflag.config.json с вашими настройками и запрашивает любую необходимую информацию, не указанную через параметры.

npx reflag init [--overwrite]

Параметры:

• --overwrite: Перезаписать существующий файл конфигурации, если он есть.
• --app-id <id>: Установить идентификатор приложения.
• --key-format <format>: Установить формат ключей для флагов.

reflag new [flagName]

Универсальная команда для быстрого старта. Эта команда объединяет init, создание флага и генерацию типов в один шаг. Используйте её для самого быстрого способа начать работу с Reflag.

npx reflag new "My Flag" [--app-id ap123456789] [--key my-flag]  [--key-format custom] [--out gen/flags.ts] [--format react]

Параметры:

• --key: Конкретный ключ для флага.
• --app-id: Идентификатор приложения для использования.
• --key-format: Формат ключей флагов (custom, snake, camel и т. д.).
• --out: Путь для генерации TypeScript-типов.
• --format: Формат сгенерированных типов (react или node).

Если вы предпочитаете больше контроля над каждым шагом, вы можете использовать отдельные команды (init, flags create, flags types) вместо этого.

reflag login

Аутентификация в вашем аккаунте Reflag. Эта команда безопасно сохраняет ваши учётные данные для последующих операций.

npx reflag login

reflag logout

Выход из аккаунта Reflag и удаление сохранённых учётных данных.

npx reflag logout

reflag flags

Управление флагами Reflag с помощью следующих подкоманд:

reflag flags create [flagName]

Создание нового флага в вашем приложении Reflag. Команда проводит вас через процесс создания флага с помощью интерактивных подсказок, если параметры не указаны.

npx reflag flags create "My Flag" [--app-id ap123456789] [--key my-flag] [--key-format custom]

Параметры:

• --key: Конкретный ключ для флага.
• --app-id: Идентификатор приложения для использования.
• --key-format: Формат ключей флагов.

reflag flags list

Список всех флагов для текущего приложения. Это помогает визуализировать доступные флаги и их текущие конфигурации.

npx reflag flags list [--app-id ap123456789]

Параметры:

• --app-id: Идентификатор приложения для использования.

reflag flags types

Генерация TypeScript-типов для ваших флагов. Это обеспечивает безопасность типов при использовании флагов Reflag в ваших TypeScript/JavaScript-приложениях.

npx reflag flags types [--app-id ap123456789] [--out gen/flags.ts] [--format react]

Параметры:

• --app-id: Идентификатор приложения для использования.
• --out: Путь для генерации TypeScript-типов.
• --format: Формат сгенерированных типов (react или node).

reflag apps

Команды для управления приложениями Reflag.

Глобальные параметры

Эти параметры можно использовать с любой командой:

• --debug: Включить режим отладки для подробного вывода.
• --base-url <url>: Установить базовый URL для Reflag API.
• --api-url <url>: Установить API URL напрямую (переопределяет базовый URL).
• --api-key <key>: API-ключ Reflag для неинтерактивной аутентификации.
• --help: Отобразить справочную информацию для команды.

Разработка с поддержкой ИИ

Reflag предоставляет мощные возможности разработки с поддержкой ИИ через правила и Model Context Protocol (MCP). Эти функции помогают вашим инструментам разработки с ИИ лучше понимать ваши флаги и предоставлять более точную помощь.

Команда rules помогает настроить специфические для ИИ правила в вашем проекте. Эти правила позволяют ИИ-инструментам лучше понимать, как работать с флагами Reflag и как они должны использоваться в вашей кодовой базе.

npx reflag rules [--format <cursor|copilot>] [--yes]

Параметры:

• --format: Формат для добавления правил:
  • cursor: Добавляет правила в .cursor/rules/reflag.mdc для интеграции с Cursor IDE.
    • copilot: Добавляет правила в .github/copilot-instructions.md для интеграции с GitHub Copilot.
• --yes: Пропустить запросы подтверждения и перезаписать существующие файлы без вопросов.

Эта команда добавляет в ваш проект правила, которые предоставляют ИИ-инструментам контекст о том, как настраивать и использовать флаги Reflag. Для формата copilot правила добавляются в выделенный раздел файла, что позволяет поддерживать другие инструкции copilot вместе с правилами Reflag.

Model Context Protocol

Model Context Protocol (MCP) — это открытый протокол, который предоставляет стандартизированный способ подключения ИИ-моделей к различным источникам данных и инструментам. В контексте Reflag MCP позволяет вашему редактору кода понимать ваши флаги, их состояния и их взаимосвязи в вашей кодовой базе. Это создаёт бесшовный мост между вашим рабочим процессом управления флагами и инструментами разработки на основе ИИ. MCP-сервер размещается компанией Reflag, что упрощает начало работы.

**Примечание: Команда Reflag mcp CLI ранее использовалась для _локального сервера. Однако в последних версиях Reflag CLI команда mcp была перепрофилирована, чтобы помочь вам подключиться к новому удалённому MCP-серверу.***

Настройка MCP

Команда mcp помогает настроить ваш редактор или ИИ-клиент для подключения к удалённому MCP-серверу Reflag. Это позволяет вашим ИИ-инструментам понимать ваши флаги и предоставлять более контекстную помощь.

npx reflag mcp [--editor <editor>] [--scope <local|global>]

Параметры:

• --editor: Редактор/клиент для настройки:
  • cursor: Cursor IDE
    • vscode: Visual Studio Code
    • claude: Claude Desktop
    • windsurf: Windsurf
• --scope: Настраивать параметры глобально или локально для проекта.

Команда проведёт вас через:

1. Выбор редактора/клиента для настройки.
2. Выбор приложения Reflag для подключения.
3. Выбор между глобальной или локальной для проекта конфигурацией.
4. Настройку соответствующего файла конфигурации для выбранного редактора.

Примечание: Настройка использует mcp-remote в качестве уровня совместимости, позволяя удалённому размещённому MCP-серверу Reflag работать со всеми редакторами/клиентами, поддерживающими MCP STDIO-серверы. Если ваш редактор/клиент поддерживает HTTP Streaming с OAuth, вы можете подключиться к MCP-серверу Reflag напрямую.

Использование в CI/CD конвейерах

CLI Reflag разработан для бесшовной работы в CI/CD конвейерах. Для автоматизированных сред, где интерактивный вход невозможен, используйте параметр --api-key или укажите API-ключ в переменной окружения REFLAG_API_KEY.

# Generate types in CI/CD
npx reflag apps list --api-key $REFLAG_API_KEY

Важные ограничения:

• При использовании --api-key команды login и logout отключены
• API-ключи обходят все интерактивные потоки аутентификации
• API-ключи привязаны только к одному приложению. Такие команды, как apps list, будут возвращать только привязанное приложение
• Храните API-ключи безопасно, используя управление секретами вашей CI/CD платформы

Пример CI-рабочего процесса:

# GitHub Actions example
- name: Generate types
  run: npx reflag flags types --api-key ${{ secrets.REFLAG_API_KEY }}

# GitHub Actions example (using environment):
- name: Generate types (environment)
  run: npx reflag flags types
  env:
    REFLAG_API_KEY: ${{ secrets.REFLAG_CI_API_KEY }}

Разработка

# Build the CLI
yarn build

# Run the CLI locally
yarn reflag [command]

# Lint and format code
yarn lint
yarn format

Требования

• Node.js >=18.0.0

Лицензия

Лицензия MIT. Copyright (c) 2025 Bucket ApS