Flaggr CLI

The Flaggr CLI lets you manage feature flags, evaluate flags, and export configurations directly from your terminal.

Installation

The CLI is a single flaggr binary for macOS, Linux and Windows, on amd64 and arm64. It is MIT-licensed, and its source is public at github.com/flaggr-dev/flaggr-cli.

With Go

With Go 1.27 or later (Go 1.26 for v0.5.0 and earlier), go install builds the CLI and puts flaggr in $(go env GOPATH)/bin, which needs to be on your PATH:

go install github.com/flaggr-dev/flaggr-cli/cmd/flaggr@latest

Keep the /cmd/flaggr at the end of the path: the repository root has no Go package, so installing the root path fails. Run flaggr --version to see what you installed.

Prebuilt binaries and the install script

Prebuilt binaries for macOS, Linux and Windows, with checksums, and an install script come with the releases on github.com/flaggr-dev/flaggr-cli from v0.5.0 on. go install works with or without a release.

Each release has an archive per platform, named for its version, OS and architecture, and checksums.txt with the SHA-256 of each:

On macOS and Linux, the install script downloads the latest release for your OS and architecture, checks it against checksums.txt, and installs flaggr to /usr/local/bin (with sudo when that directory isn't writable):

curl -fsSL https://raw.githubusercontent.com/flaggr-dev/flaggr-cli/main/install.sh | sh

Set FLAGGR_INSTALL_DIR to install elsewhere, or FLAGGR_VERSION (for example 0.5.0) to install a given release. To install by hand, check the archive against checksums.txt, extract it and put flaggr (flaggr.exe on Windows) in a directory on your PATH:

tar -xzf flaggr_0.5.0_darwin_arm64.tar.gz flaggr
sudo install -m 0755 flaggr /usr/local/bin/flaggr

Authentication

The CLI uses a browser-based auth flow (similar to gcloud auth login):

flaggr login

This will:

1. Open your browser to the Flaggr login page
2. After signing in, choose One project (a project API token, read & write, for the project you pick — the default) or All my projects (a personal access token that acts as you in every project you can access; write tier, expires in 90 days)
3. The sign-in page POSTs the credentials to the CLI's localhost callback — never in a URL, so they stay out of your browser history — and the CLI saves them to ~/.flaggr/config.json

The CLI sends a one-time state with the sign-in page and accepts only the callback that returns it, so another web page can't log your CLI into a different account by calling its localhost port. It takes the token only from the form the page POSTs and refuses one in the callback URL. Browser login needs a Flaggr server from this release or later; against an older self-hosted server, use flaggr login --token. Older CLI versions can't use browser login against this release's server — the sign-in page tells you to update.

Approving flaggr login in the browser needs your signed-in dashboard session and a verified email address (403 "Verify your email address first" otherwise). The page then offers Send verification email; open the link, then choose I've verified — retry and the CLI login completes. GitHub sign-ins need this once. The One project token is read & write in that project only: flaggr flags delete and other deletes return 403 "API token lacks the delete permission" with it. For deletes, log in with All my projects, or pass a personal access token or a project API token that has the Delete permission to flaggr login --token.

For non-interactive environments (CI/CD), pass a token directly:

flaggr login --token fgp_your_personal_access_token   # or a project API token (fgr_…)

To log out and remove saved credentials:

flaggr logout

flaggr logout only deletes ~/.flaggr/config.json; it doesn't revoke the token. A personal access token keeps working until it expires or you revoke it under Profile → Personal access tokens (https://flaggr.dev/console/profile#personal-access-tokens), and a project API token until you revoke it in the project's Settings → API tokens. The CLI prints this when you log out. If FLAGGR_API_TOKEN is set, commands keep using that token — unset it too.

Commands

flaggr status

Show CLI and server versions, check API health.

$ flaggr status
CLI version:    0.5.0 (abc1234)
Server version: 0.5.0 (d1939eb)
Environment:    production
 
✓ Flaggr is healthy

flaggr projects

List the projects you have access to.

flaggr projects
flaggr projects --json  # JSON output

flaggr services

List a project's services.

flaggr services --project <project-id>

flaggr flags list

List a project's feature flags, or only one service's.

flaggr flags list --project <project-id>
flaggr flags list --project <project-id> --service <service-id>

flaggr flags toggle

Toggle a flag on or off.

flaggr flags toggle --key my-flag --service <service-id>

flaggr eval

Evaluate a flag with targeting context via Connect-RPC.

flaggr eval bool -k my-flag -s <service-id>
flaggr eval string -k my-flag -s <service-id> -c '{"targetingKey":"user-123"}'
flaggr eval number -k my-flag -s <service-id> -e staging

flaggr eval uses the SDK evaluation endpoints, which accept project API tokens only. With a personal access token saved, pass a project token for the call: FLAGGR_API_TOKEN=fgr_your_project_token flaggr eval bool -k my-flag -s <service-id>.

flaggr export

Export a project's configuration as JSON, to a file with --output or to stdout without it.

flaggr export --project <project-id> --output flaggr-backup.json

flaggr sourcemaps

From v0.6.0. Upload a release's source maps, so the Issues page shows minified stack frames as your original files, lines and functions:

# Next.js: the maps of .next/static, served under /_next/static
flaggr sourcemaps upload .next/static --url-prefix /_next/static --release "$GIT_SHA" --project <project-id>
 
# One file: filed as /server.js, which matches any frame path ending in /server.js
flaggr sourcemaps upload dist/server.js.map --release "api@2.8.1"
 
flaggr sourcemaps list --project <project-id>                     # the releases with maps
flaggr sourcemaps list --release "$GIT_SHA"                       # one release's files
flaggr sourcemaps delete --release "$GIT_SHA"                     # a release's maps (--file for one)

upload takes directories and .map files. Each map is filed under the path its minified file has in stack traces: --url-prefix plus the map's path in the directory, without .map. --dry-run lists those paths without uploading. Without --project, each command uses the default project flaggr login saved. --release must be the release your app reports (the release option of flaggrErrors(), errorreport or @flaggr/react-native). Maps are gzipped before they're sent and must be under 64 MiB each. Your build must emit them (for Next.js, productionBrowserSourceMaps: true), but you don't have to serve them. Uploading needs write access to the project.

flaggr crash-reports

From v0.6.0. Turn the CLI's own crash reports on or off, or see whether they're on:

flaggr crash-reports status
flaggr crash-reports on
flaggr crash-reports off

Crash reports are off unless you turn them on, with this command or FLAGGR_CRASH_REPORTS=1. DO_NOT_TRACK=1 and CI environments (CI set) always keep them off.

When they're on and the CLI crashes (a Go panic), it sends a report to the Flaggr team, at https://flaggr.dev/api/ingest/cli-crashes, then fails as it would have. A report contains the panic's message and stack, the CLI's version, the subcommand that ran (such as flags list, never its arguments or flags), and your OS, architecture and Go version. It never contains your token, URLs, flag keys or command output, and Flaggr removes tokens and email addresses from the message and stack too. Reports are stored only in Flaggr's own project, never in yours.

Errors a command returns, such as a rejected token or a network failure, aren't crashes and are never reported. With reports off, a crash prints how to report it by hand instead.

More commands

Each of these takes the flags shown, and flaggr <command> --help lists the rest:

Configuration

The CLI stores configuration at ~/.flaggr/config.json:

{
  "api_url": "https://flaggr.dev",
  "api_token": "fgp_...",
  "default_project_id": "proj_abc123"
}
 

Override the API URL for self-hosted instances:

flaggr login --url https://flaggr.internal.company.com

Global Flags