Bucket

Reflag CLI

Interfaz de línea de comandos para interactuar con los servicios de Reflag. La CLI te permite gestionar aplicaciones, flags, autenticación y generar tipos TypeScript para tus flags de Reflag. Con esta herramienta, puedes optimizar tu flujo de trabajo con flags directamente desde tu terminal.

Instalación

Instala la CLI como dependencia de desarrollo en tu proyecto:

npm

npm install --save-dev @reflag/cli

yarn

yarn add --dev @reflag/cli

Ejecuta el comando new desde el directorio raíz de tu proyecto para inicializar la CLI, crear un flag y generar tipos TypeScript en un solo paso:

npm

npx reflag new

yarn

yarn reflag new

Migrando desde Bucket SDK

Si estás migrando desde la CLI de Bucket, estos son los cambios clave a tener en cuenta:

• Nombre del comando: Cambió de bucket a reflag
• Archivo de definiciones de tipos: Renombrado de features.d.ts a flags.d.ts (elimina manualmente el archivo antiguo si estaba en el control de versiones)
• Archivo de autenticación: Cambió de .bucket-auth a .reflag-auth (renombra o elimina el archivo antiguo)
• Archivo de configuración: Cambió de bucket.config.json a reflag.config.json (renombra o elimina el archivo antiguo)
• Comando: El comando features ahora es flags
• Variable de entorno: Usa REFLAG_API_KEY en lugar de BUCKET_API_KEY

Importante: Actualiza tus scripts, pasos de compilación y patrones de .gitignore para reflejar estos cambios.

Comandos Individuales

Para mayor control, puedes ejecutar cada comando individualmente:

Inicializa Reflag en tu proyecto (si aún no está configurado)

npx reflag init

Crea un nuevo flag

npx reflag flags create "Mi Flag"

Genera tipos TypeScript para tus flags

npx reflag flags types

Configuración

La CLI crea un archivo reflag.config.json en el directorio de tu proyecto cuando ejecutas reflag init. Este archivo contiene todos los ajustes necesarios para tu integración con Reflag.

Estructura del Archivo de Configuración

Aquí están todas las opciones de configuración disponibles en el archivo 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" } ] }

Opción	Descripción	Valor por defecto
$schema	Autocompletado para la configuración. latest puede reemplazarse con una versión específica.	"https://unpkg.com/@reflag/cli@latest/schema.json"
baseUrl	URL base para los servicios de Reflag.	"https://app.reflag.com"
apiUrl	URL de la API para los servicios de Reflag (anula baseUrl para las llamadas a la API).	"https://app.reflag.com/api"
appId	Tu ID de aplicación de Reflag.	Requerido
typesOutput	Ruta(s) donde se generarán los tipos TypeScript. Puede ser una cadena o un array de objetos con propiedades path y format. Formatos disponibles: react y node.	"gen/flags.ts" con formato "react"

Puedes anular estos ajustes usando opciones de línea de comandos para comandos individuales.

Comandos

reflag init

Inicializa una nueva configuración de Reflag en tu proyecto. Esto crea un archivo reflag.config.json con tus ajustes y solicita cualquier información requerida no proporcionada a través de opciones.

npx reflag init [--overwrite]

Opciones:

• --overwrite: Sobrescribe el archivo de configuración existente si hay uno.
• --app-id <id>: Establece el ID de la aplicación.
• --key-format <format>: Establece el formato de clave para los flags.

reflag new [flagName]

Comando todo en uno para empezar rápidamente. Este comando combina init, la creación de flags y la generación de tipos en un solo paso. Úsalo para la forma más rápida de ponerte en marcha con Reflag.

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

Opciones:

• --key: Clave específica para el flag.
• --app-id: ID de la aplicación a usar.
• --key-format: Formato para las claves de los flags (custom, snake, camel, etc.).
• --out: Ruta para generar los tipos TypeScript.
• --format: Formato de los tipos generados (react o node).

Si prefieres más control sobre cada paso, puedes usar los comandos individuales (init, flags create, flags types) en su lugar.

reflag login

Autentícate con tu cuenta de Reflag. Esto almacena tus credenciales de forma segura para operaciones posteriores.

npx reflag login

reflag logout

Cierra sesión de tu cuenta de Reflag y elimina las credenciales almacenadas.

npx reflag logout

reflag flags

Gestiona tus flags de Reflag con estos subcomandos:

reflag flags create [flagName]

Crea un nuevo flag en tu aplicación de Reflag. El comando te guía a través del proceso de creación del flag con indicaciones interactivas si no se proporcionan opciones.

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

Opciones:

• --key: Clave específica para el flag.
• --app-id: ID de la aplicación a usar.
• --key-format: Formato para las claves de los flags.

reflag flags list

Lista todos los flags de la aplicación actual. Esto te ayuda a visualizar qué flags están disponibles y sus configuraciones actuales.

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

Opciones:

• --app-id: ID de la aplicación a usar.

reflag flags types

Genera tipos TypeScript para tus flags. Esto asegura la seguridad de tipos al usar flags de Reflag en tus aplicaciones TypeScript/JavaScript.

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

Opciones:

