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+):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: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 withgrowthbook --help and drill down:
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):
Scripting and automation
The CLI is built to compose with shell pipelines:--output-format json|yaml|toon|prettycontrols the output shape (-o jsonfor pipelines).--jq '<expression>'filters output with built-in jq — no separate install needed.--allauto-paginates list commands, streaming NDJSON in JSON mode.--dry-runprints the HTTP request that would be sent without executing it.- Exit codes are meaningful:
0on success, non-zero on any failure, with structured error output.
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
GenerateAppFeatures and AppAttributes type definitions from your feature flags and targeting attributes for strictly-typed SDK usage:
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+.
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:
--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.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 defaultGITHUB_TOKEN, so without this your type-check would never run on them.
.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 rungrowthbook --help — every command’s full usage, flags, and examples are built in.
