Documentation
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.
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.
bash
flagdeck scan [options]
| Flag | Description |
|---|---|
--dry-run | Print 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/name | Repository 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). |
Each variable mirrors a flag, so you can configure the scan without editing the command.
| Variable | Description |
|---|---|
FLAGDECK_API_KEY | Required. Your project SDK key. |
FLAGDECK_API_URL | Override the API base URL. |
FLAGDECK_REPO | Repository identifier, same as --repo. |
FLAGDECK_DEFAULT_BRANCH | Default branch, same as --default-branch. |
FLAGDECK_LOOKBACK | Extinct-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.
"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.