Bucket

CLI Reflag

Giao diện dòng lệnh để tương tác với các dịch vụ Reflag. CLI cho phép bạn quản lý ứng dụng, cờ (flags), xác thực và tạo kiểu TypeScript cho các cờ Reflag của bạn. Với công cụ này, bạn có thể tinh gọn quy trình quản lý cờ trực tiếp từ terminal của mình.

Cài đặt

Cài đặt CLI như một dependency phát triển trong dự án của bạn:

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

# yarn
yarn add --dev @reflag/cli

Chạy lệnh new từ thư mục gốc của dự án để khởi tạo CLI, tạo một cờ và tạo kiểu TypeScript trong một bước:

# npm
npx reflag new

# yarn
yarn reflag new

Di chuyển từ Bucket SDK

Nếu bạn đang di chuyển từ Bucket CLI, đây là những thay đổi chính cần lưu ý:

• Tên lệnh: Đổi từ bucket thành reflag
• Tệp định nghĩa kiểu: Đổi tên từ features.d.ts thành flags.d.ts (xóa thủ công tệp cũ nếu nó đã được commit)
• Tệp xác thực: Đổi từ .bucket-auth thành .reflag-auth (đổi tên hoặc xóa tệp cũ)
• Tệp cấu hình: Đổi từ bucket.config.json thành reflag.config.json (đổi tên hoặc xóa tệp cũ)
• Lệnh: Lệnh features hiện là flags
• Biến môi trường: Sử dụng REFLAG_API_KEY thay vì BUCKET_API_KEY

Quan trọng: Cập nhật các script, bước xây dựng và mẫu .gitignore của bạn để phản ánh những thay đổi này.

Các lệnh riêng lẻ

Để kiểm soát tốt hơn, bạn có thể chạy từng lệnh riêng lẻ:

# 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

Cấu hình

CLI tạo một tệp reflag.config.json trong thư mục dự án của bạn khi bạn chạy reflag init. Tệp này chứa tất cả các cài đặt cần thiết cho tích hợp Reflag của bạn.

Cấu trúc tệp cấu hình

Dưới đây là tất cả các tùy chọn cấu hình có sẵn trong tệp 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"
    }
  ]
}

Tùy chọn	Mô tả	Mặc định
$schema	Tự động hoàn thành cho cấu hình. latest có thể được thay thế bằng một phiên bản cụ thể.	" https://unpkg.com/@reflag/cli@latest/schema.json "
baseUrl	URL cơ sở cho các dịch vụ Reflag.	" https://app.reflag.com "
apiUrl	URL API cho các dịch vụ Reflag (ghi đè baseUrl cho các lệnh gọi API).	" https://app.reflag.com/api "
appId	ID ứng dụng Reflag của bạn.	Bắt buộc
typesOutput	(Các) đường dẫn nơi kiểu TypeScript sẽ được tạo. Có thể là chuỗi hoặc mảng các đối tượng với thuộc tính path và format. Các định dạng có sẵn: react và node.	"gen/flags.ts" với định dạng "react"

Bạn có thể ghi đè các cài đặt này bằng các tùy chọn dòng lệnh cho từng lệnh riêng lẻ.

Các lệnh

reflag init

Khởi tạo cấu hình Reflag mới trong dự án của bạn. Lệnh này tạo một tệp reflag.config.json với cài đặt của bạn và nhắc nhập bất kỳ thông tin bắt buộc nào không được cung cấp qua các tùy chọn.

npx reflag init [--overwrite]

Các tùy chọn:

• --overwrite: Ghi đè tệp cấu hình hiện có nếu đã tồn tại.
• --app-id <id>: Đặt ID ứng dụng.
• --key-format <format>: Đặt định dạng khóa cho các cờ.

reflag new [flagName]

Lệnh tất cả trong một để bắt đầu nhanh chóng. Lệnh này kết hợp init, tạo cờ và tạo kiểu trong một bước duy nhất. Sử dụng lệnh này để có cách nhanh nhất bắt đầu với Reflag.

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

