Bucket

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 패턴을 이러한 변경 사항에 맞게 업데이트하세요.

개별 명령

더 세밀한 제어가 필요한 경우 각 명령을 개별적으로 실행할 수 있습니다:

# 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

구성

CLI는 reflag.config.json 명령을 실행할 때 프로젝트 디렉토리에 reflag init 파일을 생성합니다. 이 파일에는 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 (API 호출 시 baseUrl을 재정의).	" 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 "My Flag" [--app-id ap123456789] [--key my-flag]  [--key-format custom] [--out gen/flags.ts] [--format react]

옵션:

• --key: 플래그의 특정 키.
• --app-id: 사용할 앱 ID.
• --key-format: 플래그 키 형식 (custom, snake, camel 등).
• --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 "My Flag" [--app-id ap123456789] [--key my-flag] [--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는 규칙과 Model Context Protocol(MCP)을 통해 강력한 AI 지원 개발 기능을 제공합니다. 이러한 기능은 AI 개발 도구가 플래그를 더 잘 이해하고 더 정확한 지원을 제공할 수 있도록 도와줍니다.

rules 명령은 프로젝트에 AI 특화 규칙을 설정하는 데 도움이 됩니다. 이러한 규칙은 AI 도구가 Reflag 플래그를 사용하는 방법과 코드베이스에서 플래그를 사용해야 하는 방식을 더 잘 이해할 수 있게 합니다.

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

옵션:

• --format: 규칙을 추가할 형식:
  • cursor: Cursor IDE 통합을 위해 .cursor/rules/reflag.mdc에 규칙을 추가합니다.
    • copilot: GitHub Copilot 통합을 위해 .github/copilot-instructions.md에 규칙을 추가합니다.
• --yes: 확인 프롬프트를 건너뛰고 기존 파일을 묻지 않고 덮어씁니다.

이 명령은 AI 도구에 Reflag 플래그 설정 및 사용 방법에 대한 컨텍스트를 제공하는 규칙을 프로젝트에 추가합니다. copilot 형식의 경우 규칙은 파일의 전용 섹션에 추가되어 Reflag 규칙과 함께 다른 copilot 지침을 유지할 수 있습니다.

Model Context Protocol

Model Context Protocol(MCP)은 AI 모델을 다양한 데이터 소스와 도구에 연결하는 표준화된 방법을 제공하는 개방형 프로토콜입니다. Reflag의 맥락에서 MCP는 코드 편집기가 플래그, 플래그 상태, 코드베이스 내 관계를 이해할 수 있게 합니다. 이는 플래그 관리 워크플로우와 AI 기반 개발 도구 사이에 원활한 브리지를 만듭니다. MCP 서버는 Reflag에서 호스팅하므로 쉽게 시작할 수 있습니다.

**참고: 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 서버를 지원하는 모든 편집기/클라이언트에서 작동하도록 합니다. 편집기/클라이언트가 OAuth를 통한 HTTP Streaming을 지원하는 경우 Reflag MCP 서버에 직접 연결할 수 있습니다.

CI/CD 파이프라인에서 사용

Reflag CLI는 CI/CD 파이프라인에서 원활하게 작동하도록 설계되었습니다. 대화형 로그인이 불가능한 자동화 환경에서는 --api-key 옵션을 사용하거나 REFLAG_API_KEY 환경 변수에 API 키를 지정하세요.

# Generate types in 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 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 }}

개발

# Build the CLI
yarn build

# Run the CLI locally
yarn reflag [command]

# Lint and format code
yarn lint
yarn format

요구 사항

• Node.js >=18.0.0

라이선스

MIT License Copyright (c) 2025 Bucket ApS