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.
Install
Section titled “Install”Homebrew (macOS and Linux):
brew install canopy-labs/tap/featureflipBinary. 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):
go install github.com/canopy-labs/featureflip-cli/cmd/featureflip@latestCheck it with featureflip version.
Sign in
Section titled “Sign in”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:
featureflip loginIt 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.
Organization and project
Section titled “Organization and project”Every command works on one organization and one project. The CLI picks each from the first of these that’s set:
--organd--projectFEATUREFLIP_ORGandFEATUREFLIP_PROJECT- a default saved with
featureflip login --org <slug> --project <key> - 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.
Turn a flag on or off
Section titled “Turn a flag on or off”featureflip flags on new-checkout --env productionnew-checkout: off → on in productionon 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 productionCheck a flag in every environment with flags status:
featureflip flags status new-checkoutENVIRONMENT STATEdevelopment onstaging onproduction offProtected environments
Section titled “Protected environments”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--yesa script’s flip is refused with exit code 6.
featureflip flags on new-checkout --env production --reason "Launch day" --yesCommands
Section titled “Commands”| Command | What 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 list | The 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 list | Projects in the organization |
environments list | Environments in the project, with their change guards |
segments list | Segments in the project |
generate types | TypeScript types for the project’s flags (--out, --check) |
whoami | Who the token acts as |
login / logout | Save or remove a token on this machine |
version | The 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.
Use it in CI
Section titled “Use it in CI”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 }}" --yesPass --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.
Scripts and AI agents
Section titled “Scripts and AI agents”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:
| Code | Meaning |
|---|---|
| 0 | Success, including a flip that changed nothing |
| 1 | Unexpected error, such as a network failure or a server error that outlasted the retries |
| 2 | Usage: bad arguments, a missing --reason, or an ambiguous organization or project |
| 3 | Authentication: no token, or the token was refused |
| 4 | Not found |
| 5 | The API rejected the change, for example a plan limit or a validation error |
| 6 | Confirmation was declined, or was required and --yes wasn’t given |
| 7 | generate 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.
Generate TypeScript types
Section titled “Generate TypeScript types”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:
featureflip generate types --out src/flags.ts --checkConfiguration reference
Section titled “Configuration reference”| Variable | Purpose |
|---|---|
FEATUREFLIP_TOKEN | API token. Takes precedence over a saved one |
FEATUREFLIP_ORG | Organization slug |
FEATUREFLIP_PROJECT | Project key |
FEATUREFLIP_API_URL | API base URL (default https://api.featureflip.io) |
NO_COLOR | Turn off colored output |