Bucket CLI

用于与Bucket服务交互的命令行界面。CLI允许你管理应用程序、功能、认证，并为你的Bucket功能生成TypeScript类型。通过这个工具，你可以直接从终端简化你的功能标记工作流程。

使用方法

首先在你的项目中本地安装CLI：

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

# yarn
yarn add --dev @bucketco/cli

然后从项目的根目录运行new命令，一次性完成CLI初始化、创建功能以及生成类型的操作：

# npm
npx bucket new

# yarn
yarn bucket new

单个命令

你可以选择不运行new，而是单独调用每个步骤。

# Initialize Bucket in your project (if not already setup)
npx bucket init

# Create a new feature
npx bucket features create "My Feature"

# Generate TypeScript types for your features
npx bucket features types

配置

当你运行bucket init时，CLI会在你的项目目录中创建一个bucket.config.json文件。该文件包含了所有必要的Bucket集成设置。

配置文件结构

以下是bucket.config.json文件中可用配置选项的完整列表：

{
  "$schema": "https://unpkg.com/@bucketco/cli@latest/schema.json",
  "baseUrl": "https://app.bucket.co",
  "apiUrl": "https://app.bucket.co/api",
  "appId": "ap123456789",
  "typesOutput": [
    {
      "path": "gen/features.d.ts",
      "format": "react"
    }
  ]
}

选项	描述	默认值
$schema	用于配置自动完成功能。latest可以被替换为特定版本。	"https://unpkg.com/@bucketco/cli@latest/schema.json"
baseUrl	Bucket服务的基础URL。	"https://app.bucket.co"
apiUrl	Bucket服务的API URL（对于API调用将覆盖baseUrl）。	"https://app.bucket.co/api"
appId	你的Bucket应用ID。	必须提供
typesOutput	生成TypeScript类型的路径。可以是字符串或具有path和format属性的对象数组。可用格式：react 和 node。	格式为"react"的"gen/features.ts"

你可以使用单个命令的命令行选项来覆盖这些设置。

命令

bucket init

在你的项目中初始化一个新的Bucket配置。
这将创建一个带有你的设置的bucket.config.json文件，并提示输入任何未通过选项提供的必填信息。

npx bucket init [--overwrite]

选项：

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

bucket new [featureName]

一个全能命令，用于快速开始。该命令将 init、功能创建和类型生成合并为一步完成。使用此命令可以最快地启动并运行 Bucket。

npx bucket new "My Feature" [--key my-feature] [--app-id ap123456789] [--key-format custom] [--out gen/features.ts] [--format react]

选项：

• --key: 功能的具体键。
• --app-id: 要使用的应用 ID。
• --key-format: 功能键的格式（自定义、snake_case、camelCase 等）。
• --out: 生成 TypeScript 类型的路径。
• --format: 生成类型的格式（react 或 node）。

如果您希望对每个步骤有更多控制，可以使用单独的命令（init、features create、features types）。

bucket login

登录您的 Bucket 账户。这将验证您的 CLI 以便进行后续操作，并安全存储凭据。

npx bucket login

bucket logout

从您的 Bucket 账户注销，移除已存储的凭据。

npx bucket logout

bucket features

通过以下子命令管理您的 Bucket 功能。

bucket features create [featureName]

在您的 Bucket 应用中创建新功能。如果未提供选项，该命令将通过交互式提示引导您完成功能创建过程。

npx bucket features create "My Feature" [--key my-feature] [--app-id ap123456789] [--key-format custom]

选项：

• --key: 功能的具体键。
• --app-id: 要使用的应用 ID。
• --key-format: 功能键的格式。

bucket features list

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

npx bucket features list [--app-id ap123456789]

选项：

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

bucket features types

为您的功能生成 TypeScript 类型。这确保了在 TypeScript/JavaScript 应用程序中使用 Bucket 功能时的类型安全。

npx bucket features types [--app-id ap123456789] [--out gen/features.ts] [--format react]

选项：

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

bucket companies

用于管理公司的命令。

bucket companies list

列出您的应用中的所有公司。

npx bucket companies list [--filter <text>] [--app-id ap123456789]

选项：

• --filter: 按名称或 ID 过滤公司。
• --app-id: 要使用的应用 ID。

该命令输出包含以下列的表格：

