@basestack/flags-cli

CLI tool for Basestack Feature Flags. Scan your codebase for feature flag usage and send references to the Basestack API so your team can see where flags are used from the dashboard.

Features

• Code Refs — Scan your codebase for useFlag("slug") hooks and <Feature slug="slug"> components
• Collects file paths, line numbers, and surrounding code context (2 lines before and after) for each flag reference
• Filters out references with empty or invalid flag slugs
• Groups references by flag slug
• Detects git branch and project name automatically
• Submits references to the Basestack API

Installation

As a dev dependency (recommended)

bun add -d @basestack/flags-cli

Global install

bun add -g @basestack/flags-cli

Note: Requires Bun runtime.

Configuration

The CLI reads configuration from three sources (in order of priority):

1. CLI flags (highest priority)

flags-cli code-refs --project-id=proj_xxx --environment-key=env_xxx --api-key=sk_xxx

2. Config file

Create a .flagsrc file in your project root. JSON is supported:

{
  "projectKey": "proj_xxx",
  "environmentKey": "env_xxx",
  "apiKey": "sk_xxx",
  "apiUrl": "https://flags-api.basestack.co/v1"
}

You can also use env-style entries in .flagsrc:

projectKey=proj_xxx
environmentKey=env_xxx
apiKey=sk_xxx
apiUrl=https://flags-api.basestack.co/v1

3. Environment variables

export BASESTACK_FLAGS_PROJECT_KEY=proj_xxx
export BASESTACK_FLAGS_ENVIRONMENT_KEY=env_xxx
export BASESTACK_FLAGS_API_KEY=sk_xxx
export BASESTACK_FLAGS_API_URL=https://flags-api.basestack.co/v1 # optional

Important: Add .flagsrc to your .gitignore to avoid committing secrets.

Usage

Code Refs

Scan your codebase for feature flag references and submit them to the Basestack API:

flags-cli code-refs

With options:

flags-cli code-refs --project-id=proj_xxx --environment-key=env_xxx --api-key=sk_xxx --dir=./src

When run in an interactive terminal, code-refs opens an OpenTUI interface with progress, a scrollable results pane, and keyboard shortcuts. In CI or other non-interactive environments, it automatically falls back to plain text output.

All options

| Option | Description | Default | |---|---|---| | --project-id | Basestack project key (required) | BASESTACK_FLAGS_PROJECT_KEY env var | | --environment-key | Basestack environment key (required) | BASESTACK_FLAGS_ENVIRONMENT_KEY env var | | --api-key | API key for authentication (required) | BASESTACK_FLAGS_API_KEY env var | | --api-url | API base URL | https://flags-api.basestack.co/v1 | | --dir | Directory to scan | Current directory | | -h, --help | Show help | — |

What it scans for

The scanner looks for common flag references in .ts, .tsx, .js, .jsx, .html, and .htm files:

// Hook usage
const isEnabled = useFlag("my-feature");
const flag = useFlag<{ variant?: string }>("my-feature");
const enabled = useBooleanFlagValue("my-feature", false);
const config = useObjectFlagValue("checkout-config", {});

// Component usage
<Feature slug="my-feature">
  <MyComponent />
</Feature>

// SDK usage
const flag = await fetchFlag("my-feature", flagsConfig);
const value = await client.getFlag("my-feature");
client.clearFlagCache("my-feature");
client.getBooleanValue("my-feature", false);
client.getObjectValue("checkout-config", {});
client.getBooleanDetails("my-feature", false);

// Modal usage
const { openFeedbackModal } = useFlag("my-feature");
openFeedbackModal({ featureName: "My Feature" });

const { openFeedbackModal } = useFeatureFlagModals();
openFeedbackModal("my-feature", { featureName: "My Feature" });

// Preload usage
const sdkOptions = {
  preloadFlags: ["header", "footer"],
};

// Web component usage
<feature-flag-feedback-modal flag-key="my-feature" />

For simple dynamic cases, the scanner also resolves identifier arguments when they are backed by a nearby string literal, such as fetchFlag(slug, ...) with slug = "header" or const slug = "header".

It automatically skips node_modules, dist, build, .git, coverage, .next, .turbo, and out directories.

CI/CD Integration

Add to your CI pipeline to keep flag references up-to-date:

# GitHub Actions example
- name: Update flag references
  run: bunx @basestack/flags-cli code-refs
  env:
    BASESTACK_FLAGS_PROJECT_KEY: ${{ secrets.BASESTACK_FLAGS_PROJECT_KEY }}
    BASESTACK_FLAGS_ENVIRONMENT_KEY: ${{ secrets.BASESTACK_FLAGS_ENVIRONMENT_KEY }}
    BASESTACK_FLAGS_API_KEY: ${{ secrets.BASESTACK_FLAGS_API_KEY }}

API Contract

The CLI submits flag references via POST {baseUrl}/flags/code-refs with the following payload:

{
  "branch": "main",
  "projectName": "@my-org/my-app",
  "references": {
    "my-feature": [
      {
        "filePath": "src/App.tsx",
        "lineNumber": 12,
        "lineContent": "function App() {\n  const isEnabled = useFlag(\"my-feature\");\n  const showBanner = useFlag(\"banner\");\n\n  return ("
      }
    ]
  }
}

Note: lineContent includes up to 2 lines before and 2 lines after the matched line for surrounding context.

Headers

| Header | Description | |---|---| | x-api-key | API key (required) | | x-project-key | Project key (required) | | x-environment-key | Environment key (required) |

Response

The API returns a JSON response with status 201:

{
  "success": true
}

Development

# Install dependencies
bun install

# Run in dev mode
bun dev

# Run tests
bun test

# Lint and format
bun run check

# Build for distribution
bun run build

License

MIT