Upgrading to cf CLI v7 (Beta)

This topic describes the major changes between Cloud Foundry Command Line Interface (cf CLI) v6 and cf CLI v7.

Overview

The cf CLI v7 beta is in active development to convert commands to call the Cloud Foundry API (CAPI) v3 instead of CAPI v2.

The main goal of cf CLI v7 and CAPI v3 is to unlock new app developer workflows for users who require granular control of their apps and other advanced deployment strategies. For more information, see New Workflows Supported. These workflows were previously limited by CAPI v2.

Both cf CLI v7 beta and CAPI v3 are in active development. cf CLI v7 beta is subject to change as development continues. However, the cf CLI development team aims to provide:

  • A seamless upgrade experience from cf CLI v6. Changes have been kept to a minimum. Where there are changes, the team has incorporated feedback from the community to simplify the cf CLI user experience.

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

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

For more information about CAPI v3, see the CAPI v3 documentation. For more information about CAPI v2, see the CAPI v2 documentation.

Note: The cf CLI v7 beta is developed and tested against the latest CAPI release candidate.

Note: Since the cf CLI v7 is in beta, not all commands use CAPI v3. Some commands still use CAPI v2.

New Workflows Supported by cf CLI v7

cf CLI v7 uses CAPI v3, which offers developers more granular control over their apps. It enables new workflows by exposing packages, droplets, builds, and processes. CAPI v3 also includes new resources such as sidecars, manifests, deployments.

Some key new features available through the cf CLI v7 beta are:

Install cf CLI v7

To install cf CLI v7 beta, 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 v7 beta is tested against.

Command Differences

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

To view the release notes for cf CLI v7, see V7 Beta Release and Releases in the Cloud Foundry CLI repository on GitHub.

Note: cf CLI v7 beta still calls CAPI v2 for some commands while development is ongoing. The changes mentioned in this section reflect v3-backed cf CLI v7 commands.

About Scripting

If you have scripts that rely on the cf CLI, this section describes possible changes in cf7 which might affect scripts. For information about possible breaking changes, see Table of Differences. This table includes removed flag options, removed commands, and removed or changed argument requirements.

For information about additional changes that may affect scripting, see the v6.230 release notes in the Cloud Foundry CLI repository on GitHub. Some of these changes are:

  • In cf CLI v7, if your scripts parse error text, output text errors are returned directly from CAPI. Where possible, cf CLI v7 beta no longer wraps errors it receives from the API.

  • cf CLI v7 beta commands output errors and warnings to stderr rather than stdout to simplify debugging.

  • Style changes including flavor text updates. For more information, see Colors in CF CLI Style Guide in the Cloud Foundry CLI repository on GitHub.

  • Key-value and table column headers are displayed in lowercase.

  • Single-quote resource names appear in error cases.

Exit Codes

cf CLI v7 attempts to consistently apply the principles of idempotency across all commands which require it. For more information, see General Principles in CF CLI Style Guide in the Cloud Foundry CLI repository on GitHub. Commands now exit 0 if the outcome a user expresses when running a specific command is unchanged after the command is executed. Examples include:

  • Attempting to delete a resource which does not exist, such as a space. Commands such as delete-route and delete-space return 0 in those cases.

  • If the create-buildpack command fails to create a buildpack, the command exits with 1 instead of 0, which is the current cf CLI v6 behavior.

Table of Differences

The table below summarizes how commands differ between cf CLI v7 and cf CLI v6.

Command Changes
cf7 apps
  • [Update]: Displays information about processes.
  • [Update]: The url field is renamed to routes.
  • [Update]: Information about instances, memory, and disk is removed.
  • [Update]: Apps are listed alphabetically.
cf7 check-route
  • [Update]: HOST is no longer a required argument.
  • [Update]: No longer requires a backslash.
  • [Added flag]: Use --hostname to specify a hostname.
cf7 create-buildpack
  • [Removed flag]: --enable. Creating a buildpack enables it by default.
  • [Removed flag]: --disable. There is no way to disable a buildpack upon creation.
  • [Update]: Creating a buildpack with position set to `0` is no longer valid.
cf7 create-domain
  • [Renamed]: This command is renamed to cf create-private-domain.
  • [Update]: Support for router groups and TCP routing is removed in favor of different functionality currently being explored by the Networking team.