• id: 公司 ID。
• name: 公司名称（如果未设置则显示“(未命名)”）。
• users: 公司中的用户数量。
• lastSeen: 公司最后活跃的日期。

bucket companies features access

授予或撤销特定功能对公司、细分市场和用户的访问权限。如果没有提供功能键，系统将提示您从列表中选择一个。

npx bucket companies features access [featureKey] [--enable|--disable] [--companies <id...>] [--segments <id...>] [--users <id...>] [--app-id ap123456789]

参数：

• featureKey: 授予/撤销访问权限的功能键（可选，如果省略则交互式选择）。

选项：

• --enable: 为指定的目标启用功能。
• --disable: 为指定的目标禁用功能。
• --users: 目标用户ID。可以多次指定。
• --companies: 目标公司ID。可以多次指定。
• --segments: 目标分段ID。可以多次指定。
• --app-id: 要使用的应用ID。

至少需要指定一个目标（公司、分段或用户）。你还必须指定 --enable 或 --disable 中的一个，但不能同时指定两者。

示例：

# Enable feature for multiple companies and users
npx bucket companies features access my-feature --enable --companies comp_123 --companies comp_456 --users user_789

bucket apps

用于管理Bucket应用的命令。

全局选项

这些选项可以与任何命令一起使用：

• --debug: 启用调试模式以输出详细信息。
• --base-url <url>: 设置Bucket API的基础URL。
• --api-url <url>: 直接设置API URL（覆盖基础URL）。
• --help: 显示命令的帮助信息。

AI辅助开发

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

Bucket规则（推荐）

rules 命令帮助你为项目设置AI特定的规则。这些规则使AI工具能够更好地理解如何与Bucket和特性标志协同工作以及它们应该如何在你的代码库中被使用。

npx bucket rules [--format cursor|copilot] [--yes]

选项：

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

此命令将向你的项目中添加规则，为AI工具提供关于如何设置和使用Bucket特性标志的上下文。对于copilot格式，规则将被添加到文件中的专用部分，允许你在Bucket的规则旁边维护其他copilot指令。

模型上下文协议

模型上下文协议（MCP）是一种开放协议，它提供了一种标准化的方式来连接AI模型到不同的数据源和工具。在Bucket的背景下，MCP使你的开发环境能够理解你的特性标志、它们的状态以及它们在代码库中的关系。这在你的特性管理流程和AI驱动的开发工具之间创建了一个无缝的桥梁。MCP正处于非常早期的开发阶段，变化频繁，如果遇到问题，请访问模型上下文协议网站 并在此处提交问题单。

设置MCP

目前MCP服务器在你的机器上本地运行。要启动MCP服务器，请从你的Bucket初始化项目目录中运行CLI命令：

npx bucket mcp [--port <number|"auto">] [--app-id ap123456789]

选项：

• --port: 运行SSE服务器的端口（默认为8050，“auto”表示随机端口）。
• --app-id: 要使用的应用ID。

这将在默认情况下在 http://localhost:8050/sse 启动一个 SSE 服务器，您可以使用您选择的客户端连接到该服务器。下面的例子适用于 Cursor IDE 和 Claude Desktop。

服务器发送事件 (SSE)

{
  "mcpServers": {
    "Bucket": {
      "url": "http://localhost:8050/sse"
    }
  }
}

STDIO 代理

一些客户端不支持 SSE，而是可以通过 STDIO 代理与 MCP 服务器交互。

{
  "mcpServers": {
    "Bucket": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse", "http://localhost:8050/sse"]
    }
  }
}

Cursor IDE

要在 Cursor IDE 中启用 MCP 功能：

1. 打开 Cursor IDE。
2. 转到 设置 > MCP。
3. 点击 添加新的全局 MCP 服务器 并粘贴 SSE 配置。
4. 保存并返回到 Cursor。

Claude Desktop

要在 Claude Desktop 中启用 MCP 功能：

1. 打开 Claude Desktop。
2. 转到 设置 > 开发者。
3. 点击 编辑配置 并粘贴 STDIO 配置。
4. 保存并重启 Claude Desktop。

开发

# Build the CLI
yarn build

# Run the CLI locally
yarn bucket [command]

# Lint and format code
yarn lint
yarn format

依赖

• Node.js >=18.0.0

许可证

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