Skip to content

Featureflip CLI

The featureflip command manages your flags from a terminal or a CI job. The everyday use is flipping one flag in one environment: featureflip flags on new-checkout --env production. It also shows where a flag is on, lists and creates flags, archives and restores them, and generates TypeScript types for your flag keys.

It’s a single static binary for Linux, macOS and Windows, with no runtime to install. It talks to the public Management API, so it works on every plan, Free included, and follows the same rules as the dashboard. The source is at canopy-labs/featureflip-cli.

Homebrew (macOS and Linux):

Terminal window
brew install canopy-labs/tap/featureflip

Binary. Download the archive for your platform from the latest release, unpack it and put featureflip on your PATH. There are builds for Linux, macOS and Windows on amd64 and arm64, and checksums.txt lists each archive’s SHA-256.

Go (1.26 or later):

Terminal window
go install github.com/canopy-labs/featureflip-cli/cmd/featureflip@latest

Check it with featureflip version.

The CLI needs an API token, which you create in the dashboard:

  • Personal access token (ffp_…). Settings → API Tokens. It acts as you, across your organizations. Good for your own machine.
  • Service token (ffs_…). Organization Settings → Service Tokens. Scoped to one organization with a role and an optional project allowlist. Use one for CI, with the Member role or higher if the job changes flags.

On your own machine, save the token once:

Terminal window
featureflip login

It asks for the token without echoing it, checks it against the API, and saves it to a config file only your user can read (~/.config/featureflip/config.json on Linux, the platform’s user config directory elsewhere). featureflip logout removes it, and featureflip whoami shows who the token acts as.

In CI, set FEATUREFLIP_TOKEN instead. It takes precedence over a saved token. The CLI has no --token flag on purpose, so a token never ends up in your shell history or a process list.

Every command works on one organization and one project. The CLI picks each from the first of these that’s set:

  1. --org and --project
  2. FEATUREFLIP_ORG and FEATUREFLIP_PROJECT
  3. a default saved with featureflip login --org <slug> --project <key>
  4. the only one the token can see

When there’s more than one and you named none, the command lists them and exits with code 2.

Terminal window
featureflip flags on new-checkout --env production
new-checkout: off → on in production

on and off set the state. If the flag is already where you asked, the CLI sends nothing and still exits 0, which makes a retried CI step safe:

new-checkout is already on in production

Check a flag in every environment with flags status:

Terminal window
featureflip flags status new-checkout
ENVIRONMENT STATE
development on
staging on
production off

An environment marked as critical can require a change reason, a typed confirmation, or both. The CLI applies the same rules as the dashboard, and featureflip environments list shows which environment has which.

  • Change reason. Pass --reason "why". Without it the command stops before it changes anything, and the reason goes into the audit log.
  • Confirmation. At a terminal, the CLI asks you to type the environment’s key. In a script there’s nobody to type it, so pass --yes. Without --yes a script’s flip is refused with exit code 6.
Terminal window
featureflip flags on new-checkout --env production --reason "Launch day" --yes
CommandWhat it does
flags on <flag> --env <env>Turn a flag on in one environment (--reason, --yes)
flags off <flag> --env <env>Turn a flag off in one environment (--reason, --yes)
flags status <flag>On or off in each environment
flags listThe project’s flags. --env adds the on/off state in one environment, and --search, --tag and --archived filter
flags get <flag>Details, variations and per-environment state
flags create <flag>Create a flag. Boolean by default, or --type string|number|json with two or more --variation key=value. Also takes --name, --description, --tag and --client-side. A new flag starts off everywhere
flags archive <flag>Archive a flag (--reason, and --force if live traffic still evaluates it)
flags restore <flag>Restore an archived flag (--reason)
projects listProjects in the organization
environments listEnvironments in the project, with their change guards
segments listSegments in the project
generate typesTypeScript types for the project’s flags (--out, --check)
whoamiWho the token acts as
login / logoutSave or remove a token on this machine
versionThe CLI’s version

Every command also takes --json, --org, --project and --no-color. Run featureflip <command> --help for the details, and featureflip completion <shell> to set up completion for bash, zsh, fish or PowerShell.

A deploy job can turn a flag on once the release is out. In GitHub Actions, store a service token as a repository secret and download a pinned release:

- name: Install the Featureflip CLI
run: |
curl -sSL https://github.com/canopy-labs/featureflip-cli/releases/download/v0.1.0/featureflip_0.1.0_linux_amd64.tar.gz \
| tar -xz featureflip
sudo mv featureflip /usr/local/bin/
- name: Turn on new-checkout
env:
FEATUREFLIP_TOKEN: ${{ secrets.FEATUREFLIP_TOKEN }}
FEATUREFLIP_ORG: acme-corp
FEATUREFLIP_PROJECT: web
run: featureflip flags on new-checkout --env production --reason "Deployed ${{ github.sha }}" --yes

Pass --reason and --yes in CI even when the environment doesn’t ask for them today. If someone later marks production as critical, the job keeps working instead of failing on a missing reason.

With --json, stdout carries exactly one JSON document, whether the command succeeds or fails. A flip reports what it did:

{
"changed": true,
"current": true,
"environment": "development",
"flag": "new-checkout",
"previous": false
}

A failure passes the API’s error fields through, including suggestions for a mistyped key:

{
"did_you_mean": ["new-checkout"],
"docs_url": "https://featureflip.io/docs/management-api/errors/not_found",
"error": "not_found",
"message": "Flag not found",
"status": 404
}

Exit codes:

CodeMeaning
0Success, including a flip that changed nothing
1Unexpected error, such as a network failure or a server error that outlasted the retries
2Usage: bad arguments, a missing --reason, or an ambiguous organization or project
3Authentication: no token, or the token was refused
4Not found
5The API rejected the change, for example a plan limit or a validation error
6Confirmation was declined, or was required and --yes wasn’t given
7generate types --check found the file out of date

Requests that are safe to repeat are retried on transient gateway errors. A create carries an idempotency key, so a retry can’t make two flags.

A coding agent with a shell can drive the CLI directly. If your agent speaks the Model Context Protocol, the MCP server gives it the same API as tools, with the same FEATUREFLIP_TOKEN.

Terminal window
featureflip generate types --out src/flags.ts
// Generated by `featureflip generate types` for project web. Do not edit.
export const flagKeys = [
'new-checkout',
'theme',
] as const;
export type FlagKey = (typeof flagKeys)[number];
export interface FlagValues {
'new-checkout': boolean;
'theme': 'dark' | 'light';
}

Boolean and number flags become boolean and number. A string flag becomes the union of its variation values, and a JSON flag becomes unknown. The file is sorted and carries no timestamp, so it only changes when your flags do. Without --out the types go to stdout.

To fail a CI build when someone changes flags without regenerating, add --check. It writes nothing and exits 7 if the file is out of date:

Terminal window
featureflip generate types --out src/flags.ts --check
VariablePurpose
FEATUREFLIP_TOKENAPI token. Takes precedence over a saved one
FEATUREFLIP_ORGOrganization slug
FEATUREFLIP_PROJECTProject key
FEATUREFLIP_API_URLAPI base URL (default https://api.featureflip.io)
NO_COLORTurn off colored output