Skip to main content

GrowthBook Command Line Interface (CLI)

The GrowthBook CLI lets you manage feature flags, experiments, metrics, and everything else in the GrowthBook REST API from your terminal. Every API resource has a command group, so anything you can do via the API you can do from a shell — interactively, in scripts, or in CI.

The CLI is generated from the GrowthBook OpenAPI spec, so it tracks the API closely and updates shortly after new endpoints ship.

Upgrading from the legacy CLI?

Version 1.0 is a ground-up rewrite of the previous growthbook npm package. Your existing ~/.growthbook/config.toml profiles are imported automatically on first run. Most commands are unchanged — see the migration guide for what moved.

Installation​

Install via npm (a small launcher that downloads the prebuilt binary for your platform; requires Node.js 16+):

npm install -g growthbook

Or with Homebrew:

brew install growthbook/tap/growthbook

Prefer a standalone binary with no Node.js dependency? An install script, go install, and prebuilt downloads are covered in the repository README .

Verify the install:

growthbook --version

Authentication​

The CLI authenticates with a Secret Key or Personal Access Token, which you can create under Settings → API Keys .

For interactive setup, run:

growthbook auth login

This stores your credentials in the OS keychain when available (with a config-file fallback). Check what's active at any time with:

growthbook whoami

You can also pass credentials explicitly — useful for one-off commands or scripts:

growthbook features list --bearer-auth secret_abc123
# or
GBCLI_BEARER_AUTH=secret_abc123 growthbook features list

Self-hosted instances​

Point the CLI at your API host with --server-url (note the /api suffix), or store it once via growthbook configure:

growthbook features list --server-url https://gb-api.example.com/api

Multiple organizations or servers​

Named profiles bundle a server URL and credential together:

growthbook profiles set staging --server-url https://gb.staging.example.com/api --bearer-auth secret_xxx
growthbook profiles use staging          # set the default
growthbook features list --profile prod  # or per-command

Everyday usage​

Every command and group documents itself — start with growthbook --help and drill down:

growthbook features list                      # list feature flags
growthbook features get --id my-flag          # inspect one
growthbook features toggle --id my-flag --environments '{"production": false}'
growthbook experiments list

For guided exploration, growthbook explore opens an interactive browser of the full command tree.

Write operations accept individual flags or a raw JSON body (via --body, or piped through stdin):

echo '{"id": "my-flag", "valueType": "boolean", "defaultValue": "true"}' | growthbook features create --body -

Feature changes that need review can go through the full draft workflow — create a revision, edit it, and publish (or request review):

growthbook feature-revisions create --id my-flag --title "Enable for beta users"
growthbook feature-revisions add-rule --id my-flag --version-param 2 --rule '{"type": "force", "value": "true", "condition": "{\"beta\": true}", "environments": ["production"]}'
growthbook feature-revisions publish --id my-flag --version-param 2

Scripting and automation​

The CLI is built to compose with shell pipelines:

  • --output-format json|yaml|toon|pretty controls the output shape (-o json for pipelines).
  • --jq '<expression>' filters output with built-in jq — no separate install needed.
  • --all auto-paginates list commands, streaming NDJSON in JSON mode.
  • --dry-run prints the HTTP request that would be sent without executing it.
  • Exit codes are meaningful: 0 on success, non-zero on any failure, with structured error output.
growthbook features list --all -o json --jq '.id' | sort

In CI, authenticate with the GBCLI_BEARER_AUTH environment variable (the keychain isn't available in headless environments) and pass --no-interactive to disable all prompts.

AI coding agents​

When the CLI detects it's running under an AI coding agent (Claude Code, Cursor, and others), it automatically enables --agent-mode: structured, machine-readable errors with remediation hints and token-efficient TOON output. The CLI is self-documenting enough that agents can discover and use the full API surface from --help alone. Use --agent-mode=false to opt out.

Generating TypeScript types​

Generate an AppFeatures type definition from your feature flags for strictly-typed SDK usage:

growthbook generate-types --output ./types

Add it to your package.json scripts to keep types in sync:

{
  "scripts": {
    "type-gen": "growthbook generate-types --output ./types"
  }
}

API versioning and server compatibility​

REST endpoints are versioned by path prefix (/v1, /v2). Each command group targets the newest version of its endpoint; superseded versions remain available under a -vN suffix (e.g. features-v1, deprecated). When a command group advances to a newer API version, it ships as a major CLI release with a changelog callout so you can pin the prior major or switch to the explicit -vN command on your own schedule.

Self-hosted: the full command surface requires GrowthBook 4.4.0 or newer (when the v2 API shipped). On older servers, v2-backed commands return 404 — use the -v1 command variants or upgrade. GrowthBook Cloud is always current.

The CLI checks once a day for a newer version and prints a notice to stderr when an upgrade is available and compatible with the server you're connected to. Disable with --no-update-check or GBCLI_NO_UPDATE_CHECK=1.

Detailed command reference​

See the generated command documentation on GitHub , or run growthbook --help — every command's full usage, flags, and examples are built in.