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

Read operations such as list and retrieve work on test and live sites. Write operations such as create, update, and delete require a test site.

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

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.