Skip to content

growthbook/cli

BranchesTags

Repository files navigation

growthbook

Command-line interface for the GrowthBook REST API.

Built by Speakeasy License: MIT

Installation

The recommended way to install is via npm, which installs a small launcher that downloads the prebuilt binary for your platform:

npm i -g growthbook

Prefer a standalone binary with no Node.js dependency? An install script, go install, and prebuilt downloads are covered under CLI Installation below.

Versioning and stability

This CLI follows semantic versioning: breaking changes ship only in a major release and are called out in the changelog. Additive changes (new commands, flags, or response fields) are minor releases; fixes are patch releases. We recommend pinning to a version you have tested.

The CLI checks for a newer release at most once a day and prints a one-line notice to stderr (never stdout) when one is available and compatible with your server. Disable it with --no-update-check or GBCLI_NO_UPDATE_CHECK=1; it is also off automatically in CI and non-interactive shells.

Command versioning

Each command group targets the newest version of its API endpoint — e.g. features is the latest (v2) feature API. When a command is superseded, the previous version stays available under a version suffix (e.g. features-v1), deprecated and printing a one-line notice to stderr. When a newer API version lands, the base group advances to it and the prior version becomes the next -vN.

Because the bare command then returns the newer version's response shape, re-pointing a base command is a breaking change: it ships as a major release with the change called out in the changelog — so you can pin the prior major or move to the explicit -vN command on your own schedule.

Summary

GrowthBook REST API: A command-line interface for GrowthBook — manage feature flags, experiments, metrics, and more from your terminal.

Endpoints are versioned by path prefix: /v1 (stable) and /v2 (improved shapes). Each command group targets the newest version of its endpoint; superseded versions remain available under a -vN suffix.

Authenticate with a Secret Key or Personal Access Token via --bearer-auth (or the GBCLI_BEARER_AUTH environment variable). Run growthbook configure to store credentials, or growthbook whoami to check the active configuration.

Table of Contents

CLI Installation

Quick Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/growthbook/cli/main/scripts/install.sh | bash

Quick Install (Windows PowerShell)

iwr -useb https://raw.githubusercontent.com/growthbook/cli/main/scripts/install.ps1 | iex

Go Install

Alternatively, install directly via Go:

go install github.com/growthbook/cli/cmd/growthbook@latest

Manual Download

Download pre-built binaries for your platform from the releases page.

Shell Completion

Shell completions are available for Bash, Zsh, Fish, and PowerShell.

Bash

# Add to ~/.bashrc:
source <(growthbook completion bash)

# Or install permanently:
growthbook completion bash > /etc/bash_completion.d/growthbook

Zsh

# Add to ~/.zshrc:
source <(growthbook completion zsh)

# Or install permanently:
growthbook completion zsh > "${fpath[1]}/_growthbook"

Fish

growthbook completion fish | source

# Or install permanently:
growthbook completion fish > ~/.config/fish/completions/growthbook.fish

PowerShell

growthbook completion powershell | Out-String | Invoke-Expression

CLI Example Usage

Example

growthbook get-SDK-payload --bearer-auth 'Bearer test_token' --key '<key>'

Authentication

Authentication credentials can be configured in four ways (in order of priority):

1. Command-line flags

Pass credentials directly as flags to any command:

growthbook --bearer-auth <value> --username <value> --password <value> <command> [arguments]

2. Environment variables

Set credentials via environment variables:

Variable Description
GBCLI_BEARER_AUTH Bearer auth token: your Secret Key or Personal Access Token, sent as an Authorization Bearer header.
GBCLI_USERNAME HTTP Basic auth: your Secret Key as the username, with an empty password. username
GBCLI_PASSWORD HTTP Basic auth: your Secret Key as the username, with an empty password. password

3. OS Keychain (recommended for workstations)

Credentials are stored securely in your operating system's keychain when you run:

growthbook configure

Secret credentials (tokens, API keys, passwords) are automatically stored in:

  • macOS: Keychain
  • Linux: GNOME Keyring / KWallet (via D-Bus Secret Service)
  • Windows: Windows Credential Locker

If no keychain is available (e.g., in CI environments), credentials fall back to the config file.

4. Configuration file

Run the interactive configure command to store non-secret settings:

growthbook configure

