push-sub-commands.html.md.erb

---
title: Running cf push Sub-Step Commands (Beta)
owner: CAPI
---

This topic describes how to run beta Cloud Foundry Command Line Interface (cf CLI) commands that provide granular control over the `cf push` process. These commands break down the `cf push` process into sub-steps that can run independently. 

<p class="note"><strong>Note</strong>: This is a beta feature. Because the CLI may change, this feature is not recommended for use in scripts until it is generally available.</p>

<div class="note">
<strong>Note:</strong>
This topic includes references to cf CLI v7 beta commands. Consider the following when using these commands:
<ul>
<li> cf CLI v7 beta and CAPI v3 are both in active development and subject to change. </li>
<li> cf CLI v7 beta is developed and tested against the latest CAPI release candidate. </li>
<li> cf CLI v7 beta does not yet use CAPI v3 for all commands. Some commands still use CAPI v2 during beta. </li>
</ul>
For more information, see <a href="../../cf-cli/v7.html">Upgrading to cf CLI v7 (Beta)</a>. 
</div>

## <a id="about"></a> Overview 

The cf CLI includes commands to provide granular control over app pushes. With these commands, you can choose to perform only some steps of the `cf push` process or perform specific actions between the steps normally executed as part of running `cf push`.

Here are some example use cases for the sub-step commands:

* Updating a third party system before staging an app
* Retrying failed stagings without incurring downtime
* Calling external services to report audit data during push 
* Scanning a droplet before deploy
* Integrating with a change request system

To support these custom push workflows, Cloud Foundry divides apps into smaller building blocks. The following table describes these building blocks as _Resources_ and lists the command associated with each one.  

