> 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/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/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/subscription-and-entitlements), [`GET /v1/apis/usage`](https://developer.celigo.com/api/api-reference/apis), [`GET /v1/licenseEntitlementUsage`](https://developer.celigo.com/api/api-reference/subscription-and-entitlements#get-v1-licenseentitlementusage), [`GET /v1/historicalMonthlyUsage`](https://developer.celigo.com/api/api-reference/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/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/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/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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/subscriptions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.