<a id="cli-migrate"></a>

# Update to Confluent CLI v4

The release of Confluent CLI v4 introduces a number of [breaking
changes](#cli-breaking-changes-v4) aimed at providing a better user experience.
Note that accommodating these breaking changes might require updating your
existing scripts. If you have any questions or comments, send your feedback
directly to the CLI team using the `confluent feedback` command.

This page includes the following:

- [Breaking changes for Confluent CLI](#cli-breaking-changes-v4)
- [How to Update to Confluent CLI v4](#migrate-cli-v4)
- [FAQ](#migrate-cli-v4-faqs)

<!-- Save for later
.. important::

   In line with Confluent's major upgrades policy, ``confluent`` v3 is now
   marked as deprecated. Because official support for ``confluent`` v3 has
   ended, Confluent recommends you :ref:`update to Confluent CLI v4
   <migrate-cli-v4>`. -->

<a id="cli-breaking-changes-v4"></a>

## Breaking changes for Confluent CLI

Confluent CLI v4 includes several changes that break the syntax or output structure of the previous major release.
For a complete list of Confluent CLI v4 breaking changes, see [Confluent CLI v4.0.0 Release Notes](release-notes.md#cli-release-notes-v4).

<a id="migrate-cli-v4"></a>

## How to Update to Confluent CLI v4

This topic describes how to update the Confluent CLI on macOS, Linux, Windows, or with the
legacy command if you are not using a package manager. (If you are installing the Confluent CLI
client for the first time, see [Install Confluent CLI](install.md#cli-install).)

### Homebrew

macOS and Linux users can update to the latest version of the Confluent CLI using
the following [Homebrew](https://brew.sh/) commands:

```text
brew update && brew upgrade confluentinc/tap/cli
```

### APT

If you installed the Confluent CLI using the APT package manager,
you can upgrade to Confluent CLI v4 by running the following commands:

1. Update `apt`:
   ```bash
   sudo apt update
   ```
2. Install the Confluent CLI:
   ```bash
   sudo apt install confluent-cli
   ```

### YUM

If you installed the Confluent CLI using the YUM package manager,
you can upgrade to Confluent CLI v4 by running the following commands:

1. Clear the YUM caches:
   ```bash
   sudo yum clean all
   ```
2. Upgrade the Confluent CLI:
   ```bash
   sudo yum upgrade confluent-cli
   ```

### Windows

Installing using the Windows native installer is not yet available.
On Windows, you can upgrade to the Confluent CLI v4 by running the following command:

```text
confluent update --major
```

### Legacy

If you installed the Confluent CLI using the legacy commands rather than a package manager,
you can upgrade to Confluent CLI v4 by running the following command:

```text
confluent update --major
```

For the complete syntax of this command, see [confluent update](command-reference/confluent_update.md#confluent-update).

<a id="migrate-cli-v4-faqs"></a>

## FAQ

### Why should I upgrade my Confluent CLI to the latest version, v4?

As detailed in the Release Notes, several commands and flags have been renamed or modified
for v4 to provide better functionality and map to feature updates. In particular, the Schema Registry commands
are now aligned with [Always On Stream Governance](/cloud/current/stream-governance/packages.html#getting-started-enable-or-upgrade).
To learn more, see [Deprecation of SRCM v2 clusters and regions APIs and upgrade guide](/cloud/current/stream-governance/packages.html#upgrade-to-srcm-v3-clusters-and-regions-apis-deprecation-of-srcm-v2).

In practice, this means that users no longer explicitly create and secure Schema Registry clusters; in fact, these clusters cannot be created manually with the new CLI commands and backing APIs.
The Schema Registry cluster is now auto-created in the environment when the first Kafka cluster is created, and in the same region as the Kafka cluster.
Stream Governance and Schema Registry is always enabled in Confluent Cloud environments; you have the choice of keeping with the default “Essentials” package or upgrading to “Advanced”.
Therefore, the set of `confluent schema-registry cluster` commands have been streamlined to describe existing clusters,
while package upgrades are available on `confluent environment` commands:

```bash
confluent environment update <id> --governance-package advanced
```

Keep in mind that once you upgrade a package associated with an environment, you cannot “downgrade” back to “Essentials”:

```bash
Downgrading the package from "advanced" to "essentials" is not allowed once the Schema Registry cluster is provisioned.
```

Several new commands have been added to support working with Kafka topics and plugins.

### How can I determine if this version change affects me?

The most critical updates are related to the Schema Registry commands for Confluent Cloud customers, as detailed in the other FAQs.
You must update to Confluent CLI v4 by February 2025, per the information detailed in the
[Deprecation of SRCM v2 clusters and regions APIs and upgrade guide](/cloud/current/stream-governance/packages.html#upgrade-to-srcm-v3-clusters-and-regions-apis-deprecation-of-srcm-v2).

This does not apply to Confluent Platform.

### How much time do I have to upgrade from an earlier version to Confluent CLI v4?

You must upgrade when the version you are using is no longer supported.
It is recommended to upgrade to the latest version, Confluent CLI v4.

- Confluent CLI v1 is deprecated and not supported.
- Confluent CLI v2 will be deprecated in November 2024, and will be removed in November 2025 (after 1 year).
- Confluent CLI v3 is still supported, but will no longer support the Schema Registry cluster `enable` commands after February 2025, as described below.

Per the information in [Deprecation of SRCM v2 clusters and regions APIs and upgrade guide](/cloud/current/stream-governance/packages.html#upgrade-to-srcm-v3-clusters-and-regions-apis-deprecation-of-srcm-v2)
in the [Stream Governance packages topics](/cloud/current/stream-governance/packages.html) documentation,
support for the SRCM v2 regions API will end in February 2025. Therefore, Confluent Cloud users should update
to the associated Confluent CLI v4 before this sunset date for the related APIs.

This does not apply to Confluent Platform.

### How can I test the v4 changes in Confluent CLI?

After upgrade, run some of the commands listed as updated in the Release Notes,
and view the help output.

Running `confluent help` at the top level or for a subcommand should reflect the updates shown in the [Confluent CLI v4.0.0 Release Notes](release-notes.md#cli-release-notes-v4).

### Where are the Release Notes?

Confluent CLI v4 includes several changes that break the syntax or output structure of the previous major release.
For a complete list of Confluent CLI v4 breaking changes, see [Confluent CLI v4.0.0 Release Notes](release-notes.md#cli-release-notes-v4).

### Is Confluent CLI v3 deprecated?

Currently, Confluent CLI v1 is deprecated, and v2 will be deprecated as of November 2024.

Confluent CLI v3 is still supported, and v4 is the most recent version.

Confluent CLI v3 will no longer support the Schema Registry cluster `enable` commands after February 2025, as the corresponding backend APIs will no longer be supported. To learn more, see
[Deprecation of SRCM v2 clusters and regions APIs and upgrade guide](/cloud/current/stream-governance/packages.html#upgrade-to-srcm-v3-clusters-and-regions-apis-deprecation-of-srcm-v2).