Configuration is stored in ~/.config/growthbook/config.yaml.

Profiles

Profiles let you switch between GrowthBook environments (e.g. cloud, staging, self-hosted), each with its own server URL and API key. Keys are stored in your OS keychain, not in plaintext config.

# Create or update a profile (the key comes from --bearer-auth, stored in the keychain)
growthbook profiles set staging --server-url https://gb.staging.example.com/api --bearer-auth secret_xxx

growthbook profiles use staging      # make it the active profile
growthbook profiles list             # show configured profiles
growthbook profiles remove staging   # delete one

Select a profile for a single command with --profile <name>, or set GBCLI_PROFILE in your environment. (Upgrading from the legacy CLI? An existing ~/.growthbook/config.toml is imported into profiles automatically on first run — see MIGRATION.md.)

Generating TypeScript types

generate-types fetches all of your features and writes a TypeScript AppFeatures definition, giving you type-safe feature keys and values in the GrowthBook SDK:

growthbook generate-types                                   # → ./growthbook-types/app-features.ts
growthbook generate-types --output ./src/types --filename growthbook.ts
growthbook generate-types --project prj_123                 # limit to one project

Available Commands

Available commands

features-v1

  • ~~list~~ - Get all features ⚠️ Deprecated
  • ~~create~~ - Create a single feature ⚠️ Deprecated
  • ~~get~~ - Get a single feature ⚠️ Deprecated
  • ~~update~~ - Partially update a feature ⚠️ Deprecated
  • ~~delete~~ - Deletes a single feature ⚠️ Deprecated
  • ~~toggle~~ - Toggle a feature in one or more environments ⚠️ Deprecated
  • ~~revert~~ - Revert a feature to a specific revision ⚠️ Deprecated
  • ~~get-feature-keys~~ - Get list of feature keys ⚠️ Deprecated
  • ~~get-feature-stale~~ - Get stale status for one or more features ⚠️ Deprecated

feature-revisions-v1

features

  • list - Get all features
  • create - Create a single feature
  • get - Get a single feature
  • update - Partially update a feature
  • delete - Deletes a single feature
  • toggle - Toggle a feature in one or more environments
  • revert - Revert a feature to a specific revision
  • get-feature-keys - Get list of feature keys
  • get-feature-stale - Get stale status for one or more features

feature-revisions

archetypes

  • list - Get the organization's archetypes
  • create - Create a single archetype
  • get - Get a single archetype
  • update - Update a single archetype
  • delete - Deletes a single archetype

experiments

snapshots

visual-changesets

  • list - Get all visual changesets
  • create - Create a visual changeset for an experiment
  • get - Get a single visual changeset
  • update - Update a visual changeset
  • post-visual-change - Create a visual change for a visual changeset
  • put-visual-change - Update a visual change for a visual changeset

contextual-bandits

metrics

  • list - Get all metrics
  • create - Create a single metric
  • get - Get a single metric
  • update - Update a metric
  • delete - Deletes a metric

usage-metrics

  • get - Get metric usage across experiments

segments

  • list - Get all segments
  • create - Create a single segment
  • get - Get a single segment
  • update - Update a single segment
  • delete - Deletes a single segment

dimensions

  • list - Get all dimensions
  • create - Create a single dimension
  • get - Get a single dimension
  • update - Update a single dimension
  • delete - Deletes a single dimension

projects

  • list - Get all projects
  • create - Create a single project
  • get - Get a single project
  • update - Edit a single project
  • delete - Deletes a single project

environments

  • list - Get the organization's environments
  • create - Create a new environment
  • update - Update an environment
  • delete - Deletes a single environment

attributes

  • list - Get the organization's attributes
  • create - Create a new attribute
  • update - Update an attribute
  • delete - Deletes a single attribute

SDK-connections

data-sources

saved-groups

  • list - Get all saved group
  • create - Create a single saved group
  • get - Get a single saved group
  • update - Partially update a single saved group
  • delete - Deletes a single saved group
  • archive - Archive a single saved group
  • unarchive - Unarchive a single saved group
  • get-saved-group-references - Get features, experiments, and saved groups that reference this saved group

saved-group-revisions