Các tùy chọn:

• --key: Khóa cụ thể cho cờ.
• --app-id: ID ứng dụng để sử dụng.
• --key-format: Định dạng cho khóa cờ (custom, snake, camel, v.v.).
• --out: Đường dẫn để tạo kiểu TypeScript.
• --format: Định dạng của kiểu được tạo (react hoặc node).

Nếu bạn muốn kiểm soát nhiều hơn từng bước, bạn có thể sử dụng các lệnh riêng lẻ (init, flags create, flags types) thay thế.

reflag login

Xác thực với tài khoản Reflag của bạn. Lệnh này lưu trữ thông tin xác thực của bạn một cách an toàn cho các thao tác tiếp theo.

npx reflag login

reflag logout

Đăng xuất khỏi tài khoản Reflag của bạn và xóa thông tin xác thực đã lưu.

npx reflag logout

reflag flags

Quản lý các cờ Reflag của bạn với các lệnh con sau:

reflag flags create [flagName]

Tạo một cờ mới trong ứng dụng Reflag của bạn. Lệnh hướng dẫn bạn qua quy trình tạo cờ với các lời nhắc tương tác nếu các tùy chọn không được cung cấp.

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

Các tùy chọn:

• --key: Khóa cụ thể cho cờ.
• --app-id: ID ứng dụng để sử dụng.
• --key-format: Định dạng cho khóa cờ.

reflag flags list

Liệt kê tất cả các cờ cho ứng dụng hiện tại. Điều này giúp bạn hình dung những cờ nào có sẵn và cấu hình hiện tại của chúng.

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

Các tùy chọn:

• --app-id: ID ứng dụng để sử dụng.

reflag flags types

Tạo kiểu TypeScript cho các cờ của bạn. Điều này đảm bảo an toàn kiểu khi sử dụng các cờ Reflag trong ứng dụng TypeScript/JavaScript của bạn.

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

Các tùy chọn:

• --app-id: ID ứng dụng để sử dụng.
• --out: Đường dẫn để tạo kiểu TypeScript.
• --format: Định dạng của kiểu được tạo (react hoặc node).

reflag apps

Các lệnh để quản lý ứng dụng Reflag.

Các tùy chọn toàn cục

Các tùy chọn này có thể được sử dụng với bất kỳ lệnh nào:

• --debug: Bật chế độ gỡ lỗi để có đầu ra chi tiết.
• --base-url <url>: Đặt URL cơ sở cho API Reflag.
• --api-url <url>: Đặt URL API trực tiếp (ghi đè URL cơ sở).
• --api-key <key>: Khóa API Reflag để xác thực không tương tác.
• --help: Hiển thị thông tin trợ giúp cho một lệnh.

Phát triển hỗ trợ AI

Reflag cung cấp các khả năng phát triển hỗ trợ AI mạnh mẽ thông qua các quy tắc và Giao thức Ngữ cảnh Mô hình (MCP). Các tính năng này giúp các công cụ phát triển AI của bạn hiểu rõ hơn về các cờ của bạn và cung cấp hỗ trợ chính xác hơn.

Lệnh rules giúp bạn thiết lập các quy tắc cụ thể cho AI trong dự án của mình. Các quy tắc này cho phép các công cụ AI hiểu rõ hơn cách làm việc với các cờ Reflag và cách chúng nên được sử dụng trong mã nguồn của bạn.

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

Các tùy chọn:

• --format: Định dạng để thêm quy tắc:
  • cursor: Thêm quy tắc vào .cursor/rules/reflag.mdc để tích hợp Cursor IDE.
    • copilot: Thêm quy tắc vào .github/copilot-instructions.md để tích hợp GitHub Copilot.
• --yes: Bỏ qua lời nhắc xác nhận và ghi đè các tệp hiện có mà không hỏi.