• --app-id: ID de la aplicación a usar.
• --out: Ruta para generar los tipos TypeScript.
• --format: Formato de los tipos generados (react o node).

reflag apps

Comandos para gestionar aplicaciones de Reflag.

Opciones Globales

Estas opciones se pueden usar con cualquier comando:

• --debug: Habilita el modo de depuración para una salida detallada.
• --base-url <url>: Establece la URL base para la API de Reflag.
• --api-url <url>: Establece la URL de la API directamente (anula la URL base).
• --api-key <key>: Clave de API de Reflag para autenticación no interactiva.
• --help: Muestra información de ayuda para un comando.

Desarrollo Asistido por IA

Reflag proporciona potentes capacidades de desarrollo asistido por IA a través de reglas y el Protocolo de Contexto del Modelo (MCP). Estas características ayudan a tus herramientas de desarrollo de IA a comprender mejor tus flags y proporcionar asistencia más precisa.

Reglas de Reflag (Recomendado)

El comando rules te ayuda a configurar reglas específicas de IA para tu proyecto. Estas reglas permiten que las herramientas de IA comprendan mejor cómo trabajar con los flags de Reflag y cómo deben usarse en tu base de código.

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

Opciones:

• --format: Formato en el que añadir las reglas:
  • cursor: Añade reglas a .cursor/rules/reflag.mdc para la integración con Cursor IDE.
  • copilot: Añade reglas a .github/copilot-instructions.md para la integración con GitHub Copilot.
• --yes: Omite las solicitudes de confirmación y sobrescribe los archivos existentes sin preguntar.

Este comando añade reglas a tu proyecto que proporcionan a las herramientas de IA contexto sobre cómo configurar y usar los flags de Reflag. Para el formato copilot, las reglas se añaden a una sección dedicada en el archivo, permitiéndote mantener otras instrucciones de copilot junto con las reglas de Reflag.

Protocolo de Contexto del Modelo

El Protocolo de Contexto del Modelo (MCP) es un protocolo abierto que proporciona una forma estandarizada de conectar modelos de IA a diferentes fuentes de datos y herramientas. En el contexto de Reflag, MCP permite que tu editor de código comprenda tus flags, sus estados y sus relaciones dentro de tu base de código. Esto crea un puente perfecto entre tu flujo de trabajo de gestión de flags y las herramientas de desarrollo impulsadas por IA. El servidor MCP está alojado por Reflag, lo que facilita empezar.

**Nota: El comando de CLI mcp de Reflag se usaba anteriormente para un servidor local. Sin embargo, en versiones recientes de la CLI de Reflag, el comando mcp ha sido reutilizado para ayudarte a conectarte al nuevo servidor MCP remoto.**

Configurando MCP

El comando mcp te ayuda a configurar tu editor o cliente de IA para conectarse con el servidor MCP remoto de Reflag. Esto permite que tus herramientas de IA comprendan tus flags y proporcionen asistencia más contextual.

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

Opciones:

• --editor: El editor/cliente a configurar:
  • cursor: Cursor IDE
  • vscode: Visual Studio Code
  • claude: Claude Desktop
  • windsurf: Windsurf
• --scope: Si se debe configurar los ajustes de forma global o local para el proyecto.

El comando te guiará a través de:

1. Seleccionar qué editor/cliente configurar.
2. Elegir a qué aplicación de Reflag conectarse.
3. Decidir entre configuración global o local al proyecto.
4. Configurar el archivo de configuración apropiado para el editor elegido.

Nota: La configuración usa mcp-remote como una capa de compatibilidad que permite que el servidor MCP remoto alojado de Reflag funcione con todos los editores/clientes que soportan servidores MCP STDIO. Si tu editor/cliente soporta HTTP Streaming con OAuth, puedes conectarte al servidor MCP de Reflag directamente.

Uso en Pipelines de CI/CD (Beta)

La CLI de Reflag está diseñada para funcionar sin problemas en pipelines de CI/CD. Para entornos automatizados donde el inicio de sesión interactivo no es posible, usa la opción --api-key o especifica la clave de API en la variable de entorno REFLAG_API_KEY.

Generar tipos en CI/CD

npx reflag apps list --api-key $REFLAG_API_KEY

Restricciones importantes:

• Al usar --api-key, los comandos login y logout están deshabilitados
• Las claves de API omiten todos los flujos de autenticación interactiva
• Las claves de API están vinculadas a una sola aplicación. Comandos como apps list solo devolverán la aplicación vinculada
• Almacena las claves de API de forma segura usando la gestión de secretos de tu plataforma de CI/CD

Ejemplo de flujo de trabajo de CI:

Ejemplo de GitHub Actions

• name: Generar tipos run: npx reflag flags types --api-key ${{ secrets.REFLAG_API_KEY }}

Ejemplo de GitHub Actions (usando entorno):

• name: Generar tipos (entorno) run: npx reflag flags types env: REFLAG_API_KEY: ${{ secrets.REFLAG_CI_API_KEY }}

Desarrollo

Construir la CLI

yarn build

Ejecutar la CLI localmente

yarn reflag [comando]

Lint y formatear código

yarn lint yarn format

Requisitos

• Node.js >=18.0.0

Licencia

Licencia MIT Copyright (c) 2025 Bucket ApS