> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI version support and deprecation policy

> Learn about HubSpot CLI versioning and guidance on upgrading.

This policy defines the lifecycle of the HubSpot CLI versions to provide developers and organizations with a predictable schedule for updates, maintenance, and migrations. The goal of this policy is to balance new feature development with the stability required for production CI/CD pipelines.

## Versioning scheme and schedule

The HubSpot CLI uses semantic versioning:

`{MAJOR}.{MINOR}.{PATCH}`

* **MAJOR:** Changes that require user action (e.g., removed or renamed commands, incompatible output changes)
* **MINOR:** Backward-compatible functionality additions
* **PATCH:** Backward-compatible bug fixes and performance improvements

This versioning scheme comes with a compatibility guarantee: HubSpot will not intentionally introduce breaking changes in **MINOR** or **PATCH** releases. Breaking changes are reserved for **MAJOR** releases and are communicated clearly ahead of time.

### Pre-releases

Pre-releases are primarily intended for early adopters and contributors who want to help validate changes.  Pre-releases will only be released on [unstable release channels](#release-channels) (e.g., `next`).

Pre-release versions follow the formats below:

* **Alpha releases:** `X.Y.Z-alpha.N`
* **Beta releases:** `X.Y.Z-beta.N`

Pre-releases do <u>not</u> come with the same compatibility guarantee as the full release versions detailed above: APIs and behaviors may change while using a pre-released version. Pre-releases are never installed by default, and are instead explicitly opt-in.

### Support lifecycle tiers

Every major version of the CLI progresses through the following four stages:

| Stage | Description | Maintenance Level |
| - | - | - |
| Active | The current stable major version. | New features, bug fixes, and security updates. |
| Maintenance | The previous major version (N-1) after a new major release. | Critical bug fixes and security updates only. No new features |
| Deprecated | Version nearing the end of its life. | No updates except for special occasions. Use at your own risk; compatibility not guaranteed. |
| End of Life (EOL) | Version no longer supported. | No updates. Use at your own risk; compatibility not guaranteed. |

### The 12-month support window

When a new **major version (N)** is released, the previous **major version (N-1)** immediately enters a 12-month sunset period:

**Months 0–3 (Maintenance Phase):** Version N-1 remains fully supported for critical bugs. Developers are encouraged to begin testing Version N.\
**Months 4–12 (Deprecation Phase):** Version N-1 will trigger a "Loud Deprecation" warning on stderr. This warning will include the final EOL date and a link to the migration guide.\
**Month 12+ (End of Life):** Official support for Version N-1 ceases. The version may remain available via package managers (npm, brew, etc.) but is considered unsupported.

### Release channels

Release channels provide a convenient way to install a class of releases without pinning an exact version.

| Channel | Stable | Description | Intended audience |
| - | - | - | - |
| `latest` | yes | Latest generally available release | Default for all users |
| `next` | no | Latest beta pre-release | Early adopters and testers |
| `previous` | no | Used for support of the previous major version.  Not intended for long term usage. | Users who do not wish to update the current major version |

Channels resolve to a specific version that rotates as releases happen and is not a replacement for semantic versioning. Using release channels is useful for developers to always get a compatible version automatically and ease maintenance burden, and is not intended for automation or agents.

## Communication and notifications

Users will be notified of new releases and version deprecations via the [HubSpot Developer Changelog](https://developers.hubspot.com/changelog).

Deprecation warnings will also be displayed directly in your terminal if you're running an older version or executing a deprecating command.

* All deprecation notices will be issued via stderr to ensure they do not break scripts that parse stdout (e.g., JSON or CSV pipes).
* Warnings will include the deprecation target (i.e., the specific command, flag, or version being retired), an alternative option, a timeline for the deprecation, along with an external resource where you can learn more.

For example, the CLI will output a message that resembles the following when a deprecated version or command is detected:

```
(!!) DEPRECATION WARNING:
Version: HubSpot CLI v7.x
Status: Maintenance Mode (End of Life: December 31, 2026)
Action Required: Upgrade to v8.x to continue receiving new features
Replacement: Run npm install -g @hubspot/cli@latest to upgrade.
Documentation: https://docs.example.com/migration-v2
```

## Security vulnerabilities

Security is HubSpot's highest priority. Critical security patches, for issues typically scoring 9+ on the [CVSS scale](https://www.first.org/cvss/), may be backported to Deprecated versions at the sole discretion of the engineering team, though users should not rely on this as a standard practice.