Getting started with the cf CLI | Cloud Foundry Docs

Getting started with the cf CLI |
Cloud Foundry Docs
Doc Index
General Information
Contribute to Cloud Foundry documentation
Cloud Foundry concepts
Cloud Foundry overview
Security and networking
Cloud Foundry security
Container security in Cloud Foundry
Container-to-container networking
Orgs, spaces, roles, and permissions in Cloud Foundry
Managing Roles
Planning orgs and spaces in Cloud Foundry
App Security Groups in Cloud Foundry
Cloud Foundry app SSH components and processes
High availability
High availability in Cloud Foundry
How Cloud Foundry maintains high availability
How Cloud Foundry manages apps
Staging your apps in Cloud Foundry
The app container lifecycle on Diego architecture
How Diego balances app processes in Cloud Foundry
Cloud Foundry components
Diego components and architecture
Cloud Foundry routing architecture
Cloud Controller
Cloud Controller blobstore
User Account and Authentication server
Garden component
GrootFS disk usage in Cloud Foundry
HTTP routing
Cloud Foundry Command Line Interface (cf CLI)
Installing the cf CLI
Upgrading to cf CLI v8
Getting started with the cf CLI
Using the cf CLI with a proxy server
Using the cf CLI with a self-signed certificate
Using cf CLI plug-ins
Developing cf CLI plug-ins
Information for Operators
Deploying Cloud Foundry
Setting up DNS for your environment
Deploying Cloud Foundry with cf-deployment
Deploying BOSH on AWS
Deploying BOSH on GCP
Deploying Cloud Foundry
Configuring your Cloud Foundry for BOSH Backup and Restore
Backup and restore for external blobstores
Additional configuration
Cloud Controller blobstore configuration
cf-release end of life
Administering Cloud Foundry
Managing the runtime
Stopping and starting virtual machines
Creating and modifying quota plans
Using feature flags
Examining GrootFS disk usage
Using metadata
Managing custom buildpacks
Using Docker in Cloud Foundry
User accounts and communications
Creating and managing users with the cf CLI
Creating and managing users with the UAA CLI (UAAC)
Get started with the Notifications Service
Routing
Enabling IPv6 for hosted apps
Distributed tracing
Enabling Zipkin tracing
Enabling W3C tracing
Supporting WebSockets
Configuring load balancer health checks for CF routers
Securing incoming traffic
Enabling and configuring TCP routing
Configuring HTTP/2 support
Isolation segments
Managing isolation segments
Routing for isolation segments
Delayed jobs in Cloud Foundry
Configuring delayed job priorities with Cloud Controller
Managing apps and their stacks
Using Stack Auditor
Managing stack lifecycle
Changing stacks
Restaging your apps on a Windows stack
Running and Troubleshooting Cloud Foundry
Cloud Foundry logging
Configuring system logging
Configuring Diego for upgrades
Audit Events
UAA audit requirements
Usage events and billing
Configuring SSH access for Cloud Foundry
Configuring Diego Cell disk cleanup scheduling
Configuring Health Monitor Notifications
Adding a custom stack
Monitoring and testing Diego components
Troubleshooting Cloud Foundry
UAA performance
UAA performance metrics
Scaling Cloud Controller
Cloud Controller Multi-Process Mode (Puma)
Scaling Cloud Controller (cf-for-k8s)
Logging and metrics in Cloud Foundry
Logging and metrics architecture
Installing the Loggregator plug-in for cf CLI
Security event logging
Limiting your app log rate in Cloud Foundry
Cloud Foundry component metrics
Container metrics
Loggregator guide for Cloud Foundry operators
Logging and metrics in Cloud Foundry
Configuring the OpenTelemetry Collector
Deploying a nozzle to your Cloud Foundry Loggregator Firehose
BOSH Documentation
BOSH Backup and Restore (BBR)
Installing BBR
Release notes for BBR
Backing up with BBR
Restoring with BBR
BBR logging
Advanced features
BBR developer's guide
Information for developers
Developing and managing apps
How to push your app with Cloud Foundry CLI (cf push)
Pushing your app using Cloud Foundry CLI (cf push)
Deploying with app manifests
App manifest attribute reference
Deploying an app with Docker
Deploying your large apps
Starting, restarting, and restaging apps
Pushing an app with multiple processes
Running cf push sub-step commands
Configuring app deployments
Pushing apps with sidecar processes
Using blue-green deployment to reduce downtime
Troubleshooting app deployment and health
SSH for apps and services
Configuring SSH access for your deployment
Accessing your apps with SSH
Accessing services with SSH
Routes and domains
Configuring routes and domains
Configuring per-route options
Hash-Based Routing
Configuring CF to route traffic to apps on custom ports
Routing HTTP/2 and gRPC traffic to apps
Troubleshooting TCP routing
Managing services
Managing service instances
Sharing service instances
Delivering service credentials to an app
Managing service keys
Configuring Play Framework service connections
Using an external file system (volume services)
User-provided service instances
Streaming app logs
Streaming app logs to log management services
Streaming app logs to third-party services
Streaming app logs to Splunk
Streaming app logs with Fluentd
Streaming app logs to Azure OMS log analytics
Using metrics with drain logs
Managing apps with the cf CLI
Running tasks in your apps
Scaling your app using Cloud Foundry CLI (cf scale)
Using Cloud Foundry health checks
Retrieving app and event information
Configuring container-to-Container networking
Cloud Foundry environment variables
Available Cloud Controller API client libraries
Designing and running your app in the cloud
Cloud Foundry API app revisions
Cloud Foundry Buildpacks
Cloud Native Buildpacks
Paketo Buildpacks
Classic Buildpacks
What are classic buildpacks?
Working with buildpacks in Cloud Foundry
CF buildpack languages and sources
Stack association
Pushing an app with multiple buildpacks
Using a proxy server
Supported binary dependencies
Configuring the production server
Binary buildpack
Go buildpack
Hosted Web Core buildpack
Creating an extension buildpack for .NET apps
Using the .NET Framework Web Config Transform Extension Buildpack
Java buildpack
Using Cloud Foundry Java buildpack
Getting started deploying Java apps to Cloud Foundry
Getting started deploying your Grails apps to Cloud Foundry
Getting started deploying Ratpack apps to Cloud Foundry
Getting started deploying Spring apps to Cloud Foundry
Configuring service connections
Using Java Native Image
Cloud Foundry Java Client Library
.NET Core buildpack
NGINX buildpack
Node.js buildpack
Node.js buildpack-specific information
Environment variables defined by Node buildpack
Configuring service connections for Node.js application
Using PHP buildpack with runtimes
Additional information on PHP buildpacks in Cloud Foundry
Getting started deploying PHP apps to Cloud Foundry
PHP buildpack configuration
Composer
Sessions
New Relic
Python buildpack
R buildpack
Ruby buildpack
Additional information on Ruby buildpacks in Cloud Foundry
Getting started deploying Ruby apps
Getting started deploying Ruby apps
Getting started deploying Ruby on Rails apps
Configuring Rake tasks for deployed apps
Environment variables defined by Ruby buildpack
Configuring service connections for Ruby
Windows Gemfile support
Staticfile buildpacks
Creating custom buildpacks
Sidecar buildpacks
Packaging dependencies for offline buildpacks
Merging from upstream buildpacks
Upgrading dependency versions for Cloud Foundry
Using CI for buildpacks
Releasing a new Cloud Foundry buildpack version
Updating buildpack-related gems in Cloud Foundry
Information for Managed Service Authors
Services in Cloud Foundry
Service Broker API
Open Service Broker API
Platform profiles
Catalog metadata
Volume services
Release Notes
Managing service brokers in Cloud Foundry
Managing access to service plans
Binding credentials in Cloud Foundry
CredHub
Setting up and deploying CredHub with BOSH
Configuring a hardware security module
Using a key management service with CredHub
CredHub credential types
Backing up and restoring CredHub instances
Troubleshooting CredHub
Dashboard Single Sign-on
Service instance sharing in Cloud Foundry
Service broker examples
App log streaming in Cloud Foundry
Offering Route Services in Cloud Foundry
Supporting multiple CF instances
User Account and Authentication
UAA Overview
UAA Concepts
Identity Providers in UAA
UAA Metrics
Deploy UAA
API Reference
UAA API
CAPI API
Rate limit information returned by the Cloud Controller API
CAPI V2
CAPI V3
Getting started with the cf CLI
Prerequisite
Log in with the CLI
Log in with the API
Manage users and roles
Push an app
Push a new app or push changes to an app
Push an app using a manifest
Push an app with a buildpack
Map a route to an app
Manage user-provided service instances
Create a service instance
Bind and unbind service instances
Update a service instance
Retrieve cf CLI return codes
View CLI help output
Page last updated:
The Cloud Foundry Command Line Interface (cf CLI) is the official command line client for Cloud Foundry. You can use the cf CLI to manage apps, service instances, orgs, spaces, and users in your environment.
cf CLI v7 is no longer supported, and not all v7 commands will work. Please upgrade to cf CLI v8 before following the instructions in this guide.
Prerequisite
To follow the procedures in this topic, you must download and install the latest version of the cf CLI v8. For more information, see
Installing the Cloud Foundry command line interface
Log in with the CLI
The
cf login
command uses the syntax described below to specify a target API endpoint, login credentials, an org, and a space.
The cf CLI prompts for credentials as needed. If you are a member of multiple orgs or spaces,
cf login
prompts you to specify the org or space to which you
want to log in. Otherwise, it targets your org and space automatically.
To log in to the cf CLI:
In a terminal window, run:
cf login -a API-URL -u USERNAME -p PASSWORD -o ORG -s SPACE
Where:
API-URL
is your API endpoint, the URL of the Cloud Controller in your Cloud Foundry instance.
USERNAME
is your username.
PASSWORD
is your password. Cloud Foundry discourages using the
-p
option, because it records your password in your shell history.
ORG
is the org where you want to deploy your apps.
SPACE
is the space in the org where you want to deploy your apps.
When you successfully log in, you see output similar to the following example:
API endpoint: https://api.example.com

