Configuration

The Chargebee CLI authenticates with a Chargebee site name and an API key. Get a key from the dashboard: Settings > Configure Chargebee > API Keys.

A profile saves the connection settings for a site. The active profile is the one the CLI uses unless you select another profile or supply credentials through environment variables.

Configure the CLI interactively

chargebee auth add

The command prompts for the region, site name, API key, and profile name. It verifies the credentials against the API, detects the site's Product Catalog version when the key permits it, and saves the connection as the active profile.

Configure the CLI without prompts

For sites outside the United States, include the region.

chargebee auth add --site acme-test --api-key test_xxx

You can also provide the API key through the CHARGEBEE_API_KEY environment variable:

CHARGEBEE_API_KEY="test_xxx" chargebee auth add --site acme-test

Check the active CLI connection

Show the selected site, region, and whether it is a test or live site:

chargebee auth status
chargebee auth whoami     # alias of auth status

Manage named CLI profiles

Save a profile for each site you use, then switch between profiles. These setup commands prompt for the API key:

chargebee auth add --profile test --site acme-test
chargebee auth add --profile prod --site acme

chargebee auth list                # show saved profiles and their storage
chargebee auth switch              # choose a profile interactively
chargebee auth switch prod         # switch by name
chargebee auth rename prod live    # rename without re-entering the key

Run a single command against another profile with --use-profile:

chargebee --use-profile test customer list

--use-profile selects which site a command talks to, so it applies to API commands, open, and listen. For other commands, use chargebee auth switch to change the active profile.

Configure CLI credentials with environment variables

For CI pipelines and containers, set both variables to authenticate without saving a profile:

export CHARGEBEE_SITE="acme-test"
export CHARGEBEE_API_KEY="test_xxx"

chargebee customer list

CHARGEBEE_SITE and CHARGEBEE_API_KEY must be set together.

Credentials resolve in this order:

1. --use-profile <name>
2. CHARGEBEE_SITE + CHARGEBEE_API_KEY
3. The active profile

Environment variables take precedence over the active profile, even after auth switch. To return to saved profiles, unset both variables:

unset CHARGEBEE_SITE CHARGEBEE_API_KEY

Set the site region

Set the region where your site is hosted: the United States, Europe, or Australia. The CLI saves the region in the profile and uses it to connect to services such as webhook forwarding.

Interactive setup asks for the region unless you pass --region. When you supply both the site and API key, setup defaults to us. Include --region for sites hosted in Europe or Australia:

chargebee auth add --site acme-test --api-key test_xxx --region eu

chargebee auth status and chargebee auth list show the saved region. To change it, run chargebee auth add --profile <name> --region <region>. This replaces the saved profile, so supply the site and API key again.

To override the region in your current shell session:

export CHARGEBEE_REGION="eu"      # takes precedence over the profile's region

Set the CLI API host

The CLI sends requests to https://<site>.<host>, where the host defaults to chargebee.com. Set a different host when you configure a profile, and it is saved with that profile:

chargebee auth add --site acme-test --host chargebee.com

With environment-variable credentials, or when no profile is configured, CHARGEBEE_HOST sets the host instead.

CLI credential and configuration storage

By default, the CLI saves API keys in your operating system's credential store: macOS Keychain, Linux Secret Service, or Windows Credential Manager. Linux requires secret-tool and an accessible keyring. Windows uses Windows PowerShell.

If the credential store is unavailable or saving the key fails, the CLI saves the key in the profile file. On macOS and Linux, the file has mode 600. Check the storage location in the setup output or the STORE column of chargebee auth list.

To change where the CLI stores configuration and API keys:

• Set CHARGEBEE_CLI_KEYCHAIN=0 to save API keys in profile files.
• Set CHARGEBEE_CONFIG_DIR to use a different configuration directory. This also saves API keys in profile files by default.
• Set CHARGEBEE_CLI_KEYCHAIN=1 alongside CHARGEBEE_CONFIG_DIR to use the operating system's credential store with that directory.

If a profile uses the credential store and its key cannot be read, commands fail with recovery guidance. Restore access to the store or run chargebee auth add --profile <name> to save the key again.

Remove a saved CLI profile

chargebee auth remove test

The command asks for confirmation, removes the profile, and attempts to delete its stored API key. It reports any credential cleanup failure. To remove a profile in a script, include its name and --yes:

chargebee auth remove test --yes

Removing the active profile interactively lets you choose another saved profile. With --yes, the CLI clears the active profile instead; run chargebee auth switch <name> to select another. Environment-variable credentials remain in effect until you unset them.

Turn off CLI telemetry

Usage telemetry is on by default and can be turned off at any time:

chargebee telemetry disable

See Telemetry for recorded fields and automatic opt-outs.