FlagdeckFlagdeck
Pricing
Docs
Get Started

Documentation

CLI

The @flagdeck/cli scans your codebase for feature-flag references and reports them to Flagdeck, so a flag with no references and no traffic can be retired with confidence. Only metadata (file path, line, commit) is sent; your source never leaves the machine.

Install

There is nothing to install. Run it with npx:

bash

export FLAGDECK_API_KEY=your_sdk_key
npx flagdeck scan --dry-run   # print matches, send nothing
npx flagdeck scan             # report references for this repo

FLAGDECK_API_KEY is a project SDK key. It resolves the project the references belong to. See Code references for how references turn into a "safe to remove" verdict.

Usage

bash

flagdeck scan [options]

Options

FlagDescription
--dry-runPrint the references instead of sending them.
--alias "<template>"Match wrapped keys. {key} is replaced by each flag key. Repeatable, for example --alias "FLAGS.{key}".
--repo owner/nameRepository identifier. Defaults to the git origin remote.
--default-branch <name>The branch the "safe to remove" verdict is judged against. Defaults to the scanned branch.
--lookback <n>Commits of history to scan for keys removed from code (extinct flags). Default 50.
--api-url <url>Override the API base URL (self-hosted Flagdeck).

Environment variables

Each variable mirrors a flag, so you can configure the scan without editing the command.

VariableDescription
FLAGDECK_API_KEYRequired. Your project SDK key.
FLAGDECK_API_URLOverride the API base URL.
FLAGDECK_REPORepository identifier, same as --repo.
FLAGDECK_DEFAULT_BRANCHDefault branch, same as --default-branch.
FLAGDECK_LOOKBACKExtinct-flag lookback, same as --lookback.

Only files tracked by git are scanned, so your .gitignore is respected. Keys are matched on word boundaries to avoid substring false positives.

Continuous scanning with GitHub Actions

"No references" is only trustworthy if it is recent, so scan on every push to your default branch. Add your SDK key as a repository secret named FLAGDECK_API_KEY (Settings, then Secrets and variables, then Actions), then add .github/workflows/flagdeck-scan.yml:

yaml

name: Flagdeck code references

on:
  push:
    branches: [main]

concurrency:
  group: flagdeck-scan
  cancel-in-progress: true

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.ref_name }}
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx -y @flagdeck/cli scan
        env:
          FLAGDECK_API_KEY: ${{ secrets.FLAGDECK_API_KEY }}
          FLAGDECK_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}

Checking out the branch, rather than a detached HEAD, means the scan reports the branch as main. FLAGDECK_DEFAULT_BRANCH tells Flagdeck which branch the "safe to remove" verdict should be judged against, because git cannot detect origin/HEAD after a CI checkout. For self-hosted Flagdeck, set FLAGDECK_API_URL in the env: block. For wrapped keys, add --alias patterns to the run: line.