> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.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

export const ExternalLink = () => {
  return <svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" style={{
    display: "inline-block",
    verticalAlign: "-0.125em",
    marginLeft: "0.15em"
  }}>
      <path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path>
    </svg>;
};

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

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

## 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 <ExternalLink />](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** <ExternalLink />](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](/lib/js#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 <ExternalLink />](https://github.com/growthbook/cli/tree/main/docs), or run `growthbook --help` — every command's full usage, flags, and examples are built in.