CLI version support and deprecation policy

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 (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 not 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. 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, 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.

​Versioning scheme and schedule

​Pre-releases

​Support lifecycle tiers

​The 12-month support window

​Release channels

​Communication and notifications

​Security vulnerabilities