Flagbearer CLI

Create feature flags and roll them out from a terminal or a CI job. Requires Node.js 22 or later.

npx @flagbearer/cli login
npx @flagbearer/cli flags set new-checkout --env development --rollout 100

To skip the npx prefix, install it globally with npm install --global @flagbearer/cli, then run flagbearer.

Sign in

On your own machine, sign in through the browser:

flagbearer login

Flagbearer opens in your browser. Pick the organization the CLI can use and its access, Editor or Viewer, and approve it. The sign-in is saved in ~/.config/flagbearer/credentials.json, readable only by you, and refreshes on its own. flagbearer logout removes it from the machine. To end it everywhere, disconnect the Flagbearer CLI on the organization's API tokens tab.

In CI, use a personal API token instead:

1. Open your organization's API tokens tab and create a token. Pick Editor so it can create and change flags. Give it a name like "GitHub Actions": flag history shows its changes under that name.
2. Store the secret in your CI's secrets and pass it as FLAGBEARER_TOKEN.

When FLAGBEARER_TOKEN is set, the CLI uses it instead of a saved sign-in, so a CI job never acts as whoever last signed in on the machine.

Pick an application

Flag commands work on one application. Pass its ID, slug or name as --app, or set FLAGBEARER_APP. To see them:

flagbearer apps list

ID  SLUG        NAME        ORG
12  storefront  Storefront  3

A name can match apps in two organizations. Then the command lists them and asks for the ID. In CI, prefer the ID: it doesn't change when the app is renamed.

Commands

flags create takes --name and --description. The name defaults to the key. Quote values with spaces, like --name "New checkout".

Change a flag

flags set changes one environment, chosen with --env and its key, like development or production:

flagbearer flags set new-checkout --env staging --rollout 25

• --rollout <percent> turns the flag on for that percentage of users, from 0 to 100. At 0, only the environment's testers get it.
• --on turns the flag on and keeps the rollout it had.
• --off turns it off.

Changing production asks you to confirm. Where nobody is at the terminal, as in CI, pass --yes instead, or the command refuses.

Typed flag keys

generate types writes a file listing the application's flags, so TypeScript checks flag keys and editors autocomplete them:

flagbearer generate types --app storefront --out src/flagbearer.d.ts

// src/flagbearer.d.ts
// Generated by `flagbearer generate types --app storefront --out src/flagbearer.d.ts`.
// Don't edit it. Run that command again after adding or removing flags.
import "@flagbearer/web";

declare module "@flagbearer/web" {
  interface Flags {
    "dark-mode": true;
    "new-checkout": true;
  }
}

flags.isEnabled("new-checkout", false); // ok
flags.isEnabled("new-chekout", false); // type error: not a flag in this app

Commit the file. Without it, any string is a flag key.

• The file covers each Flagbearer SDK in the nearest package.json. To choose, pass --sdk web, --sdk node or --sdk react-native, more than once for several.
• --check writes nothing and exits 1 when the file is out of date, so CI catches a deleted flag that code still uses.
• --format json writes the sorted keys as a JSON array, for other languages and tools.

In CI

A GitHub Actions step that rolls a flag out to a quarter of production users after a deploy:

- run: npx @flagbearer/cli flags set new-checkout --env production --rollout 25 --yes
  env:
    FLAGBEARER_TOKEN: ${{ secrets.FLAGBEARER_TOKEN }}
    FLAGBEARER_APP: "12"

Other CI systems work the same way: set the two variables and run the command.

To fail a build when the typed flag keys are out of date:

- run: npx @flagbearer/cli generate types --app storefront --out src/flagbearer.d.ts --check
  env:
    FLAGBEARER_TOKEN: ${{ secrets.FLAGBEARER_TOKEN }}

Options and output

Every command takes:

• --app <app>: the application's ID, slug or name, instead of FLAGBEARER_APP.
• --json: prints JSON instead of text, for scripts.
• --url <url>: a Flagbearer server other than https://flagbearer.dev, instead of FLAGBEARER_URL.

The exit code says how it went:

• 0: done.
• 1: Flagbearer refused the change or couldn't be reached. The message says why.
• 2: the command was wrong, or you're not signed in.

An API token can make 60 changes a minute. Past that, commands exit 1 and say to wait.