Skip to main content
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+):
Or with Homebrew:
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:

Authentication

The CLI authenticates with a Secret Key or Personal Access Token, which you can create under Settings → API Keys . For interactive setup, run:
This stores your credentials in the OS keychain when available (with a config-file fallback). Check what’s active at any time with:
You can also pass credentials explicitly — useful for one-off commands or scripts:

Self-hosted instances

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

Multiple organizations or servers

Named profiles bundle a server URL and credential together:

Everyday usage

Every command and group documents itself — start with growthbook --help and drill down:
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):
Feature changes that need review can go through the full draft workflow — create a revision, edit it, and publish (or request review):

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.
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 AppFeatures and AppAttributes type definitions from your feature flags and targeting attributes for strictly-typed SDK usage:
The generated file also registers both types with the SDK, so every GrowthBook instance and React hook is strictly typed with no generics or imports. It only needs to be somewhere your tsconfig.json includes. If it lives outside that, for example in another package of a monorepo, import it once from the app (import type {} from "shared/generated/app-features"), otherwise the types silently don’t apply. This requires CLI version 4.0.0+ and JS or React SDK version 2.1.0+.
The types are registered with both SDK packages, so the same file works whichever one your project uses. Attributes are optional, so you can set them in stages, for example some in the constructor and the rest from middleware, a useEffect hook, or a plugin. Attributes that aren’t defined in GrowthBook and values of the wrong type are compile-time errors. TypeScript only flags unknown attributes on an object written inline in the call. If you build the attributes in a variable first, add satisfies AppAttributes (or annotate the variable as AppAttributes) so its keys are checked too:
To also catch an attribute that was added in GrowthBook but never passed to the SDK, use --strict-attributes. Every attribute then becomes a required key in setAttributes and the attributes option. Pass null or undefined when your app doesn’t know a value, such as the id of a logged-out user. If your app uses more than one GrowthBook instance with different features, such as one per project, generate a file for each with --no-register and pass the types to each instance yourself:
Upgrading from an earlier CLI version?Earlier versions only wrote AppFeatures, which did nothing until you passed it to the SDK as a generic. Because the file now registers itself, regenerating it can surface new type errors across your app: unknown or dynamic feature keys, mismatched fallback values, and attributes that aren’t defined in GrowthBook. Pass --no-register to keep the previous behavior.

Keeping types up to date

Commit the generated file and let a scheduled workflow open a pull request whenever your features or attributes change. A removed or retyped flag then shows up as a failing type-check on that pull request, not as a broken deploy.
Setup is two repository secrets:
  • GROWTHBOOK_API_KEY: a read-only Secret Key.
  • TYPES_PR_TOKEN: a personal access token or GitHub App token that can push branches and open pull requests. GitHub doesn’t run other workflows on pull requests opened with the default GITHUB_TOKEN, so without this your type-check would never run on them.
The workflow does nothing when the types haven’t changed. If you’d rather not commit generated code, add the output directory to .gitignore and generate on every build instead. This needs GBCLI_BEARER_AUTH wherever you build:

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.