cf7 create-route
  • [Update]: SPACE is no longer a required argument. The command creates a route in the space you are targeting.
  • [Update]: Support for TCP routing is removed in favor of different functionality currently being explored by the Networking team.
  • [Removed flag]: --random-port
  • [Removed flag]: port
cf7 create-service-auth-token This command is removed because the V1 Broker API is deprecated as of January 2015.
cf7 create-shared-domain
  • [Removed flag]: --router-group. Support for TCP routing is removed in favor of different functionality currently being explored by the Networking team.
cf7 create-user
  • [Added flag]: --password-prompt. This option enhances security by removing the requirement to type your password on the command line.
cf7 delete
  • [Change in flag behavior]: -r no longer deletes routes when the route is mapped to more than one app.
cf7 delete-domain
  • [Renamed]: This command is renamed to cf delete-private-domain.
  • [Update]: Support for router groups and TCP routing is removed in favor of different functionality currently being explored by the Networking team.
cf7 delete-org
  • [Update]: The command fails if the org contains shared private domains.
cf7 delete-service-auth-token This command is removed because the V1 Broker API is deprecated as of January 2015.
cf7 domains
  • [Update]: The status column is renamed to availability.
  • [Update]: The table refers to private domains with private instead of own.
  • [Update]: The type column is removed, since support for TCP routing is removed.
cf files This command is removed because the V1 Broker API is deprecated as of January 2015.
cf7 packages
  • [Update]: Displays packages from most recent to least recent.
cf7 push
  • [Removed flag]: --routh-path. You can use the routes property in the manifest instead.
  • [Removed flag]: -d for domain. You can use the routes property in the manifest instead.
  • [Removed flag]: --no-hostname. You can use the routes property in the manifest instead.
  • [Removed flag]: --hostname. You can use the routes property in the manifest instead.
  • [Added flag]: --strategy. You can deploy an app without causing downtime using cf push app_name --strategy rolling. Exits when at least one instance of each process is healthy.
  • [Added flag]: --no-wait. When used, the command exits when the one instance one process becomes healthy.
  • [Added flag]: --endpoint. Required if you set health check type to http when pushing an app.
  • [Updated flag]: --health-check-type none is removed in favor of --health-check-type process.
  • [Updated flag]: --no-route no longer unbinds all existing routes associated with the app.
  • [Updated flag]: -t now has a long form --app-start-timeout. All short-form flags now have long-form equivalents.
cf7 migrate-services-instances This command is removed because the V1 Broker API is deprecated as of January 2015.
cf7 restart-app-instance
  • [Added Flag]: --process
cf7 rename-buildpack This command is removed. Instead, use --rename flag with cf update-buildpack.
cf7 routes
  • [Updated output]: port and type no longer appear in the table.
cf7 scale
  • [Added flag]: --process
cf7 service-auth-tokens This command is removed because the V1 Broker API is deprecated as of January 2015.
cf7 set-health-check
  • [Added flag]: --process
  • [Added flag]: --invocation-timeout
cf7 set-running-environment-variable-group
  • [Update]: System environment variables can only be strings. This is enforced on the API.
cf7 ssh
  • [Added flag]: --process
  • [Added environment variable]: all_proxy. Specifies a proxy server for all requests.
cf7 set-staging-environment-variable-group
  • [Update]: System environment variables can only be strings. This is enforced on the API.
cf7 start
  • [Update]: Stages an app to support cf push app --no-start use cases. If there is a new package, start stages and starts using the new package. If the app has been rolled back, start starts using the droplet you used to roll back your app. In the case of a droplet that is in a FAILED state, start ignores the failed droplet and restages the latest READY package to try to produce a healthy droplet. In cf CLI v6, start fails if the droplet is in a FAILED state.
cf7 unshare-private-domain
  • [Update]: This command now provides a warning and requires confirmation before it proceeds.
cf7 update-buildpack
  • [Added flag]: --rename
  • [Change in flag behavior]: --unlock and --path are now compatible.
cf7 update-service-auth-token This command is removed because the V1 Broker API is deprecated as of January 2015.
cf7 v3-COMMAND
  • [Update]: v3 prefixes have been removed, since the commands now use CAPI v3 by default.
cf7 apply-manifest
  • [Update]: If no flags are passed, the command defaults to using the manifest located in your pwd.
cf7 v3-cancel-zdt-push
  • This command is removed. Instead, use cf cancel-deployment.
cf7 v3-zdt-push
  • This command is removed. Instead, use --strategy rolling flag with cf push.
View the source for this page in GitHub