Upgrading to cf CLI v8

You can use Cloud Foundry Command Line Interface (cf CLI) v8 to interact with Cloud Foundry API (CAPI) V3. This topic describes the major changes between cf CLI v7 and cf CLI v8.

The cf CLI development team aims to provide:

• A seamless upgrade experience from cf CLI v7. Changes are minimal. Where there are changes, the team has incorporated feedback from the community to simplify the cf CLI user experience.

• Details about potential breaking changes and alternative workflows for scripting environments.

To understand the differences between specific commands, see Command differences below.

For more information about CAPI V3, see the CAPI V3 documentation.

For more information about cf CLI v8, see v8.0.0 in GitHub.

New workflows supported by cf CLI v8

Some key new features available through the cf CLI v8 are:

• Asynchronous service operations: All service-related operations are now asynchronous by default. This includes manipulating service keys and route bindings.

Install cf CLI v8

To install cf CLI v8, see the README in the Cloud Foundry CLI repository on GitHub. It includes instructions for downloading the latest CAPI release candidate, which is what the cf CLI v8 beta is tested against.

In cf CLI v8, Golang has been updated from v1.13 to v1.16. When targeting a foundation that does not have a SAN, you might encounter errors because the common name field is deprecated in Golang v1.15 and later. For more information, see X.509 CommonName deprecation in the Golang v1.15 release notes.

Prerequisites

The cf CLI v8 requires cf-deployment v16.11.0 or later.

This version of cf-deployment contains CAPI release v1.109.0, which provides the CAPI V3 API v3.99.0.

For more information, see the cf CLI Versioning and Support Policy on GitHub.

Command differences

These sections describe changes in commands from cf CLI v7 to cf CLI v8. They also provide important information for those who use the cf CLI in scripts.

For information about possible breaking changes, see the Table of differences below. This table includes removed flag options, updated output, and removed or changed argument requirements.

Manifest differences

When you apply a manifest by running cf push, cf CLI v8 does not provide a manifest diff through the V3 manifest diff endpoint. This new endpoint supports version 1 manifests only. For more information, see Create a manifest diff for a space (experimental) in the CAPI documentation.

About scripting

If you have scripts that rely on the cf CLI, this section describes possible changes in cf CLI v8 that might affect scripts.

Some of these changes are:

• Style changes, including changes in the order or wording of the output.
• cf CLI v8 uses CAPI V3 to make requests related to services. CAPI V3 creates asynchronous jobs. If you want to continue to create jobs synchronously, use the new --wait flag.
• JSON response changes such as additional elements or nesting, which may impact parsing in existing scripts.

Table of differences

The following table summarizes how commands differ between cf CLI v7 and cf CLI v8.

Command	Changes
cf bind-service	[Added flag]: Use --wait to wait for the bind operation to complete.
cf bind-route-service	[Update]: Bind route operation is async by default. [Added flag]: Use --wait to wait for the bind operation to complete.
cf create-service	[Added flag]: Use --wait to wait for the create operation to complete.
cf create-service-key	[Update]: Create operation is async by default. [Added flag]: Use --wait to wait for the create operation to complete.
cf delete-service	[Added flag]: Use --wait to wait for the delete operation to complete.
cf delete-service-key	[Update]: Delete operation is async by default. [Added flag]: Use --wait to wait for the delete operation to complete.
cf map-route	[Added flag]: Use --destination-protocol to use HTTP/2 protocol to communicate with apps. By default, if destination-protocol is not set, HTTP/1 protocol is used for HTTP route.
cf marketplace	[Added flag]: Use --show-unavailable to show plans that are not available for use.
cf route	[New]: New command for viewing details about a route and its destinations.
cf routes	[Update]: Added service instance column to output.
cf service	[Added flag]: Use --params to retrieve and display the given service instances's parameters as JSON. All other output is suppressed. [Update]: Displays information about guid, type, and broker tags. [Update]: The service field is renamed to offering. [Update]: The service broker field is renamed to broker. [Update]: The dashboard field is renamed to dashboard url. [Update]: Minor changes to the ordering and wording of each block of information.
cf service-key	[Update]: Displays information about last operation and message as new columns. [Response]: All JSON response elements from v7 are now wrapped into an additional element named credentials.
cf services	[Added flag]: Use --no-apps to not retrieve bound apps information. [Added flag]: Use --wait to wait for the operation to complete.
cf unbind-service	[Added flag]: Use --wait to wait for the unbind operation to complete.
cf unbind-route-service	[Update]: Unbind route operation is async by default. [Added flag]: Use --wait to wait for the unbind operation to complete.
cf update-service	[Added flag]: Use --wait to wait for the update operation to complete. [Removed flag]: --upgrade. Use new command cf upgrade-service to upgrade a plan.
cf upgrade-service	[Removed flag]: --force. There is no longer user interaction required on this command.