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.

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.

The following list provides an overview of key new features available through the cf7 CLI beta:

Install cf CLI v7

To install cf CLI v7 beta, see the README in the cloudfoundry/cli GitHub repository. It includes instructions for downloading the latest CAPI release candidate, which is what the cf CLI v7 beta is tested against.

Command Differences

The following sections provide details about changes in commands from v6 to v7 and some information for those who use the cf CLI in scripts.

To view full release notes for cf CLI v7, see V7 Beta Release and the official release page in the cf CLI GitHub repository.

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 discusses possible changes in cf7 which might affect scripts. Also see the Table of Differences to be aware of possible breaking changes. These include removed flag options, removed commands, and removed or changed argument requirements.

See the following list of additional changes that may affect scripting, introduced as early as December 2016 as part of the ongoing effort to refactor the cf CLI:

  • If your scripts parse error text, it is important to note that in cf7, 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 the Colors section of the CF CLI Style Guide on GitHub.

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

  • Single quote resource names in error cases.

Exit Codes

cf7 attempts to consistently apply the principles of idempotency across all commands which require it. See our style guide for more information. 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 space (or any resource) which doesn’t exist. Commands like delete-route, delete-space, etc now return 0 in those cases. - we’ve made updates to create-buildpack whereby if the buildpack is not created, the command exits with 1 instead of 0, which is the current cf6 behavior.

Table of Differences

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

Command Changes
cf7 apps
  • [Update]: Displays information about processes.
  • [Update]: url field renamed to routes.
  • [Update]: Removes information about instances, memory, and disk.
  • [Update]: Apps 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 zero is no longer valid.
cf7 create-domain
  • [Renamed]: This command is renamed to cf create-private-domain.
  • [Update]: No longer supports router groups and TCP routing 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 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 Removed command because the V1 Broker API was deprecated as of January 2015.
cf7 create-shared-domain
  • [Removed flag]: --router-group. This removes support for TCP routing removed in favor of different functionality currently being explored by the Networking team.
cf7 create-user
  • [Added flag]: --password-prompt. This option provides more security because users do not have to type their 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]: No longer supports router groups and TCP routing 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 Removed command because the V1 Broker API was deprecated as of January 2015.
cf7 domains
  • [Update]: status column renamed to availability.
  • [Update]: Table refers to private domains with private instead of own.
  • [Update]: Removed type column since support for TCP Routing has been removed.
cf files Removed command because the V1 Broker API was 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 down time 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 of 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 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 Removed command because the V1 Broker API was deprecated as of January 2015.
cf7 restart-app-instance
  • [Added Flag]: --process.
cf7 rename-buildpack Removed command. 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 Removed command because the V1 Broker API was 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 now 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 now on the API.
cf7 start
  • [Update]: Stages an app again to support cf push app --no-start use cases. If there is a new package, start will stage and start with the new package. If the app has been rolled back, start will start with the droplet you used to roll back your app. In the case of a droplet that’s in a FAILED state, V7 start will ignore the failed droplet and restage the latest READY package to try to produce a healthy droplet. In V6, start will fail.
cf7 unshare-private-domain
  • [Update]: The 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 Removed command because the V1 Broker API was deprecated as of January 2015.
cf7 v3-COMMAND
  • [Update]: v3 prefixes have been removed as 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
  • Removed command. Instead, use cf cancel-deployment.
cf7 v3-zdt-push
  • Removed command. Instead, use --strategy rolling flag with cf push
Create a pull request or raise an issue on the source for this page in GitHub