Upgrading to cf CLI v7

New workflows supported by cf CLI v7
Installing cf CLI v7
- Prerequisites
Command differences

Page last updated:

The main goal of Cloud Foundry CLI (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 below. These workflows were previously limited by CAPI V2.

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 below.

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

New workflows supported by cf CLI v7

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

Some key new features available with the cf CLI v7 are:

Rolling App Deployments: Push updates to apps without incurring downtime.
Running cf push Sub-Step Commands: Exercise granular control over the cf push process. These commands break down the cf push process into sub steps that can run independently.
Pushing an App with Multiple Processes: Use a single command to push apps that run multiple processes. An example is a web app that has a UI process and a worker process.
Pushing Apps with Sidecar Processes: Run additional processes in the same container as your app.
Using Metadata: Add metadata to objects, for example, spaces, and apps. This helps with operating, monitoring, and auditing.

Installing cf CLI v7

To install cf CLI v7, 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.

Prerequisites

The cf CLI v7 requires cf-deployment v13.5.0 or later.

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

For more information, see the CAPI release notes and the Cloud Controller release notes on GitHub.

If you target an later version of cf-deployment, cf CLI v7 presents a warning saying that the API version is less than the minimum supported. Not all commands run correctly. For example, cf apps does not work.

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.

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

About scripting

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

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 no longer wraps errors it receives from the API.
cf CLI v7 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.

Caution If the services attribute is declared at the top-level of the manifest.yml file, cf CLI v6 generates a warning, but in cf CLI v7, there is no warning and the app is still pushed.

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, for example, a space. Commands like 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 following table summarizes how commands differ between cf CLI v7 and cf CLI v6.

Command	Changes
`cf add-network-policy`	[Removed flag]: The flag `--destination-app` is deprecated. Instead, the destination app is the required second argument, using no flag.
`cf 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.
`cf bind-security-group`	[Update]: `SPACE` is no longer an argument. To provide a space, use the `--space` flag.
`cf check-route`	[Update]: `HOST` is no longer a required argument. [Update]: No longer requires a backslash. [Added flag]: Use `--hostname` to specify a hostname.
`cf create-buildpack`	[Removed flag]: `--enable`. Creating a buildpack activates it by default. [Removed flag]: `--disable`. You can not deactivate a buildpack upon creation. [Update]: Creating a buildpack with position set to `0` is no longer valid.
`cf create-domain`	[Renamed]: This command is renamed to `create-private-domain`.
`cf create-org`	[Update]: `clients.read` scope (or `clients.admin`, or `zones.uaa.admin`) is now required when logged in using client credentials.
`cf create-quota`	[Renamed]: This command is renamed to `create-org-quota`.
`cf create-space`	[Update]: `clients.read` scope (or `clients.admin`, or `zones.uaa.admin`) is now required when logged in using client credentials.
`cf create-route`	[Update]: `SPACE` is no longer a required argument. The command creates a route in the space you are targeting. [Removed flag]: `--random-port`. This is now default behavior for routes with TCP domains if the `--port` flag is not provided.
`cf create-service-auth-token`	This command is removed.
`cf create-service-broker`	[Update]: If the command does not successfully complete all phases, a service broker object exists, which can then be updated or deleted.
`cf create-user`	[Added flag]: `--password-prompt`. This option enhances security by removing the requirement to type your password on the command line.
`cf delete`	[Change in flag behavior]: `-r` no longer deletes routes when the route is mapped to more than one app.
`cf delete-domain`	[Renamed]: This command is renamed to `delete-private-domain`.
`cf delete-org`	[Update]: The command fails if the org contains shared private domains.
`cf delete-quota`	[Renamed]: This command is renamed to `delete-org-quota`.
`cf delete-service-auth-token`	This command is removed.
`cf domains`	[Update]: The `status` column is renamed to `availability`. [Update]: The table refers to private domains with `private` instead of `own`.
`cf files`	This command is removed.
`cf map-route`	[Removed flag]: `--random-port`. In the cf CLI v7, when you map a TCP route to an app, a random port is assigned to the route by default. To specify a port for a TCP route, use the `--port` flag.
`cf marketplace`	[Renamed flag]: The `-s` flag is renamed to `-e` for consistency with other commands. [Update]: When the `-e` flag is specified, plan costs advertised by the service broker are displayed. [Update]: When the `-e` flag is specified, and no service offering with that name is found, the exit code returned is 0. This is in contrast to the cf CLI v6, which returned exit code 1 in this case.
`cf migrate-service-instances`	This command is removed.
`cf packages`	[Update]: Displays packages from most recent to least recent.
`cf push`	[Removed flag]: `--route-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.
`cf purge-service-offering`	[Removed flag]: The `-p` flag is removed.
`cf quota`	[Renamed]: This command is renamed to `org-quota`.
`cf quotas`	[Renamed]: This command is renamed to `org-quotas`.
`cf remove-network-policy`	[Removed flag]: The flag `--destination-app` is deprecated. Instead, the destination app is the required second argument, using no flag.
`cf rename-buildpack`	This command is removed. Instead, use `--rename` flag with `cf update-buildpack`.
`cf restart-app-instance`	[Added Flag]: `--process`
`cf routes`	[Updated output]: `port`, `type`, and `service` no longer appear in the table. [Renamed flag]: `--orglevel` is now `--org-level`.
`cf run-task`	[Updated]: `COMMAND` is no longer an argument. To specify a command, use the `--command` flag. [Added Flag]: `--process`
`cf scale`	[Added flag]: `--process`
`cf service-access`	[Update]: When a service offering comes from a space-scoped service broker, the space and org are displayed.
`cf service-auth-tokens`	This command is removed.
`cf set-health-check`	[Added flag]: `--process` [Added flag]: `--invocation-timeout`
`cf set-quota`	[Renamed]: This command is renamed to `set-org-quota`.
`cf set-running-environment-variable-group`	[Update]: System environment variables can only be strings. This is enforced on the API.
`cf set-staging-environment-variable-group`	[Update]: System environment variables can only be strings. This is enforced on the API.
`cf ssh`	[Added flag]: `--process` [Added environment variable]: `all_proxy`. Specifies a proxy server for all requests.
`cf 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.
`cf unshare-private-domain`	[Update]: This command now provides a warning and requires confirmation before it proceeds.
`cf update-buildpack`	[Added flag]: `--rename` [Change in flag behavior]: `--unlock` and `--path` are now compatible.
`cf update-quota`	[Renamed]: This command is renamed to `update-org-quota`.
`cf update-service-auth-token`	This command is removed.
`cf v3-COMMAND`	[Update]: `v3` prefixes have been removed, since the commands now use CAPI V3 by default.
`cf apply-manifest`	[Update]: If no flags are passed, the command defaults to using the manifest located in your `pwd`.
`cf v3-cancel-zdt-push`	This command is removed. Instead, use `cf cancel-deployment`.
`cf v3-zdt-push`	This command is removed. Instead, use `--strategy rolling` flag with `cf push`.
`cf buildpacks`	The order of the columns are changed. The buildpack column header is renamed.

View the source for this page in GitHub