> ## Documentation Index
> Fetch the complete documentation index at: https://docs.growthbook.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GrowthBook Command Line Interface (CLI)

> The GrowthBook command-line interface (CLI) for managing feature flags, experiments, metrics, and more from your terminal

The GrowthBook CLI lets you manage feature flags, experiments, metrics, and everything else in the [GrowthBook REST API](https://docs.growthbook.io/app/api.md) 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.

> [!NOTE]
>
> **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 ](https://github.com/growthbook/cli/blob/main/MIGRATION.md) for what moved.

## Installation

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

```bash theme={null}
npm install -g growthbook
```

Or with Homebrew:

```bash theme={null}
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 ](https://github.com/growthbook/cli#cli-installation).

Verify the install:

```bash theme={null}
growthbook --version
```

## Authentication

The CLI authenticates with a **Secret Key** or **Personal Access Token**, which you can create under [**Settings → API Keys** ](https://app.growthbook.io/settings/keys).

For interactive setup, run:

```bash theme={null}
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:

```bash theme={null}
growthbook whoami
```

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

```bash theme={null}
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`:

```bash theme={null}
growthbook features list --server-url https://gb-api.example.com/api
```

### Multiple organizations or servers

Named profiles bundle a server URL and credential together:

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
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):

```bash theme={null}
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](https://jqlang.github.io/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.

```bash theme={null}
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](https://docs.growthbook.io/lib/js.md#strict-typing):

```bash theme={null}
growthbook generate-types --output ./types
```

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

```json theme={null}
{
  "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 ](https://github.com/growthbook/cli/tree/main/docs), or run `growthbook --help` — every command's full usage, flags, and examples are built in.