Zuora CLI

Command-line interface for Zuora.

zuora-cli discovers the capabilities visible to your configured credentials and exposes them as domain-oriented commands.

Status: alpha, version 0.0.1-alpha.0. Command coverage and generated command names can change while the CLI is still in alpha.

Requirements

Node.js 18 or newer.

Install

For the current alpha, install from this repository:

npm install
npm run build
npm link

This exposes the zuora-cli command on your PATH.

Configure

Set the Zuora base URL and choose one authentication method.

Client credentials:

export ZUORA_BASE_URL="https://rest.apisandbox.zuora.com"
export ZUORA_CLIENT_ID="..."
export ZUORA_CLIENT_SECRET="..."

Bearer token:

export ZUORA_BASE_URL="https://rest.apisandbox.zuora.com"
export ZUORA_ACCESS_TOKEN="..."

The Bearer prefix is optional. You can also pass a token as a global option:

zuora-cli --access-token "$ZUORA_ACCESS_TOKEN" list

Optional environment variables:

| Variable | Purpose | | --- | --- | | ZUORA_BEARER_TOKEN | Alias for ZUORA_ACCESS_TOKEN. | | ZUORA_ENTITY_IDS | Sets the Zuora entity scope header. | | ZUORA_ORG_IDS | Sets the Zuora org scope header. | | ZUORA_VERSION | Sets the Zuora API version header. | | ZUORA_CLI_TIMEOUT_MS | Request timeout in milliseconds. Default: 120000. | | ZUORA_CLI_SCHEMA_CACHE_TTL_MS | Command metadata cache TTL in milliseconds. Default: 86400000. | | ZUORA_CLI_CACHE_DIR | Cache directory. Default: ~/.zuora-cli/cache. | | ZUORA_CLI_DISABLE_TOKEN_CACHE | Set to true to disable token cache reads and writes. |

Run zuora-cli --help to see the same environment variable list in the CLI.

Quick Start

List commands visible to your credentials:

zuora-cli list

Print command metadata as JSON:

zuora-cli list --json

Refresh command metadata:

zuora-cli refresh

Clear cached credentials and command metadata:

zuora-cli cache clear

Run a generated command:

zuora-cli product create \
  --name aaa \
  --effective-start-date 2026-01-01 \
  --effective-end-date 2099-12-31

Query an object:

zuora-cli object query --object-type account --page-size 1

Command Shape

Generated commands follow an AWS-style shape:

zuora-cli <domain> <operation> [options]

Examples:

| Command | Purpose | | --- | --- | | zuora-cli account summary ... | Retrieve account summary data. | | zuora-cli object query --object-type account | Query Zuora object records. | | zuora-cli product create ... | Create a product. | | zuora-cli commerce-product create ... | Create a commerce product. |

The naming layer is dynamic:

• Repeated entity names are removed from operations. For example, commerce product creation appears as commerce-product create, not commerce-product create-product.
• Multi-operation capabilities are split into subcommands. For example, order management operations become commands such as order get and order activate.

Input Flags

Primitive fields use normal options:

zuora-cli object query --object-type account --page-size 1

Object and array fields use JSON options:

zuora-cli some-domain some-operation --payload-json '{"name":"example"}'

Use command help to inspect available options:

zuora-cli <domain> <operation> --help

Output

Command output defaults to the response returned by Zuora.

zuora-cli list --json is available for scripts that need command metadata. Generated business commands do not require a separate --json flag.

Caching

zuora-cli caches command metadata and generated access tokens locally so each command does not need to rediscover capabilities or request a new token.

The cache is stored under ~/.zuora-cli/cache by default. Set ZUORA_CLI_CACHE_DIR to override it.

Access tokens are cached as local plaintext credential material. Cache directories and files are restricted to the current OS user where supported.

• Access tokens are reused until shortly before expiry.
• Changing the client secret creates a new token cache entry.
• Command metadata is cached for 24 hours by default.
• Run zuora-cli refresh to force command metadata refresh.
• Run zuora-cli cache clear to remove cached tokens and command metadata.
• Set ZUORA_CLI_DISABLE_TOKEN_CACHE=true to disable token cache reads and writes. Command metadata caching remains enabled.

Exit Codes

Commands exit with a nonzero status for parser errors, transport errors, and business validation failures returned by Zuora.

Troubleshooting

If a command is missing, run:

zuora-cli refresh
zuora-cli list

If authentication or command discovery behaves unexpectedly, clear local cache:

zuora-cli cache clear

If you are using a bearer token and also have client credential variables set, the explicit bearer token takes precedence.