Using Experimental cf CLI Commands

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.4 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

Page last updated:

This topic describes how to use the experimental Cloud Foundry Command Line Interface (cf CLI) commands offered by the Cloud Controller V3 API.

These commands provide developers with the ability to better orchestrate app deployment workflows. New features include the deployment and management of apps with multiple processes and uploading and staging multiple versions of a single app.

The experimental commands described in this topic require Pivotal Cloud Foundry (PCF) 1.12+ and the cf CLI v6.30.0+.

For more information about cf CLI commands, see the Cloud Foundry CLI Reference Guide. For more information about the Cloud Controller V3 API, see the API documentation.

Note: Because these commands are experimental, they are not guaranteed to be available or compatible in subsequent cf CLI releases.

Overview

The new commands include a v3- prefix. While the syntax of some experimental commands is based on the existing cf CLI, these commands call the V3 API and support new flags to unlock additional features. Other commands expose the new primitives of apps, such as by performing operations on an app’s packages and droplets.

In the V2 APIs, running and staging an app are tightly coupled operations. As a result, an app cannot be staging and running at the same time. The V3 APIs offer developers more granular control over the uploading, staging, and running of an app.

Commands

Consult the following table for a description of the experimental commands.

Command Description
v3-apply-manifest Applies manifest properties to an app
v3-apps Lists all apps in the target space
v3-create-app Creates a V3 app
v3-create-package Uploads a V3 package
v3-delete Deletes a V3 app
v3-droplets Lists droplets of an app
v3-env Shows all environment variables for an app
v3-get-health-check Shows the type of health check performed on an app
v3-packages Lists packages of an app
v3-push Pushes a new app or syncs changes to an existing app
v3-restart Stops all instances of an app and then starts them again, which may cause downtime
v3-restart-app-instance Terminates and then instantiates an app instance
v3-set-droplet Sets the droplet used to run an app
v3-set-env Sets an environment variable for an app
v3-set-health-check Changes type of health check performed on an app’s process
v3-ssh SSH to an app container instance
v3-stage Creates a new droplet for an app
v3-start Starts an app
v3-stop Stops an app
v3-unset-env Removes an environment variable from an app

Considerations

Keep in mind the following considerations when using the experimental commands:

  • v3-push supports only a subset of features of push. In particular, it does not support app manifests.
  • For some commands, such as set-env, ssh, and bind-service, no new V3 version exists. In those cases, use the old commands.
  • You can use V3 and old commands together, but some combinations may give unexpected results. For example, if you use V3 commands to create an app with a package but it is not staged, or you use v3-push to push an app but it fails to stage, the old apps command does not return the app.

Declaring Multiple App Processes with a Procfile

Developers can supply a Procfile with their app in order to run multiple long-lived processes using a single codebase.

To use a Procfile, include it in the root of your app directory and push your app.

For more information about Procfiles, see the About Procfiles section of the Production Server Configuration topic.