Password>
Authenticating...
OK

Targeted org example-org

Targeted space development

API endpoint: https://api.example.com
User: username
example.com
Org: example-org
Space: development
Alternatively, you can write a script to log in and set your target using the non-interactive
cf api
cf auth
, and
cf target
commands. See
UAAC
for setting up
client_id
and
client_secret
Log in with the API
You can write a script to log in to the cf CLI. This allows you to avoid manually logging in to the cf CLI each time you use it.
To write a script to log in:
In a terminal window, target your API by running:
cf api API-URL
Where
API-URL
is your API endpoint, the URL of the Cloud Controller in your Cloud Foundry instance.
For more information about the
cf api
command, use
cf api --help
Authenticate by running:
cf auth USERNAME PASSWORD
Where:
USERNAME
is your username.
PASSWORD
is your password. Cloud Foundry discourages using the
-p
option, because it records your password in your shell history.
For more information about the
cf auth
command, use
cf auth --help
Target your org or space by running:
cf target -o ORG -s SPACE
Where:
ORG
is the org you want to target.
SPACE
is the space you want to target.
For more information about the
cf target
command, use
cf target --help
After you log in, the cf CLI saves a
config.json
file that contains your API endpoint, org, space values, and access token. If you change these settings,
the
config.json
file is updated accordingly.
By default,
config.json
is located in the
~/.cf
directory. You can relocate the
config.json
file using the
CF_HOME
environment variable.
Manage users and roles
The cf CLI includes commands to list users and assign roles in orgs and spaces. For a full reference, including role assignment for UAA clients and multi-origin disambiguation, see
Managing roles
For more information about the available roles and their permissions, see
Orgs, Spaces, Roles, and Permissions
The following example assigns the Org Manager role to
[email protected]
in
example-org
$ cf set-org-role huey
example.com example-org OrgManager
Assigning role OrgManager to user huey
example.com in org example-org as username
example.com...
OK
If you are not an admin, you see this message when you try to run these commands:
error code: 10003, message: You are not authorized to perform the requested action
Push an app
These sections describe how to use the
cf push
command to push a new app or sync changes to an existing app.
For more information about the
cf push
command, use
cf push --help
Push a new app or push changes to an app
To push an app:
In a terminal window, log in to the cf CLI by running:
cf login
Go to the directory of the app.
Push a new app or push changes to an app by running:
cf push APP-NAME
Where
APP-NAME
is the name of the app.
Push an app using a manifest
You can provide a path to a manifest file when you push an app. The manifest file includes information such as the name of the app, disk limit, and number
of instances. You can use a manifest file rather than adding flags to the
cf push
command.
cf push
locates the
manifest.yml
file in the current working directory by default. Alternatively, you can provide a path to the manifest with the
-f
flag.
For more information about the
-f
flag, see the
cf push --help
output.
When you provide an app name at the command line, the
cf push
command uses that app
name instead of any app name provided in the manifest. If the manifest configures multiple apps, you can push a
single app by providing thenname at the command line; the cf CLI does not push the others. Use these behaviors for testing.
Push an app with a buildpack
You can specify a buildpack when you push an app with the
-b
flag. If you use the
-b
flag to specify a buildpack, the app remains permanently linked to
that buildpack. To use the app with a different buildpack, you must delete the app and then push it again.
For more information about available buildpacks, see the
Cloud Foundry documentation
The following example shows the terminal output for
cf push awesome-app -b ruby_buildpack
, which pushes an app called
awesome-app
to the URL
and specifies the Ruby buildpack with the
-b
flag:
Pushing app awesome-app to org example-org / space development as
[email protected]
...

