Bucket MCP Server

Reflag CLI

Interface de linha de comando para interagir com os serviços 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 com flags diretamente do terminal.

Instalação

Instale a CLI como 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 Bucket SDK

Se você está migrando da Bucket CLI, aqui estão as principais mudanças a serem observadas:

• Nome do comando: Alterado de bucket para reflag
• Arquivo de definições de tipo: 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:

Inicializa o Reflag no seu projeto (se ainda não estiver configurado)

npx reflag init

Cria uma nova flag

npx reflag flags create "Minha Flag"

Gera tipos TypeScript para suas 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 Reflag.	"https://app.reflag.com"
apiUrl	URL da API para os serviços Reflag (substitui baseUrl para chamadas de API).	"https://app.reflag.com/api"
appId	Seu ID de aplicação 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

Inicializa 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 necessária não fornecida via opções.

npx reflag init [--overwrite]

Opções:

• --overwrite: Substitui o arquivo de configuração existente, se houver.
• --app-id <id>: Define o ID da aplicação.
• --key-format <format>: Define o formato da 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 "Minha Flag" [--app-id ap123456789] [--key minha-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 chaves de flag (custom, snake, camel, etc.).
• --out: Caminho para gerar os tipos TypeScript.
• --format: Formato dos tipos gerados (react ou node).

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

reflag login

Autentica-se com sua conta Reflag. Isso armazena suas credenciais de forma segura para operações subsequentes.

npx reflag login

reflag logout

Sai da sua conta Reflag e remove as credenciais armazenadas.

npx reflag logout

reflag flags

Gerencie suas flags do Reflag com estes subcomandos:

reflag flags create [flagName]

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

npx reflag flags create "Minha Flag" [--app-id ap123456789] [--key minha-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 chaves de flag.

reflag flags list

Lista todas as flags do app atual. Isso ajuda 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

Gera tipos TypeScript para suas flags. Isso garante segurança de tipos ao usar flags do Reflag em suas aplicações 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 Reflag.

Opções Globais

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

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

Desenvolvimento Assistido por IA

O Reflag oferece recursos poderosos de desenvolvimento assistido por IA por meio de regras e Model Context Protocol (MCP). Esses recursos ajudam suas ferramentas de desenvolvimento de IA a entender melhor suas flags e fornecer assistência mais precisa.

Regras do Reflag (Recomendado)

O comando rules ajuda a configurar regras específicas de IA para o seu projeto. Essas regras permitem que as ferramentas de IA entendam melhor como trabalhar com flags do Reflag e como elas devem ser usadas em sua base de 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 Cursor IDE.
  • copilot: Adiciona regras ao .github/copilot-instructions.md para integração com GitHub Copilot.
• --yes: Pula prompts de confirmação e substitui arquivos existentes sem perguntar.

Este comando adiciona regras ao seu projeto que fornecem às ferramentas de IA contexto 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 juntamente com as regras do Reflag.

Model Context Protocol

O Model Context Protocol (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 seus relacionamentos dentro da sua base de código. Isso cria uma ponte perfeita entre seu fluxo de trabalho de gerenciamento de flags e ferramentas de desenvolvimento alimentadas por 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 redirecionado para ajudá-lo a se conectar ao novo servidor MCP remoto.**

Configurando o MCP

O comando mcp ajuda 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 ] [--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 a configuração deve ser global ou local para o projeto.

O comando irá guiá-lo através de:

1. Selecionar qual editor/cliente configurar.
2. Escolher a qual app Reflag se conectar.
3. Decidir entre configuração global ou local ao 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, permitindo que o servidor MCP remoto hospedado do Reflag funcione com todos os editores/clientes que suportam servidores MCP STDIO. Se seu editor/cliente suportar HTTP Streaming com OAuth, você pode se conectar diretamente ao servidor MCP do Reflag.

Uso em Pipelines de CI/CD (Beta)

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.

Gerar tipos em 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
• Chaves de API ignoram todos os fluxos de autenticação interativa
• Chaves de API são vinculadas a apenas um app. Comandos como apps list retornarão apenas o app vinculado
• Armazene chaves de API de forma segura usando o gerenciamento de segredos da sua plataforma de CI/CD

Exemplo de fluxo de trabalho CI:

Exemplo do GitHub Actions

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

Exemplo do GitHub Actions (usando environment):

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

Desenvolvimento

Compila a CLI

yarn build

Executa a CLI localmente

yarn reflag [comando]

Lint e formatação de código

yarn lint yarn format

Requisitos

• Node.js >=18.0.0

Licença

MIT License Copyright (c) 2025 Bucket ApS