Bucket

CLI do Reflag

Interface de linha de comando para interagir com os serviços do Reflag. A CLI permite gerenciar apps, flags, autenticação e gerar tipos TypeScript para suas flags do Reflag. Com esta ferramenta, você pode otimizar seu fluxo de trabalho de flags diretamente do seu terminal.

Instalação

Instale a CLI como uma dependência de desenvolvimento no seu projeto:

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

# yarn
yarn add --dev @reflag/cli

Execute o comando new a partir do diretório raiz do seu projeto para inicializar a CLI, criar uma flag e gerar tipos TypeScript em uma única etapa:

# npm
npx reflag new

# yarn
yarn reflag new

Migrando do SDK do Bucket

Se você está migrando da CLI do Bucket, aqui estão as principais mudanças que você deve conhecer:

• Nome do comando: Alterado de bucket para reflag
• Arquivo de definições de tipos: Renomeado de features.d.ts para flags.d.ts (remova manualmente o arquivo antigo se ele foi commitado)
• Arquivo de autenticação: Alterado de .bucket-auth para .reflag-auth (renomeie ou remova o arquivo antigo)
• Arquivo de configuração: Alterado de bucket.config.json para reflag.config.json (renomeie ou remova o arquivo antigo)
• Comando: O comando features agora é flags
• Variável de ambiente: Use REFLAG_API_KEY em vez de BUCKET_API_KEY

Importante: Atualize seus scripts, etapas de build e padrões de .gitignore para refletir essas mudanças.

Comandos Individuais

Para mais controle, você pode executar cada comando individualmente:

# 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

Configuração

A CLI cria um arquivo reflag.config.json no diretório do seu projeto quando você executa reflag init. Este arquivo contém todas as configurações necessárias para sua integração com o Reflag.

Estrutura do Arquivo de Configuração

Aqui estão todas as opções de configuração disponíveis no arquivo 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"
    }
  ]
}

Opção	Descrição	Padrão
$schema	Autocompletar para a configuração. latest pode ser substituído por uma versão específica.	" https://unpkg.com/@reflag/cli@latest/schema.json "
baseUrl	URL base para os serviços do Reflag.	" https://app.reflag.com "
apiUrl	URL da API para os serviços do Reflag (substitui a baseUrl para chamadas de API).	" https://app.reflag.com/api "
appId	ID do seu aplicativo Reflag.	Obrigatório
typesOutput	Caminho(s) onde os tipos TypeScript serão gerados. Pode ser uma string ou um array de objetos com propriedades path e format. Formatos disponíveis: react e node.	"gen/flags.ts" com formato "react"

Você pode substituir essas configurações usando opções de linha de comando para comandos individuais.

Comandos

reflag init

Inicialize uma nova configuração do Reflag no seu projeto. Isso cria um arquivo reflag.config.json com suas configurações e solicita qualquer informação obrigatória não fornecida por meio de opções.

npx reflag init [--overwrite]

Opções:

• --overwrite: Sobrescrever o arquivo de configuração existente, se houver.
• --app-id <id>: Definir o ID do aplicativo.
• --key-format <format>: Definir o formato de chave para as flags.

reflag new [flagName]

Comando tudo-em-um para começar rapidamente. Este comando combina init, criação de flag e geração de tipos em uma única etapa. Use-o para a maneira mais rápida de começar a usar o Reflag.

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

Opções:

• --key: Chave específica para a flag.
• --app-id: ID do app a ser usado.
• --key-format: Formato para as chaves das flags (custom, snake, camel, etc.).
• --out: Caminho para gerar os tipos TypeScript.
• --format: Formato dos tipos gerados (react ou node).

Se você preferir mais controle sobre cada etapa, pode usar os comandos individuais (init, flags create, flags types).

reflag login

Autentique-se com sua conta do Reflag. Isso armazena suas credenciais com segurança para operações subsequentes.

npx reflag login

reflag logout

Saia da sua conta do Reflag e remova as credenciais armazenadas.

npx reflag logout

reflag flags

Gerencie suas flags do Reflag com estes subcomandos:

reflag flags create [flagName]

Crie uma nova flag no seu app Reflag. O comando guia você pelo processo de criação de flags com prompts interativos se as opções não forem fornecidas.

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

Opções:

• --key: Chave específica para a flag.
• --app-id: ID do app a ser usado.
• --key-format: Formato para as chaves das flags.

reflag flags list

Liste todas as flags do app atual. Isso ajuda você a visualizar quais flags estão disponíveis e suas configurações atuais.

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

Opções:

• --app-id: ID do app a ser usado.

reflag flags types

Gere tipos TypeScript para suas flags. Isso garante segurança de tipos ao usar flags do Reflag em seus aplicativos TypeScript/JavaScript.

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

