Reflag CLI

用于与Reflag服务交互的命令行界面。CLI允许您管理应用程序、标志、身份验证，并为您的Reflag标志生成TypeScript类型。通过此工具，您可以直接从终端简化标志工作流程。

安装

在项目中作为开发依赖项安装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模式以反映这些更改。

单独命令

为了获得更多的控制，您可以单独运行每个命令：

# 在项目中初始化Reflag（如果尚未设置）
npx reflag init

# 创建一个新的标志
npx reflag flags create "我的标志"

# 为您的标志生成TypeScript类型
npx reflag flags types

配置

当您运行reflag init时，CLI会在您的项目目录中创建一个reflag.config.json文件。该文件包含了您的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	Reflag服务的基础URL。	"https://app.reflag.com"
apiUrl	Reflag服务的API URL（覆盖基础URL进行API调用）。	"https[://app.reflag.com/api"
appId	您的Reflag应用ID。	必填
typesOutput	TypeScript类型将被生成的路径。可以是一个字符串或具有path和format属性的对象数组。可用格式：react和node。	"gen/flags.ts" 格式为 "react"

您可以使用命令行选项覆盖这些设置。

命令

reflag init

在项目中初始化新的Reflag配置。这会创建一个带有您设置的reflag.config.json文件，并提示获取任何未通过选项提供的必要信息。

npx reflag init [--overwrite]

选项：

• --overwrite：如果存在，则覆盖现有配置文件。
• --app-id <id>：设置应用ID。
• --key-format <format>：设置标志键的格式。

reflag new [flagName]

快速开始的一站式命令。此命令结合了init、标志创建和类型生成。使用此命令以最快的方式启动Reflag。

npx reflag new "我的标志" [--app-id ap123456789] [--key 我的标志]  [--key-format custom] [--out gen/flags.ts] [--format react]

选项：

• --key：特定的标志键。
• --app-id：要使用的应用ID。
• --key-format：标志键的格式（自定义、蛇形、驼峰等）。
• --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 "我的标志" [--app-id ap123456789] [--key 我的标志] [--key-format custom]

选项：

• --key：特定的标志键。
• --app-id：要使用的应用ID。
• --key-format：标志键的格式。

reflag flags list

列出当前应用的所有标志。这有助于您可视化可用标志及其当前配置。

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

选项：

• --app-id：要使用的应用ID。

reflag flags types

为您的标志生成TypeScript类型。这确保了在您的TypeScript/JavaScript应用程序中使用Reflag标志时的类型安全性。

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

选项：

• --app-id：要使用的应用ID。
• --out：生成TypeScript类型的路径。
• --format：生成类型的格式（react或node）。

reflag apps

管理Reflag应用的命令。

全局选项

这些选项可用于任何命令：

• --debug：启用调试模式以显示详细输出。
• --base-url <url>：设置Reflag API的基础URL。
• --api-url <url>：直接设置API URL（覆盖基础URL）。
• --api-key <key>：非交互式身份验证的Reflag API密钥。
• --help：显示命令的帮助信息。

AI辅助开发

Reflag通过规则和模型上下文协议（MCP）提供了强大的AI辅助开发能力。这些功能帮助您的AI开发工具更好地理解您的标志，并提供更准确的协助。

Reflag规则（推荐）

rules命令帮助您为项目设置AI特定规则。这些规则使AI工具能够更好地了解如何与Reflag标志一起工作以及它们应该如何在您的代码库中使用。

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

选项：

• --format：添加规则的格式：
  • cursor：将规则添加到.cursor/rules/reflag.mdc以实现与Cursor IDE的集成。
  • copilot：将规则添加到.github/copilot-instructions.md以实现GitHub Copilot的集成。
• --yes：跳过确认提示并覆盖现有文件而不询问。

此命令向您的项目添加规则，为AI工具提供有关如何设置和使用Reflag标志的上下文。对于copilot格式，规则被添加到文件中的专用部分，允许您维护其他copilot指令与Reflag规则并存。

模型上下文协议

模型上下文协议（MCP）是一种开放协议，提供了一种标准化的方法来连接AI模型与不同的数据源和工具。在Reflag的背景下，MCP使您的代码编辑器能够理解您的标志、它们的状态以及它们在代码库中的关系。这创建了一个无缝的桥梁，连接您的标志管理工作流程和AI驱动的开发工具。Reflag托管MCP服务器，使其易于上手。

注意：Reflag的mcp CLI命令之前用于本地服务器。然而，在Reflag CLI的最新版本中，mcp命令已被重新设计，帮助您连接到新的远程MCP服务器。

设置MCP

mcp命令帮助您配置编辑器或AI客户端以连接到Reflag的远程MCP服务器。这使得您的AI工具能够理解您的标志并提供更具体的协助。

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作为兼容层，允许远程托管的Reflag MCP服务器与支持MCP STDIO服务器的所有编辑器/客户端协同工作。如果您的编辑器/客户端支持HTTP流传输和OAuth，可以直接连接到Reflag MCP服务器。

在CI/CD管道中使用（测试版）

Reflag CLI旨在无缝地在CI/CD管道中使用。在无法进行交互式登录的自动化环境中，使用--api-key选项或在REFLAG_API_KEY环境变量中指定API密钥。

# 在CI/CD中生成类型
npx reflag apps list --api-key $REFLAG_API_KEY

重要限制：

• 使用--api-key时，login和logout命令被禁用
• API密钥绕过了所有交互式认证流程
• API密钥仅绑定到一个应用。如apps list命令只会返回绑定的应用
• 使用CI/CD平台的安全管理功能存储API密钥

示例CI工作流程：

# GitHub Actions示例
- name: 生成类型
  run: npx reflag flags types --api-key ${{ secrets.REFLAG_API_KEY }}

# GitHub Actions示例（使用环境）：
- name: 生成类型（环境）
  run: npx reflag flags types
  env:
    REFLAG_API_KEY: ${{ secrets.REFLAG_CI_API_KEY }}

开发

# 构建CLI
yarn build

# 在本地运行CLI
yarn reflag [command]

# 检查和格式化代码
yarn lint
yarn format

要求

• Node.js >=18.0.0

许可证

MIT许可证 版权所有 (c) 2025 Bucket ApS