For information on using these commands, see the [Example Workflows](#example-workflows) section below. 

<table>
	<tr>
		<th>Resource</th>
		<th>Description</th>
		<th style="width: 30%">Command</th>
	</tr>
	<tr>
		<td>App</td>
		<td>The top-level resource that represents an app and its configuration.<br>
		For more information, see <a href="https://v3-apidocs.cloudfoundry.org/index.html#apps">Apps</a> in the CAPI documentation.</td>
		<td>
		<ul>
			<li><strong>cf CLI v6</strong>: <br><code>cf v3-create-app</code></li>
			<li><strong>cf CLI v7</strong>: <br><code>cf7 create-app</code></li>
		</ul>
		</td>
	</tr>
	<tr>
		<td>Package</td>
		<td>The source code that makes up an app.<br>
		For more information, see <a href="https://v3-apidocs.cloudfoundry.org/index.html#packages">Packages</a> in the CAPI documentation.</td>
		<td><ul>
			<li><strong>cf CLI v6</strong>: <br><code>cf v3-create-package</code></li>
			<li><strong>cf CLI v7</strong>: <br><code>cf7 create-package</code></li>
		</ul></td>
	</tr>
	<tr>
		<td>Build</td>
		<td>The staging process. Creating a build combines a Package with a Buildpack and builds it into an executable resource.<br>
		For more information, see <a href="https://v3-apidocs.cloudfoundry.org/index.html#builds">Builds</a> in the CAPI documentation.</td>
		<td><ul>
			<li><strong>cf CLI v6</strong>: <br><code>cf v3-stage</code></li>
			<li><strong>cf CLI v7</strong>: <br><code>cf7 stage</code></li>
		</ul></td>
	</tr>
	<tr>
		<td>Droplet</td>
		<td>An executable resource that results from a Build.<br>
		For more information, see <a href="https://v3-apidocs.cloudfoundry.org/index.html#droplets">Droplet</a>  in the CAPI documentation.</td>
		<td><ul>
			<li><strong>cf CLI v6</strong>: <br><code>cf v3-set-droplet</code></li>
			<li><strong>cf CLI v7</strong>: <br><code>cf7 set-droplet</code></li>
		</ul></td>
	</tr>
	<tr>
		<td>Manifest</td>
		<td>A file used when pushing your app to apply bulk configuration to an app and its underlying processes..<br>
		For more information, see <a href="https://v3-apidocs.cloudfoundry.org/index.html#app-manifest">App Manifest</a> in the CAPI documentation.</td>
		<td><ul>
			<li><strong>cf CLI v6</strong>: <br><code>cf v3-create-manifest</code>, code>v3-apply-manifest</code></li>
			<li><strong>cf CLI v7</strong>: <br><code>cf7 create-manifest</code>, <code>apply-manifest</code></li>
		</ul></td>
	</tr>
</table>

## <a id="example-workflows"></a> Example Workflows

The following sections describe example workflows for working with the `cf push` sub-step commands. 

### <a id="update-system"></a> Push an App Using Sub-Step Commands

This example workflow describes how to push an app using sub-step commands instead of `cf push`.

1. Create your app with the cf CLI:
	* **cf CLI v7**: 

		```
		cf7 create-app MY-APP
		```
	* **cf CLI v6**: 

		```
		cf v3-create-app MY-APP
		```

1. From your app directory, create a package for your app. 
	* **cf CLI v7**:

		```
		cf7 create-package MY-APP
		```
	* **cf CLI v6**:

		```
		cf v3-create-package MY-APP
		```

1. Locate and copy the `package guid` from the output of the previous step. See the following example output:
	<pre class="terminal">
	Uploading and creating bits package for app MY-APP in org test / space test as admin...
	 package guid: 0dfca85a-8ed4-4f00-90d0-3ab08852dba8
	 OK
	</pre>

1. Stage the package you created:
	* **cf CLI v7**:

		```
		cf7 stage MY-APP --package-guid PACKAGE-GUID
		``` 
	* **cf CLI v6**:

		```
		cf v3-stage MY-APP --package-guid PACKAGE-GUID
		``` 

1. Locate and copy the `droplet guid` from the output of the previous step. See the following example output:
	<pre class="terminal">
	Staging package for MY-APP in org test / space test as admin...
	...
	Package staged
	 droplet guid: f60d3464-415a-4202-9d40-26a70373a487
	 state: staged
	 created: Mon 25 Sep 16:37:45 PDT 2018
	</pre>

1. Assign the droplet to your app: 
	* **cf CLI v7**:

		```
		cf7 set-droplet MY-APP -d DROPLET-GUID
		```
	* **cf CLI v6**:

		```
		cf v3-set-droplet MY-APP -d DROPLET-GUID
		```

1. Start your app:
	* **cf CLI v7**:

		```
		cf7 start MY-APP
		```
	* **cf CLI v6**:

		```
		cf v3-start MY-APP
		```

### <a id="update-system-example"></a> Roll Back to a Previous Droplet

This example workflow describes how to roll back to a previous droplet used by your app. You may want to use this, for example, if you update your app and it has a bug that causes it to crash. 

1. List the droplets for your app:
	* **cf CLI v7**:

		```
		cf7 droplets MY-APP
		```
	* **cf CLI v6**:

		```
		cf v3-droplets MY-APP
		```

1. From the output, locate and copy the second-to-last GUID. In the following example, this is `66524145-5502-40e6-b782-47fe68e13c49`. 
	<pre class="terminal">
	Listing droplets of app MY-APP in org test / space test as admin...

	guid state created
 	66524145-5502-40e6-b782-47fe68e13c49 staged Mon 25 Sep 16:37:34 PDT 2018
 	0677ad93-9f77-4aaa-9a6b-44da022dcd58 staged Mon 25 Sep 16:44:55 PDT 2018
	</pre>

1. Stop your app:
	* **cf CLI v7**:

		```
		cf7 stop MY-APP
		```
	* **cf CLI v6**:

		```
		cf v3-stop MY-APP
		```

1. Set the app to use the previous droplet:
	* **cf CLI v7**:

		```
		cf7 set-droplet MY-APP -d PREVIOUS-DROPLET-GUID
		```
	* **cf CLI v6**:

		```
		cf v3-set-droplet MY-APP -d PREVIOUS-DROPLET-GUID
		```

1. Start your app:
	* **cf CLI v7**:

		```
		cf7 start MY-APP
		```
	* **cf CLI v6**:

		```
		cf v3-start MY-APP
		```