Commands

Use the Chargebee CLI to call APIs from your terminal or scripts.

Run a command

Each API resource has operations such as list, retrieve, and create:

chargebee <resource> <operation> [id] [-d key=value ...]

For example:

chargebee customer list
chargebee customer retrieve cust_123

Discover commands

Use these commands to find resources, operations, and parameters:

chargebee resources                 # List API resources
chargebee customer --help           # List customer operations
chargebee customer create --help    # Show usage and available examples
chargebee docs customer create      # Show the full parameter reference

chargebee docs fetches the published API reference and caches it locally for later use.

Pass request parameters

Use -d for individual parameters

Repeat -d key=value for each parameter. Use bracket notation for nested values:

chargebee customer create \
  -d first_name=Ada \
  -d email=ada@example.com \
  -d 'billing_address[country]=US'

Quote arguments that contain brackets. Otherwise, shells such as zsh may reject them before the CLI runs.

Values starting with [ or { are parsed as JSON. Use this for arrays and objects:

chargebee subscription create-with-items cust_123 \
  -d 'subscription_items=[{"item_price_id":"standard-USD-monthly","quantity":1}]'

This operation requires Product Catalog 2.0 and an existing item price.

Use JSON for larger requests

Pass - as the last argument to read a JSON object from standard input. Use nested objects for nested parameters:

echo '{"email":"ada@example.com","billing_address":{"city":"San Francisco"}}' \
  | chargebee customer create -

Do not combine - with -d.

Filter list results

Include the filter’s operator in brackets:

chargebee customer list -d 'email[is]=ada@example.com'
chargebee customer list -d 'id[in]=["cust_123","cust_456"]'

For JSON input, nest the operator inside the filter:

echo '{"status":{"in":["active","paused"]}}' \
  | chargebee subscription list -

Supported operators vary by filter. Check them with the relevant docs command:

chargebee docs customer list

Pagination parameters such as limit and offset take plain values:

chargebee customer list -d limit=20

Process responses

API commands write JSON to stdout and errors and diagnostics to stderr. Failed requests return a nonzero exit code.

Use jq to select values:

chargebee customer list | jq -r '.list[].customer.email'

chargebee invoice list -d limit=5 \
  | jq '.list[].invoice | {id, total, status}'

You can also capture a value for another command:

CUSTOMER_ID=$(chargebee customer create -d email=ada@example.com | jq -r '.customer.id')
chargebee customer retrieve "$CUSTOMER_ID"

Get JSON output from any CLI command

API responses are already JSON. Add --json when scripts or AI agents need consistent JSON output from other commands too:

chargebee auth status --json
chargebee resources --json | jq -r '.resources[]'

With --json:

• Successful, non-streaming commands return one JSON document.
• Commands never prompt for input. Supply required values through flags or supported environment variables.
• Errors are JSON objects on stderr and include an exit code. Warnings also go to stderr.
• Non-streaming commands leave stdout empty on failure.
• listen streams one JSON object per line. See Webhook forwarding.

Exit codes

Scripts can use these exit codes with or without --json:

Site restrictions

Live sites

Live-site write confirmation is available in Chargebee CLI 1.5.1 and later. Older versions block live-site writes. Run chargebee update to upgrade. See Upgrade the Chargebee CLI.

Read operations such as list and retrieve work on test and live sites without confirmation.

Write operations such as create, update, and delete change production data on a live site, so the CLI asks for confirmation first:

Run "customer update" on LIVE site "acme"? This changes production data.

The default is No. If you decline, the command exits with code 6 and nothing changes.

Some commands cannot prompt for confirmation, including commands run in scripts, CI, --json mode, or with input or output piped or redirected. Pass -y or --yes to confirm the write. Without it, the command exits with code 6:

chargebee customer update cust_123 -d auto_collection=off --yes

Writes on test sites run without confirmation. Use a test site while you build and test integrations.

Generating a code sample sends no API request, so --code-sample works on live sites without confirmation.

Product Catalog versions

Use operations that match your site’s Product Catalog. For example:

• Product Catalog 1.0: subscription create
• Product Catalog 2.0: subscription create-with-items

When the site’s catalog version is known, the CLI blocks incompatible operations before sending a request. This check also applies to code samples. Operations supported by both catalogs remain available.

Auto-upgraded sites allow both subscription operations. If the CLI cannot determine the catalog version, it skips the check.

Troubleshoot commands

For other workflows, see Configuration, Webhook forwarding, and AI agents.