GrowthBook Command Line Interface (CLI) - GrowthBook Documentation

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.

​Installation

​Authentication

​Self-hosted instances

​Multiple organizations or servers

​Everyday usage

​Scripting and automation

​AI coding agents

​Generating TypeScript types

​API versioning and server compatibility

​Detailed command reference

Installation

Authentication

Self-hosted instances

Multiple organizations or servers

Everyday usage

Scripting and automation

AI coding agents

Generating TypeScript types

API versioning and server compatibility

Detailed command reference