constants

  • list - Get all constants
  • create - Create a single constant
  • get-constant-references - Get features and constants that reference this constant
  • get - Get a single constant
  • update - Partially update a single constant
  • delete - Delete a single constant
  • archive - Archive a single constant
  • unarchive - Unarchive a single constant

constant-revisions

organizations

  • list - Get all organizations (only for super admins on multi-org Enterprise Plan only)
  • create - Create a single organization (only for super admins on multi-org Enterprise Plan only)
  • update - Edit a single organization (only for super admins on multi-org Enterprise Plan only)

fact-tables

fact-metrics

code-references

members

  • list - Get all organization members
  • update-member-role - Update a member's global role (including any enviroment restrictions, if applicable). Can also update a member's project roles if your plan supports it.
  • delete - Removes a single user from an organization

queries

settings

  • get - Get organization settings

meta

  • get-version - Get the GrowthBook server version and build info

ramp-schedules

reports

namespaces

dashboards

contextual-bandit-queries

custom-fields

  • create - Create a single customField
  • list - Get all custom fields
  • delete - Delete a single customField
  • get - Get a single customField
  • update - Update a single customField

metric-groups

  • get - Get a single metricGroup
  • delete - Delete a single metricGroup
  • update - Update a single metricGroup
  • create - Create a single metricGroup
  • list - Get all metricGroups

teams

experiment-templates

  • get - Get a single experimentTemplate
  • delete - Delete a single experimentTemplate
  • update - Update a single experimentTemplate
  • create - Create a single experimentTemplate
  • list - Get all experimentTemplates
  • bulk-import - Bulk create or update experiment templates

analytics-explorations

ramp-schedule-templates

  • get - Get a single rampScheduleTemplate
  • delete - Delete a single rampScheduleTemplate
  • update - Update a single rampScheduleTemplate
  • create - Create a single rampScheduleTemplate
  • list - Get all rampScheduleTemplates

Request Body Input

Operations that accept a request body support three input methods, with a clear priority chain:

Individual flags (highest priority)

growthbook <command> --name "Jane" --age 30

--body flag

Provide the entire request body as a JSON string:

growthbook <command> --body '{"name": "John", "age": 30}'

Individual flags override --body values:

# Result: {name: "Jane", age: 30}
growthbook <command> --body '{"name": "John", "age": 30}' --name "Jane"

Stdin piping (lowest priority)

Pipe JSON into any command that accepts a request body:

echo '{"name": "John", "age": 30}' | growthbook <command>

Individual flags override stdin values:

# Result: {name: "Jane", age: 30}
echo '{"name": "John", "age": 30}' | growthbook <command> --name "Jane"

This is useful for chaining commands, reading from files, or scripting:

# Read body from a file
growthbook <command> < request.json

# Pipe from another command
curl -s https://example.com/data.json | growthbook <command>

Priority

When multiple input methods are used, the priority is:

Priority Source Description
1 (highest) Individual flags --name "Jane" always wins
2 --body flag Whole-body JSON via flag
3 (lowest) Stdin Piped JSON input

Server Selection

Select Server by Index

Use --server <index> to select a server by its zero-based index (default: 0):

# Server Variables Description
0 https://api.growthbook.io/api GrowthBook Cloud
1 https://{domain}/api domain Self-hosted GrowthBook 
growthbook --server <index> <command> [arguments]

Server Variables