Lệnh này thêm các quy tắc vào dự án của bạn cung cấp cho các công cụ AI ngữ cảnh về cách thiết lập và sử dụng các cờ Reflag. Đối với định dạng copilot, các quy tắc được thêm vào một phần chuyên dụng trong tệp, cho phép bạn duy trì các hướng dẫn copilot khác cùng với các quy tắc của Reflag.

Giao thức Ngữ cảnh Mô hình

Giao thức Ngữ cảnh Mô hình (MCP) là một giao thức mở cung cấp một cách chuẩn hóa để kết nối các mô hình AI với các nguồn dữ liệu và công cụ khác nhau. Trong bối cảnh của Reflag, MCP cho phép trình soạn thảo mã của bạn hiểu các cờ, trạng thái của chúng và mối quan hệ của chúng trong mã nguồn. Điều này tạo ra một cầu nối liền mạch giữa quy trình quản lý cờ của bạn và các công cụ phát triển hỗ trợ AI. Máy chủ MCP được lưu trữ bởi Reflag, giúp bạn dễ dàng bắt đầu.

**Lưu ý: Lệnh CLI mcp của Reflag trước đây được sử dụng cho một máy chủ _local. Tuy nhiên, trong các phiên bản gần đây của CLI Reflag, lệnh mcp đã được chuyển đổi mục đích sử dụng để giúp bạn kết nối với máy chủ MCP từ xa mới.**_

Thiết lập MCP

Lệnh mcp giúp bạn cấu hình trình soạn thảo hoặc máy khách AI của mình để kết nối với máy chủ MCP từ xa của Reflag. Điều này cho phép các công cụ AI của bạn hiểu các cờ của bạn và cung cấp hỗ trợ theo ngữ cảnh hơn.

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

Các tùy chọn:

• --editor: Trình soạn thảo/máy khách để cấu hình:
  • cursor: Cursor IDE
    • vscode: Visual Studio Code
    • claude: Claude Desktop
    • windsurf: Windsurf
• --scope: Có cấu hình cài đặt toàn cục hay cục bộ cho dự án hay không.

Lệnh sẽ hướng dẫn bạn qua:

1. Chọn trình soạn thảo/máy khách để cấu hình.
2. Chọn ứng dụng Reflag để kết nối.
3. Quyết định giữa cấu hình toàn cục hoặc cục bộ cho dự án.
4. Thiết lập tệp cấu hình phù hợp cho trình soạn thảo bạn đã chọn.

Lưu ý: Thiết lập sử dụng mcp-remote như một lớp tương thích cho phép máy chủ MCP Reflag từ xa hoạt động với tất cả các trình soạn thảo/máy khách hỗ trợ máy chủ MCP STDIO. Nếu trình soạn thảo/máy khách của bạn hỗ trợ HTTP Streaming với OAuth, bạn có thể kết nối trực tiếp với máy chủ MCP Reflag.

Sử dụng trong các quy trình CI/CD

CLI Reflag được thiết kế để hoạt động liền mạch trong các quy trình CI/CD. Đối với các môi trường tự động nơi không thể đăng nhập tương tác, hãy sử dụng tùy chọn --api-key hoặc chỉ định khóa API trong biến môi trường REFLAG_API_KEY.

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

Các hạn chế quan trọng:

• Khi sử dụng --api-key, các lệnh login và logout bị vô hiệu hóa
• Khóa API bỏ qua tất cả các quy trình xác thực tương tác
• Khóa API chỉ gắn với một ứng dụng. Các lệnh như apps list sẽ chỉ trả về ứng dụng được gắn
• Lưu trữ khóa API một cách an toàn bằng cách sử dụng quản lý bí mật của nền tảng CI/CD của bạn

Ví dụ quy trình 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 }}

Phát triển

# Build the CLI
yarn build

# Run the CLI locally
yarn reflag [command]

# Lint and format code
yarn lint
yarn format

Yêu cầu

• Node.js >=18.0.0

Giấy phép

Giấy phép MIT Bản quyền (c) 2025 Bucket ApS