cli

module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 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: 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: use your GrowthBook Secret Key as the username and leave the password empty. username
GBCLI_PASSWORD HTTP Basic auth: use your GrowthBook Secret Key as the username and leave the password empty. 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
  • ~~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
  • add-visual-change - Create a visual change for a visual changeset
  • update-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
  • list - List saved-group revisions across the organization
  • list-for-saved-group - List revisions for a saved group
  • create - Create a draft revision
  • latest - Get the most recent active draft revision
  • get - Get a single saved group revision
  • set-metadata - Update saved group metadata in a draft revision
  • set-condition - Update the condition of a condition saved group draft revision
  • set-values - Replace the values list in a list saved group draft revision
  • archive - Stage an archive/unarchive in a draft revision
  • add-items - Append items to a list saved group draft revision
  • remove-items - Remove items from a list saved group draft revision
  • request-review - Request review for a draft revision
  • submit-review - Submit a review on a draft revision
  • merge-status - Get merge status for a draft revision
  • rebase - Rebase a draft revision onto the current live saved group
  • publish - Publish a draft revision
  • discard - Discard a draft revision
  • revert - Revert the saved group to a prior revision
constants
  • list - Get all constants
  • create - Create a single constant
  • get-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
  • list - List constant revisions across the organization
  • list-for-constant - List revisions for a constant
  • create - Create a draft revision
  • latest - Get the most recent active draft revision
  • get - Get a single constant revision
  • set-metadata - Update constant metadata in a draft revision
  • set-value - Update the value of a constant draft revision
  • archive - Stage an archive/unarchive in a draft revision
  • request-review - Request review for a draft revision
  • submit-review - Submit a review on a draft revision
  • merge-status - Get merge status for a draft revision
  • rebase - Rebase a draft revision onto the current live constant
  • publish - Publish a draft revision
  • discard - Discard a draft revision
  • revert - Revert the constant to a prior revision
configs
  • list - Get all configs
  • create - Create a single config
  • get-references - Get features and configs that reference this config
  • get-key-usage - Get the feature rules and default values implementing each key
  • get-lineage - Get the full lineage (family tree) for a config
  • verify-schema - Verify a config's schema against a source (drift check)
  • get-schema - Export a config's schema
  • get - Get a single config
  • update - Partially update a single config
  • delete - Delete a single config
  • archive - Archive a single config
  • unarchive - Unarchive a single config
  • lock - Lock a config at its current published revision
  • unlock - Unlock a config
config-revisions
  • list - List config revisions across the organization
  • list-for-config - List revisions for a config
  • create - Create a draft revision
  • latest - Get the most recent active draft revision
  • get - Get a single config revision
  • set-metadata - Update config metadata in a draft revision
  • set-value - Update the value of a config draft revision
  • set-schema - Update or import the schema of a config draft revision
  • set-projection - Set (or update) a config's per-source render projection on a draft
  • delete-projection - Remove a config's per-source render projection on a draft
  • archive - Stage an archive/unarchive in a draft revision
  • request-review - Request review for a draft revision
  • submit-review - Submit a review on a draft revision
  • recall-review - Recall a review request
  • reopen - Reopen a discarded revision
  • schedule-publish - Schedule (or cancel) a deferred publish
  • merge-status - Get merge status for a draft revision
  • rebase - Rebase a draft revision onto the current live config
  • publish - Publish a draft revision
  • discard - Discard a draft revision
  • revert - Revert the config to a prior revision
custom-hooks
  • list - Get all custom hooks
  • create - Create a single custom hook
  • test - Dry-run hook code in the sandbox
  • get - Get a single custom hook
  • update - Partially update a single custom hook
  • delete - Delete a single custom hook
  • list-history - List a custom hook's version history
  • revert - Revert a custom hook to a previous version
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
  • list - Get all fact metrics
  • create - Create a single fact metric
  • get - Get a single fact metric
  • update - Update a single fact metric
  • delete - Deletes a single fact metric
  • create-analysis - Create a fact metric analysis
code-references
  • submit - Submit list of code references
  • list - Get list of all code references for the current organization
  • get-for-feature - Get list of code references for a single feature id
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
  • list - Get all reports
  • create - Create a new report
  • get - Get a single report
  • refresh - Refresh a report by re-running its analysis
  • set-metadata - Update report metadata (title, description, visibility)
  • set-settings - Update report analysis settings
namespaces
dashboards
  • get - Get a single dashboard
  • delete - Delete a single dashboard
  • update - Update a single dashboard
  • create - Create a single dashboard
  • list - Get all dashboards
  • list-for-experiment - Get all dashboards for an experiment
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

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/configrevisions
cli/configs
cli/constantrevisions
cli/constants
cli/contextualbanditqueries
cli/contextualbandits
cli/customfields
cli/customhooks
cli/dashboards
cli/datasources
cli/dimensions
cli/environments
cli/experiments
cli/experimenttemplates
cli/factmetrics
cli/facttables
cli/featurerevisions
cli/featurerevisionsv1
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.