Some server URLs contain template variables (e.g., https://{hostname}:{port}/v1). Set these via dedicated flags:

Variable Flag Default Description
domain --domain <value> "localhost:3100" Your self-hosted GrowthBook host (and port) 
growthbook --domain value <command> [arguments]

Server variable flags are combined with the selected server URL to produce the final endpoint.

Override Server URL

Use --server-url to override the server URL entirely, bypassing any named or indexed server selection:

growthbook --server-url https://custom-api.example.com <command> [arguments]

Precedence: --server-url > --server > default

Output Formats

Every command supports a --output-format flag that controls how the response is rendered to stdout.

Available formats

Format Flag Description
Pretty --output-format pretty (default) Aligned key-value pairs with color, nested indentation. Human-readable at a glance.
JSON --output-format json JSON output. Passthrough when the response is already JSON (preserves original field order and numeric precision). Falls back to typed marshaling otherwise.
YAML --output-format yaml YAML output via standard marshaling.
Table --output-format table Tabular output for array responses.
TOON --output-format toon Token-Oriented Object Notation — a compact, line-oriented format that typically uses 30–60% fewer tokens than JSON. Well-suited for piping responses into LLM prompts. 
# Default pretty output
growthbook <command>

# Machine-readable JSON
growthbook <command> --output-format json

# TOON for LLM-friendly compact output
growthbook <command> --output-format toon

# Pipe JSON to jq without using --output-format
growthbook <command> --output-format json | jq '.fieldName'

jq filtering

Use --jq to filter or transform the response inline using a jq expression. This always outputs JSON and overrides --output-format:

# Extract a single field
growthbook <command> --jq '.name'

# Filter an array
growthbook <command> --jq '.items[] | select(.active == true)'

Color control

Use --color to control terminal colors:

Value Behavior
auto (default) Color when stdout is a TTY, plain text otherwise
always Always colorize
never Never colorize

The NO_COLOR and FORCE_COLOR environment variables are also respected.

Streaming and pagination

When using --all (pagination) or streaming operations, output is written incrementally as items arrive:

Format Streaming behavior
json One compact JSON object per line (NDJSON)
yaml YAML documents separated by ---
toon One TOON-encoded object per block, separated by blank lines
pretty (default) Pretty-printed items separated by blank lines

Pagination

Some operations in this CLI support automatic pagination. These operations accept --all to automatically fetch all pages and stream results incrementally.

Basic usage

# Fetch a single page (default behavior)
growthbook <command> --page 1

# Automatically fetch all pages
growthbook <command> --all

Limiting pages

Use --max-pages to cap the number of pages fetched:

# Fetch at most 5 pages
growthbook <command> --all --max-pages 5

Output formats

When using --all, results are streamed as each page is fetched:

Format Behavior
--output-format json One JSON object per line (NDJSON)
--output-format yaml YAML documents separated by ---
--output-format toon One TOON-encoded block per item, separated by blank lines
Default (pretty) Pretty-printed items separated by blank lines 
# Stream all results as NDJSON
growthbook <command> --all --output-format json

# Pipe to jq for further processing
growthbook <command> --all --output-format json | jq '.fieldName'

# Use the built-in --jq flag
growthbook <command> --all --jq '.fieldName'

How it works

Under the hood, --all calls the operation once, then follows the underlying Next() pagination closure to fetch subsequent pages. Results are written to stdout as they arrive rather than buffered in memory, so this works well even with large result sets.

Without --all, paginated operations behave like any other command — pass cursor, page, offset, or limit flags manually and get a single page of results.

Error Handling

The CLI uses standard exit codes to indicate success or failure:

Exit Code Meaning
0 Success
1 Error (API error, invalid input, etc.)

On success, the response data is printed to stdout as JSON. On failure, error details are printed to stderr.

# Capture output and handle errors
growthbook ... > output.json 2> error.log
if [ $? -ne 0 ]; then
  echo "Error occurred, see error.log"
fi

Diagnostics

The CLI includes two diagnostic flags available on all commands:

Dry Run

Preview what would be sent without making any network calls:

growthbook <command> --dry-run

Output goes to stderr and includes:

  • HTTP method and URL
  • Request headers (sensitive values redacted)
  • Request body preview (sensitive fields redacted)

The command exits successfully without contacting the API. This is useful for verifying request construction before executing.

Debug

Log request and response diagnostics while running normally:

growthbook <command> --debug

Debug output goes to stderr and includes:

  • Request method, URL, headers, and body preview
  • Response status, headers, and body preview
  • Transport errors (if any)

The command still executes normally and produces its regular output on stdout.

Flag Precedence

If both --dry-run and --debug are set, --dry-run takes precedence and no network calls are made.

Security

Sensitive information is automatically redacted in diagnostic output:

  • Headers: Authorization, Cookie, Set-Cookie, X-API-Key, and other security headers show [REDACTED]
  • Body: JSON fields named password, secret, token, api_key, client_secret, etc. show [REDACTED]

Diagnostic output should still be treated as potentially sensitive operational data.

Development

Maturity

This CLI follows semantic versioning and a stable command-versioning convention — see Versioning and stability at the top of this README. We recommend pinning to a version you have tested.

Contributions

While we value open-source contributions to this CLI, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

CLI Created by Speakeasy

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages