FlagShark CLI

flagshark is the open-source CLI that powers FlagShark. Drop it into any repo, run one command, and get a report of stale feature flags — no account, no configuration required to get started, no telemetry. It uses the same detection engine (@flagshark/core) as the FlagShark dashboard and GitHub Action, so results are consistent across all three.

Install

The fastest path is npx — no install needed:

npx flagshark scan

Or install globally if you run it often:

npm install -g flagshark
flagshark scan

The package is published as flagshark on npm. Source at FlagShark/flagshark on GitHub. MIT licensed.

Quickstart

Run from the root of any repo:

$ npx flagshark scan

🦈 FlagShark

Scanned 156 files across 4 languages
Detected providers: LaunchDarkly (JS SDK), Unleash (Go SDK)
Found 23 feature flags, 7 stale

Stale flags:
┌──────────────────┬────────────────────────┬───────────────┬────────────────────────┐
│ Flag             │ File                   │ Last Modified │ Signal                 │
├──────────────────┼────────────────────────┼───────────────┼────────────────────────┤
│ CHECKOUT_V2      │ src/checkout.ts:47     │ 14 months ago │ age                    │
│ NEW_NAV          │ src/layout.tsx:12      │ 8 months ago  │ age, low-usage         │
│ BETA_SEARCH      │ src/search.ts:91       │ 11 months ago │ age, low-usage         │
└──────────────────┴────────────────────────┴───────────────┴────────────────────────┘

Flag Health Score: 70/100 (7/23 flags are stale)

The CLI exits with code 0 if no stale flags are found, 1 if stale flags are detected, and 2 if something went wrong. That makes it directly usable in CI without extra glue.

CLI options

The CLI has a single subcommand, scan. Running flagshark with no arguments behaves the same as flagshark scan.

Both --flag value and --flag=value forms are accepted for all options.

--show-excluded lists the actual file paths that were excluded, while --verbose prints the effective exclude rules that caused them to be skipped.

Output formats

The --format flag controls how results are rendered:

• text (default) — human-readable table with color, printed to stdout.
• json — structured JSON object; safe to pipe to jq or another tool.
• markdown — GitHub-flavored Markdown table; useful for posting to issues or Slack.
• csv — comma-separated values; import directly into a spreadsheet.
• sarif — SARIF 2.1 format for IDE and security tool integrations.

Use --output <path> (or -o) to write the report to a file instead of stdout:

flagshark scan --format sarif --output flagshark.sarif
flagshark scan --format csv -o stale-flags.csv

Exit codes

This is the standard CI shape — drop the command into any script and let the exit code drive the rest.

Staleness signals

A flag reference is only evaluated if the file imports a known flag SDK. A function literally named isEnabled() in a file with no flag SDK import is ignored, which keeps false positives down.

The CLI fires two staleness signals:

• age — git blame on the flag reference line shows it was last modified more than --threshold days ago (default: 30 days).
• low-usage — the flag name appears in only one file across the entire repo. That usually means a rollout is finished and the losing branch was cleaned up, leaving a lone reference behind.

Two additional signals require a connected FlagShark platform integration and are reported as errors or warnings:

• missing-in-platform — the flag is referenced in code but does not exist in the flag platform. This is an error-severity signal that triggers exit code 1 when --fail-on-error is on (the default).
• archived-in-platform — the flag has been archived in the platform (warning severity).

See LaunchDarkly integration for setup details.

Common usage

Scan only what changed in this PR

Useful in CI when you don't want to penalize a PR for stale flags it didn't introduce:

flagshark scan --diff origin/main

Pipe JSON output into another tool

flagshark scan --format json | jq '.staleFlags[] | {name, file: .filePath, age}'

Tune the staleness threshold

Tighter threshold for aggressive cleanup teams:

flagshark scan --threshold 7

Looser threshold for kill-switch-heavy or long-lived codebases:

flagshark scan --threshold 90

Use it in any CI (not just GitHub Actions)

# Example: generic CI step
- run: npx flagshark scan --diff $BASE_REF

Add a pre-push git hook

# .git/hooks/pre-push
npx flagshark scan --threshold 14 || {
  echo "Stale flags detected. Run 'npx flagshark scan' for details."
  exit 1
}

CLI vs the dashboard

The CLI is a snapshot tool. Each run scans your current checkout and reports what it sees. It has no memory of prior runs.

The FlagShark dashboard tracks the lifecycle of each flag: when it was added, who added it, when it crossed thresholds, and (with auto-cleanup enabled) opens cleanup PRs when a flag is safe to remove.

You can use both. Many teams adopt the CLI first — zero setup, single npm command — then connect the GitHub App for tracking and automation.

Related Documentation

• GitHub Action — Same scanner, runs in GitHub Actions, posts PR comments
• Supported Languages — the full language + SDK matrix
• Configuration — .flagshark.yml for custom provider patterns and exclude rules
• @flagshark/core library — Use the detection engine directly in your own scripts