Opções:

• --app-id: ID do app a ser usado.
• --out: Caminho para gerar os tipos TypeScript.
• --format: Formato dos tipos gerados (react ou node).

reflag apps

Comandos para gerenciar apps do Reflag.

Opções Globais

Estas opções podem ser usadas com qualquer comando:

• --debug: Ativar o modo de depuração para saída detalhada.
• --base-url <url>: Definir a URL base para a API do Reflag.
• --api-url <url>: Definir a URL da API diretamente (substitui a URL base).
• --api-key <key>: Chave de API do Reflag para autenticação não interativa.
• --help: Exibir informações de ajuda para um comando.

Desenvolvimento Assistido por IA

O Reflag fornece poderosos recursos de desenvolvimento assistido por IA por meio de regras e Protocolo de Contexto de Modelo (MCP). Esses recursos ajudam suas ferramentas de desenvolvimento de IA a entender melhor suas flags e fornecer assistência mais precisa.

O comando rules ajuda você a configurar regras específicas de IA para seu projeto. Essas regras permitem que as ferramentas de IA entendam melhor como trabalhar com flags do Reflag e como elas devem ser usadas no seu código.

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

Opções:

• --format: Formato para adicionar regras:
  • cursor: Adiciona regras ao .cursor/rules/reflag.mdc para integração com o IDE Cursor.
    • copilot: Adiciona regras ao .github/copilot-instructions.md para integração com o GitHub Copilot.
• --yes: Pular prompts de confirmação e sobrescrever arquivos existentes sem perguntar.

Este comando adiciona regras ao seu projeto que fornecem contexto às ferramentas de IA sobre como configurar e usar flags do Reflag. Para o formato copilot, as regras são adicionadas a uma seção dedicada no arquivo, permitindo que você mantenha outras instruções do copilot junto com as regras do Reflag.

Protocolo de Contexto de Modelo

O Protocolo de Contexto de Modelo (MCP) é um protocolo aberto que fornece uma maneira padronizada de conectar modelos de IA a diferentes fontes de dados e ferramentas. No contexto do Reflag, o MCP permite que seu editor de código entenda suas flags, seus estados e suas relações dentro do seu código. Isso cria uma ponte perfeita entre seu fluxo de trabalho de gerenciamento de flags e ferramentas de desenvolvimento com IA. O servidor MCP é hospedado pelo Reflag, facilitando o início.

**Nota: O comando mcp da CLI do Reflag era usado anteriormente para um servidor _local. No entanto, em versões recentes da CLI do Reflag, o comando mcp foi reaproveitado para ajudar você a se conectar ao novo servidor MCP remoto.**_

Configurando o MCP

O comando mcp ajuda você a configurar seu editor ou cliente de IA para se conectar ao servidor MCP remoto do Reflag. Isso permite que suas ferramentas de IA entendam suas flags e forneçam assistência mais contextual.

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

Opções:

• --editor: O editor/cliente a ser configurado:
  • cursor: Cursor IDE
    • vscode: Visual Studio Code
    • claude: Claude Desktop
    • windsurf: Windsurf
• --scope: Se deve configurar as configurações globalmente ou localmente para o projeto.

O comando irá guiá-lo por:

1. Selecionar qual editor/cliente configurar.
2. Escolher qual app Reflag conectar.
3. Decidir entre configuração global ou local do projeto.
4. Configurar o arquivo de configuração apropriado para o editor escolhido.

Nota: A configuração usa mcp-remote como uma camada de compatibilidade que permite que o servidor MCP remoto hospedado do Reflag funcione com todos os editores/clientes que suportam servidores MCP STDIO. Se seu editor/cliente suporta HTTP Streaming com OAuth, você pode se conectar diretamente ao servidor MCP do Reflag.

Uso em Pipelines de CI/CD

A CLI do Reflag foi projetada para funcionar perfeitamente em pipelines de CI/CD. Para ambientes automatizados onde o login interativo não é possível, use a opção --api-key ou especifique a chave de API na variável de ambiente REFLAG_API_KEY.

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

Restrições importantes:

• Ao usar --api-key, os comandos login e logout são desabilitados
• As chaves de API ignoram todos os fluxos de autenticação interativos
• As chaves de API estão vinculadas a apenas um app. Comandos como apps list retornarão apenas o app vinculado
• Armazene as chaves de API com segurança usando o gerenciamento de segredos da sua plataforma de CI/CD

Exemplo de fluxo de trabalho de 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 }}

Desenvolvimento

# Build the CLI
yarn build

# Run the CLI locally
yarn reflag [command]

# Lint and format code
yarn lint
yarn format

Requisitos

• Node.js >=18.0.0

Licença

Licença MIT Copyright (c) 2025 Bucket ApS