Getting Started with the cf CLI
This topic describes configuring and getting started with the Cloud Foundry Command Line Interface (cf CLI).
Overview
The cf CLI is the official command line client for Cloud Foundry. You can use the cf CLI to manage apps, service instances, orgs and spaces, and users in your environment.
Prerequisite
To do the procedures in this topic, you must download and install the latest version of the cf CLI. See Installing the Cloud Foundry Command Line Interface.
Log In With the CLI
The cf login
command uses the following syntax 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 for which ones to log into. Otherwise it targets your org and space automatically.
To log in to the cf CLI:
cf login -a API_URL -u USERNAME -p PASSWORD -o ORG -s SPACE
Where:
API_URL
: This is your API endpoint, the URL of the Cloud Controller in your App Cloud instance.USERNAME
: Your username.PASSWORD
: Your password. Use of the-p
option is discouraged as it may record your password in your shell history.ORG
: The org where you want to deploy your apps.SPACE
: The space in the org where you want to deploy your apps.
$ cf login -a https://api.example.com -u username@example.com -o example-org -s development 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
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, set your target using the non-interactive cf api
, cf auth
, and cf target
commands.
For more information about these commands, see the following topics in the Cloud Foundry CLI Reference Guide:
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. The CF_HOME
environment variable allows you to relocate the config.json
file.
Localize the CLI
The cf CLI translates terminal output into the language that you select. The default language is en-US
.
The cf CLI supports the following languages:
- Chinese (simplified):
zh-Hans
- Chinese (traditional):
zh-Hant
- English:
en-US
- French:
fr-FR
- German:
de-DE
- Italian:
it-IT
- Japanese:
ja-JP
- Korean:
ko-KR
- Portuguese (Brazil):
pt-BR
- Spanish:
es-ES
For more information, see config in Cloud Foundry CLI Reference Guide.
Note: Localization with cf config --locale
affects only messages that the cf CLI generates.
To set the language of the cf CLI:
Log in to the cf CLI:
cf login
Run the following command:
$ cf config --locale YOUR-LANGUAGE
Where
YOUR-LANGUAGE
is the desired language.For example:
$ cf config --locale pt-BR
Confirm the language change:
cf help
For example:
$ cf help NOME: cf - Uma ferramenta de linha de comando para interagir com Cloud Foundry USO: cf [opções globais] comando [argumentos...] [opções de comando] VERSÃO: 6.14.1 ...
Manage Users and Roles
The cf CLI includes commands that list users and assign roles in orgs and spaces.
List Users
This section describes how to list users in an org or space. For more information, see org-users and space-users in the Cloud Foundry CLI Reference Guide.
To list users in an org or a space:
Log in to the cf CLI:
cf login
Do one of the following:
- List org users:
cf org-users
- List space users:
cf space-users
The following example shows the cf CLI output for listing the users of an org:
$ cf org-users example-org Getting users in org example-org as username@example.com... ORG MANAGER username@example.com BILLING MANAGER huey@example.com dewey@example.com ORG AUDITOR louie@example.com
Manage Roles
The following commands can be used to manage roles in the cf CLI. These commands require Cloud Foundry admin permissions and take username, org or space, and role as arguments:
cf set-org-role
. See set-org-role in the Cloud Foundry CLI Reference Guide.cf unset-org-role
. See unset-org-role in the Cloud Foundry CLI Reference Guide.cf set-space-role
. See set-space-role in the Cloud Foundry CLI Reference Guide.cf unset-space-role
. See unset-space-role in the Cloud Foundry CLI Reference Guide.
The following are the available roles:
OrgManager
BillingManager
OrgAuditor
SpaceManager
SpaceDeveloper
SpaceAuditor
For more information about user roles, see Orgs, Spaces, Roles, and Permissions.
The following example shows the cf CLI output for assigning the Org Manager role to a user within an 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
Note: If you are not a Cloud Foundry 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
Manage Roles for Users with Identical Usernames in Multiple Origins
If a username corresponds to multiple accounts from different user stores, such as both the internal UAA store and an external SAML or LDAP store, the cf set-org-role
and the cf unset-org-role
commands above return the following error:
The user exists in multiple origins. Specify an origin for the requested user from: ‘uaa’, ‘other’
To resolve this ambiguity, construct a curl
command that uses the CF API to perform the desired role-management function.
For an example, see the PUT v2/organizations/:guid/auditors API function.
Push an App
This section describes how to use the cf push
command to push a new app or sync changes to an existing app.
For more information, see push in the Cloud Foundry CLI Reference Guide.
Push a New App or Push Changes to an App
The following procedure describes how to push an app from the cf CLI.
To push an app:
Log in to the cf CLI:
cf login
Navigate to the directory of the app.
Push a new app or push changes to an app:
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 may include 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. Or, you can provide a path to the manifest with the -f
flag.
For more information about the -f
flag, see push in the Cloud Foundry CLI Reference Guide.
Note: When you provide an app name at the command line, cf push
uses that app name whether or not there is a different app name in the manifest. If the manifest describes multiple apps, you can push a single app by providing its name 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 Buildpacks.
The following example pushes an app called my-awesome-app
to the URL http://my-awesome-app.example.com
and specifies the Ruby buildpack with the -b
flag:
$ cf push my-awesome-app -b ruby_buildpack Creating app my-awesome-app in org example-org / space development as username@example.com... OK Creating route my-awesome-app.example.com... OK ... 1 of 1 instances running App started ... requested state: started instances: 1/1 usage: 1G x 1 instances urls: my-awesome-app.example.com last uploaded: Wed Jun 8 23:43:15 UTC 2016 stack: cflinuxfs3 buildpack: ruby_buildpack state since cpu memory disk details #0 running 2016-06-08 04:44:07 PM 0.0% 0 of 1G 0 of 1G
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 APPNAME.DOMAIN
, where APPNAME
is the name of your app and DOMAIN
is your default domain.
For information about mapping a route to your app, see Routes and Domains.
To map a route to the app:
Log in to the cf CLI:
cf login
Map a route:
cf push APP-NAME --hostname MY-HOSTNAME
Where:
APP-NAME
is the name of the app.MY-HOSTNAME
is the hostname.
Manage User-Provided Service Instances
This section describes 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. See cf cups in the Cloud Foundry CLI Reference Guide.
To create or update a user-provided service instance, you need to 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. See Supply Parameters Interactively.
- Non-interactively. See Supply Parameters Non-Interactively.
- With third-party log management software as described in RFC 6587. See Supply Parameters Through a Third-Party. For more information, see RFC 6587
Note: When used with third-party logging, the cf CLI sends data formatted according to RFC 5424. See RFC 5424.
Supply Parameters Interactively
This procedure describes how to create a new service instance by supplying parameters interactively:
To supply parameters interactively:
Log in to the cf CLI:
cf login
List parameters in a comma-separated list after the
-p
flag:cf cups MY-SERVICE -p "MY-PARAMETER, MY-SECOND-PARAMETER, MY-THIRD-PARAMETER"
Where:
MY-SERVICE
is the name of the service to create.MY-PARAMETER
,MY-SECOND-PARAMETER
, andMY-THIRD-PARAMETER
are parameters such as username, password, host, port, and database name.
For example:
$ cf cups sql-service-instance -p "host, port, dbname, username, password" host> mysql.example.com port> 1433 dbname> mysqldb username> admin password> Pa55w0rd Creating user provided service sql-service-instance in org example-org / space development as username@example.com... OK
Supply Parameters Non-Interactively
This procedure describes how to create a new service instance by supplying parameters non-interactively:
To supply parameters non-interactively:
Log in to the cf CLI:
cf login
Pass parameters and their values in as a JSON hash, bound by single quotes, after the
-p
tag.cf cups MY-SERVICE -p '{"host":"HOSTNAME", "port":"PORT"}'
Where:
MY-SERVICE
is the name of the service to create.HOSTNAME
andPORT
are service parameters.
For example:
$ cf cups sql-service-instance -p '{"host":"mysql.example.com", "port":"1433", "dbname":"mysqldb", "username":"admin","password":"pa55woRD"}' Creating user provided service sql-service-instance in org example-org / space development as username@example.com... OK
Supply Parameters Through a Third-Party
For specific log service instructions, see Service-Specific Instructions for Streaming Application Logs.
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:
cf cups MY-SERVICE -l THIRD-PARTY-DESTINATION-URL
Where:
MY-SERVICE
is the name of the service to create.THIRD-PARTY-DESTINATION-URL
is the external URL of the third-party service.
For example, the following command creates a service instance that sends log information to the syslog drain URL of a third-party log management service:
$ cf cups mylog -l syslog://logs4.example.com:25258 Creating user provided service mylog in org example-org / space development as username@example.com... OK
Bind and Unbind Service Instances
After you create a user-provided service instance, you can do the following with the cf CLI:
Bind the service to an app with
cf bind-service
. See bind-service in the Cloud Foundry CLI Reference Guide.Unbind the service with
cf unbind-service
. See unbind-service in the Cloud Foundry CLI Reference Guide.Rename the service with
cf rename-service
. See rename-service in the Cloud Foundry CLI Reference Guide.Delete the service with
cf delete-service
. See delete-service in the Cloud Foundry CLI Reference Guide.
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, see update-user-provided-service in the Cloud Foundry CLI Reference Guide.
Note: 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. If a command was successful, the exit code is 0
.
To view a cf CLI exit code:
Log in to the cf CLI:
cf login
Run one of the following commands to see that the login was successful, depending on your OS:
- Mac:
echo $?
- Windows:
echo %ERRORLEVEL%
If the command was successful, the exit code is
0
.- Mac:
View CLI Help Output
The cf help
command lists the cf CLI commands and a brief description of each. For more information, see help in the Cloud Foundry CLI Reference Guide.
To list detailed help on any cf CLI command, add the -h
flag to the command.
The following example shows detailed help output for cf delete
:
$ cf delete -h NAME: delete - Delete an app USAGE: cf delete APP_NAME [-f -r] ALIAS: d OPTIONS: -f Force deletion without confirmation -r Also delete any mapped routesView the source for this page in GitHub