> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/subscriptions.md).

# subscriptions

Read-only view of the account's licensing and entitlement usage — what tier the account is on, what it's consuming, and how that's trended month-over-month.

**REST API**: [Subscription & Entitlements](https://developer.celigo.com/api/api-reference/account-and-admin/subscription-and-entitlements)

**OpenAPI spec**: `dist/subscription.yml` in `@celigo/api-specs` — see [OpenAPI specs](https://developer.celigo.com/api/using-the-api/openapi-specs)

```
celigo subscriptions <subcommand>
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand          | Purpose                                                                    |
| ------------------- | -------------------------------------------------------------------------- |
| `licenses`          | License (subscription) information for the current account.                |
| `usage`             | One combined object aggregating every usage surface, fetched in parallel.  |
| `entitlement-usage` | Current usage vs allocation per license entitlement, split by environment. |
| `historical-usage`  | Historical monthly entitlement usage for flow-run pricing models.          |
| `api-usage`         | API-call usage detail for the account.                                     |

***

## `celigo subscriptions licenses`

Fetch the licenses associated with the current account.

**Signature**

```bash
celigo subscriptions licenses
```

**Arguments**

None.

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
# Identify the subscription tier
celigo subscriptions licenses --format json | jq '.[] | {type, tier: .tier}'
```

**Corresponds to**: [`GET /v1/licenses`](https://developer.celigo.com/api/api-reference/account-and-admin/subscription-and-entitlements#get-v1-licenses)

***

## `celigo subscriptions usage`

Return one combined object aggregating every usage surface, fetched in parallel: account usage (`usage`), API (`apiUsage`), license entitlement (`entitlementUsage`), historical monthly (`historicalMonthlyUsage`), EDI label printing (`labelPrinting`), storage per environment (`storage`), and syncs (`syncs`). License-gated sources you lack come back as inline `{"error": ...}` entries instead of failing the command.

> **Breaking change in celigo-cli 2026.8.7.** `usage` previously printed only the bare `/v1/usage` account records — a monthly array with duration in milliseconds. Anything parsing that old shape should pipe `--jq .usage`, which yields exactly the old payload.

**Signature**

```bash
celigo subscriptions usage
```

**Arguments**

None.

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
# The combined seven-surface object
celigo subscriptions usage

# Just the legacy account usage records (the pre-2026.8.7 output)
celigo subscriptions usage --jq .usage
```

**Corresponds to**: seven parallel reads — [`GET /v1/usage`](https://developer.celigo.com/api/api-reference/account-and-admin/subscription-and-entitlements), [`GET /v1/apis/usage`](https://developer.celigo.com/api/api-reference/api-management/apis), [`GET /v1/licenseEntitlementUsage`](https://developer.celigo.com/api/api-reference/account-and-admin/subscription-and-entitlements#get-v1-licenseentitlementusage), [`GET /v1/historicalMonthlyUsage`](https://developer.celigo.com/api/api-reference/account-and-admin/subscription-and-entitlements#get-v1-historicalmonthlyusage), plus the label-printing, per-environment storage, and syncs usage endpoints.

***

## `celigo subscriptions entitlement-usage`

Return entitlement usage for the account, keyed by usage category — flows enabled, endpoints consumed, agents active, trading partners consumed, and environments enabled on multi-environment licenses.

**Signature**

```bash
celigo subscriptions entitlement-usage
```

**Arguments**

None.

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
# How close is the account to its flow allocation?
celigo subscriptions entitlement-usage --format json \
  | jq '{flows: .flowUsage.numEnabled, endpoints: .endpointUsage.numConsumed, agents: .agentUsage.numActive}'
```

**Corresponds to**: [`GET /v1/licenseEntitlementUsage`](https://developer.celigo.com/api/api-reference/account-and-admin/subscription-and-entitlements#get-v1-licenseentitlementusage)

***

## `celigo subscriptions historical-usage`

Return historical monthly entitlement usage — intended for flow-run pricing models (primarily platform licenses). Useful for month-by-month trend analysis against allocation.

**Signature**

```bash
celigo subscriptions historical-usage
```

**Arguments**

None.

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
# Usage trend for the trailing year
celigo subscriptions historical-usage --format json | jq '.[] | {month, flowRuns, allocation}'
```

**Corresponds to**: [`GET /v1/historicalMonthlyUsage`](https://developer.celigo.com/api/api-reference/account-and-admin/subscription-and-entitlements#get-v1-historicalmonthlyusage)

***

## `celigo subscriptions api-usage`

Return API-call usage detail for the account.

**Signature**

```bash
celigo subscriptions api-usage
```

**Arguments**

None.

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo subscriptions api-usage --format table
```

**Corresponds to**: [`GET /v1/apis/usage`](https://developer.celigo.com/api/api-reference/api-management/apis#get-v1-apis-usage)

***

## Gotchas

1. **Read-only surface.** Every subcommand here is a `GET`. There's no CLI path to upgrade a license or change an entitlement — license upgrades route through the Celigo sales team (the underlying `/api/licenses/upgradeRequest` endpoint is session-auth only and returns `404 Not Found` to bearer PATs).
2. **`usage` combines every surface since celigo-cli 2026.8.7.** It fans out to all seven usage endpoints and returns one keyed object; the other subcommands remain for reading a single surface. Scripts that parsed the old bare `/v1/usage` array should pipe `--jq .usage`. A missing license shows up as an inline `{"error": ...}` entry, not a failure.
3. **`entitlement-usage` is keyed by usage category, not by environment.** The response is shaped `{ flowUsage: {...}, endpointUsage: {...}, agentUsage: {...}, environmentUsage: {...}, … }`. If you're piping to `jq`, target the category key you want. Per-environment counts live under `environmentUsage.environments`.
4. **No pagination, no filters.** These endpoints return the full account snapshot in one shot. There are no `--limit`, `--start-date`, or `--status` flags — if you need a windowed view, slice the JSON yourself.
5. **Not the same as `notifications`.** `subscriptions` is account licensing; `notifications` is per-user email subscription to integration/flow/connection events. Despite the overlapping word, they're unrelated surfaces.

## Related

* [notifications](/cli/commands/notifications.md) — per-user notification subscriptions (integrations, flows, connections).
* [account](/cli/commands/account.md) — account-wide operations (snapshot, search, stats) that pair well with usage data.
* [jobs](/cli/commands/jobs.md) — flow-run volume visible through `jobs list` correlates with `historical-usage` usage trends.