cli

module
v1.0.0-next.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 7, 2026 License: Apache-2.0

README

growthbook

Command-line interface for the GrowthBook REST API.

Built by Speakeasy

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: GrowthBook offers a full REST API for interacting with the application.

Request data can use either JSON or Form data encoding (with proper Content-Type headers). All response bodies are JSON-encoded.

The API base URL for GrowthBook Cloud is https://api.growthbook.io/api. For self-hosted deployments, it is the same as your API_HOST environment variable (defaults to http://localhost:3100/api). The rest of these docs will assume you are using GrowthBook Cloud.

Versioning

Endpoints are versioned by path prefix:

  • /v1/... — stable, widely-supported endpoints
  • /v2/... — updated endpoints with improved shapes (e.g. unified per-rule environment scope for feature flags)

New integrations should prefer v2 where available.

Authentication

We support both the HTTP Basic and Bearer authentication schemes for convenience.

You first need to generate a new API Key in GrowthBook. Different keys have different permissions:

  • Personal Access Tokens: These are sensitive and provide the same level of access as the user has to an organization. These can be created by going to Personal Access Tokens under the your user menu.
  • Secret Keys: These are sensitive and provide the level of access for the role, which currently is either admin or readonly. Only Admins with the manageApiKeys permission can manage Secret Keys on behalf of an organization. These can be created by going to Settings -> API Keys

If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank (when using curl, add : at the end of the secret to indicate an empty password)

curl https://api.growthbook.io/api/v1/features \



  -u secret_abc123DEF456:

If using Bearer auth, pass the Secret Key as the token:

curl https://api.growthbook.io/api/v1/features \
-H "Authorization: Bearer secret_abc123DEF456"

Errors

The API may return the following error status codes:

  • 400 - Bad Request - Often due to a missing required parameter
  • 401 - Unauthorized - No valid API key provided
  • 402 - Request Failed - The parameters are valid, but the request failed
  • 403 - Forbidden - Provided API key does not have the required access
  • 404 - Not Found - Unknown API route or requested resource
  • 422 - Soft Warning - The request failed, but can be re-submitted with ?ignoreWarnings=true to proceed anyway.
  • 429 - Too Many Requests - You exceeded the rate limit of 60 requests per minute. Try again later.
  • 5XX - Server Error - Something went wrong on GrowthBook's end (these are rare)

The response body will be a JSON object with the following properties:

  • message - Information about the error

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 If using Bearer auth, pass the Secret Key as the token: 
curl https://api.growthbook.io/api/v1/features   -H "Authorization: Bearer secret_abc123DEF456"
``` |
| `GBCLI_USERNAME` | If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank:
```bash
curl https://api.growthbook.io/api/v1/features   -u secret_abc123DEF456:
# The ":" at the end stops curl from asking for a password

username | | GBCLI_PASSWORD | If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank:

curl https://api.growthbook.io/api/v1/features   -u secret_abc123DEF456:
# The ":" at the end stops curl from asking for a password

password |

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
  • ~~post~~ - 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
features
  • list - Get all features
  • post - 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-v2
archetypes
  • list - Get the organization's archetypes
  • post - Create a single archetype
  • get - Get a single archetype
  • put - Update a single archetype
  • delete - Deletes a single archetype
experiments
snapshots
visual-changesets
  • list - Get all visual changesets
  • post - Create a visual changeset for an experiment
  • get - Get a single visual changeset
  • put - 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
  • post - Create a single metric
  • get - Get a single metric
  • put - Update a metric
  • delete - Deletes a metric
usage-metrics
  • get - Get metric usage across experiments
segments
  • list - Get all segments
  • post - Create a single segment
  • get - Get a single segment
  • update - Update a single segment
  • delete - Deletes a single segment
dimensions
  • list - Get all dimensions
  • post - Create a single dimension
  • get - Get a single dimension
  • update - Update a single dimension
  • delete - Deletes a single dimension
projects
  • list - Get all projects
  • post - Create a single project
  • get - Get a single project
  • put - Edit a single project
  • delete - Deletes a single project
environments
  • list - Get the organization's environments
  • post - Create a new environment
  • put - Update an environment
  • delete - Deletes a single environment
attributes
  • list - Get the organization's attributes
  • post - Create a new attribute
  • put - Update an attribute
  • delete - Deletes a single attribute
SDK-connections
  • list - Get all sdk connections
  • post - Create a single sdk connection
  • get - Get a single sdk connection
  • put - Update a single sdk connection
  • delete - Deletes a single SDK connection
  • lookup-SDK-connection-by-key - Find a single sdk connection by its key
data-sources
saved-groups
  • list - Get all saved group
  • post - 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
  • post - 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)
  • post - Create a single organization (only for super admins on multi-org Enterprise Plan only)
  • put - 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

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

Directories

Path Synopsis
cmd
gendocs command
growthbook command
internal
cli
Hand-written (NOT generated).
 Hand-written (NOT generated).
cli/analyticsexplorations
cli/archetypes
cli/attributes
cli/codereferences
cli/constantrevisions
cli/constants
cli/contextualbanditqueries
cli/contextualbandits
cli/customfields
cli/dashboards
cli/datasources
cli/dimensions
cli/environments
cli/experiments
cli/experimenttemplates
cli/factmetrics
cli/facttables
cli/featurerevisions
cli/featurerevisionsv2
cli/features
cli/featuresv1
cli/members
cli/meta
cli/metricgroups
cli/metrics
cli/namespaces
cli/organizations
cli/projects
cli/queries
cli/rampschedules
cli/rampscheduletemplates
cli/reports
cli/savedgrouprevisions
cli/savedgroups
cli/sdkconnections
cli/segments
cli/settings
cli/snapshots
cli/teams
cli/usagemetrics
cli/visualchangesets
client
config
Package config provides configuration management for the CLI.
 Package config provides configuration management for the CLI.
customcfg
Package customcfg holds hand-written (NOT generated) configuration that the generated config.Config struct can't carry — named profiles, each with a server URL and (keychain-stored) secret — plus one-time migration from the legacy TS CLI.
 Package customcfg holds hand-written (NOT generated) configuration that the generated config.Config struct can't carry — named profiles, each with a server URL and (keychain-stored) secret — plus one-time migration from the legacy TS CLI.
explorer
flagutil
Package flagutil provides utilities for working with Cobra flags, particularly for handling persistent flags and the Changed() pattern.
 Package flagutil provides utilities for working with Cobra flags, particularly for handling persistent flags and the Changed() pattern.
interactive
Package interactive provides auto-prompting for missing required flags using huh forms when running in a TTY.
 Package interactive provides auto-prompting for missing required flags using huh forms when running in a TTY.
output
Package output provides utilities for formatting and outputting CLI command results.
 Package output provides utilities for formatting and outputting CLI command results.
sdk
sdk/models/components
sdk/models/operations
sdk/models/sdkerrors
sdk/optionalnullable
sdk/retry
sdk/sdkinternal/config
sdk/sdkinternal/hooks
sdk/sdkinternal/utils
sdk/types
testclient
usage

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.