...

Waiting for app awesome-app to start...

name: awesome-app
requested state: started
routes: awesome-app.example.com
last uploaded: Wed 17 Jul 22:57:04 UTC 2024
stack: cflinuxfs3
buildpacks:
name version detect output buildpack name
ruby_buildpack 1.8.58 ruby ruby

type: web
sidecars:
instances: 1/1
memory usage: 1024M
start command: bundle exec rackup config.ru -p $PORT -o 0.0.0.0
state since cpu memory disk logging cpu entitlement details
#0 running 2024-07-17T22:57:22Z 0.3% 49.5M of 1G 130.2M of 1G 0B/s of 16K/s 2.4%
To avoid security exposure, verify that you migrate your apps and custom
buildpacks to use the
cflinuxfs4
stack based on Ubuntu 22.04 LTS (Jammy Jellyfish). The
cflinuxfs3
stack is
based on Ubuntu 18.04 (Bionic Beaver), which reaches end of standard support in April 2023.
Map a route to an app
You can provide a hostname for your app when you push the app. If you do not provide a hostname, the
cf push
command routes your app to a URL of the form
APP-NAME.DOMAIN
, where
APP-NAME
is the name of your app and
DOMAIN
is the default domain configured in the Cloud Foundry environment. The route definition is
included in the
manifest.yml
file.
For information about mapping a route to your app, see
Routes and domains
To map a route to the app:
In a terminal window, log in to the cf CLI by running:
cf login
Push and map a route by running:
cf push -f manifest.yml --var host=APP-HOSTNAME
Where:
APP-NAME
is the name of the app.
APP-DOMAIN
is the domain of the app.
APP-HOSTNAME
is the hostname of the app.
Manage user-provided service instances
These sections describe how to create or update a service instance.
Create a service instance
To create a new service instance, use the
cf create-user-provided-service
or
cf cups
commands. For more information about the
cf create-user-provided-service
and
cf cups
commands, use
cf create-user-provided-service --help
To create or update a user-provided service instance, you must supply basic parameters. For example, a database service might require a username, password,
host, port, and database name.
You can provide these parameters in the following ways:
Interactively. For more information, see
Supply Parameters Interactively
below.
Non-interactively. For more information, see
Supply Parameters Non-Interactively
below.
With third-party log management software as described in RFC 6587. For more information, see
Supply Parameters Through a Third Party
below
and
RFC 6587
When used with third-party logging, data is sent formatted according to RFC 5424. For more information, see
RFC 5424
Supply parameters interactively
To create a new service while supplying parameters interactively:
In a terminal window, log in to the cf CLI by running:
cf login
List parameters in a comma-separated list after the
-p
flag. Run:
cf cups SERVICE -p "PARAMETER, SECOND-PARAMETER, THIRD-PARAMETER"
Where:
SERVICE
is the name of the service you want to create.
PARAMETER
SECOND-PARAMETER
, and
THIRD-PARAMETER
are parameters such as username, password, host, port, and database name.
Supply parameters non-interactively
To create a new service while supplying parameters non-interactively:
In a terminal window, log in to the cf CLI by running:
cf login
Pass parameters and their values in as a JSON hash, bound by single quotes, after the
-p
tag. Run:
cf cups SERVICE -p '{"host":"HOSTNAME", "port":"PORT"}'
Where:
SERVICE
is the name of the service you want to create.
HOSTNAME
and
PORT
are service parameters.
Supply parameters through a third party
For specific log service instructions, see
Streaming app logs to third-party services
To create a service instance that sends data to a third party:
Log in to the cf CLI:
cf login
Create a service instance that sends data to a third party by running:
cf cups SERVICE -l THIRD-PARTY-DESTINATION-URL
Where:
SERVICE
is the name of the service you want to create.
THIRD-PARTY-DESTINATION-URL
is the external URL of the third-party service.
Bind and unbind service instances
After you create a user-provided service instance, you can:
Bind the service to an app with
cf bind-service
. For more information, use
cf bind-service --help
Unbind the service with
cf unbind-service
. For more information, use
cf unbind-service --help
Rename the service with
cf rename-service
. For more information, use
cf rename-service --help
Delete the service with
cf delete-service
. For more information, use
cf delete-service --help
Update a service instance
To update one or more of the parameters for an existing user-provided service instance, use
cf update-user-provided-service
or
cf uups
For more information about the
cf update-user-provided-service
and
cf uups
commands, use
cf create-user-provided-service --help
The
cf uups
command does not update any parameter values that you do not supply.
Retrieve cf CLI return codes
The cf CLI uses exit codes, which help with scripting and confirming that a command has run successfully.
To view a cf CLI exit code:
In a terminal window, log in to the cf CLI by running:
cf login
To check that the login was successful, run one of these commands, depending on your OS:
For macOS, run:
echo $?
For Windows, run:
echo %ERRORLEVEL%
If the command succeeds, the exit code is
View CLI help output
The
cf help
command lists the cf CLI commands and a brief description of each..
To list detailed help for any cf CLI command, add the
--help
or
-h
flag to the command.
The example below shows detailed help output for the
cf delete
command:
NAME:
delete - Delete an app

USAGE:
cf delete APP_NAME [-f -r]

ALIAS:

OPTIONS:
-f Force deletion without confirmation
-r Delete any mapped routes (only deletes routes mapped to a single app)
Create a pull request or raise an issue on the source for this page in GitHub