Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
264 lines (177 sloc) 12.4 KB
title: Getting Started with the cf CLI
owner: CLI
<strong><%= modified_date %></strong>
This topic describes configuring and getting started with the Cloud Foundry Command Line Interface (cf CLI).
This page assumes you have the latest version of the cf CLI.
See the [Installing the Cloud Foundry Command Line Interface](./install-go-cli.html) topic for installation instructions.
##<a id='i18n'></a>Localize ##
The cf CLI translates terminal output into the language that you select. The default language is <code>en-US</code>. The cf CLI supports the following languages:
* Chinese (simplified): <code>zh-Hans</code>
* Chinese (traditional): <code>zh-Hant</code>
* English: <code>en-US</code>
* French: <code>fr-FR</code>
* German: <code>de-DE</code>
* Italian: <code>it-IT</code>
* Japanese: <code>ja-JP</code>
* Korean: <code>ko-KR</code>
* Portuguese (Brazil): <code>pt-BR</code>
* Spanish: <code>es-ES</code>
Use [cf config]( to set the language. To set the language with `cf config`, use the syntax: <code>$ cf config --locale YOUR_LANGUAGE </code>.
For example, to set the language to Portuguese and confirm the change by running `cf help`:
<pre class="terminal">
$ cf config --locale pt-BR
$ cf help
cf - Uma ferramenta de linha de comando para interagir com Cloud Foundry
cf [opções globais] comando [argumentos...] [opções de comando]
<p class='note'><strong>Note</strong>: Localization with <code>cf config --locale</code> affects only messages that the cf CLI generates. </p>
## <a id='login'></a>Login ##
Use [cf login]( to log in to <%= vars.product_short %>. The `cf login` command uses the following syntax to specify a target API endpoint, an org (organization), and a space: <code>$ cf login [-a API_URL] [-u USERNAME] [-p PASSWORD] [-o ORG] [-s SPACE] </code>.
* `API_URL`: This is your API endpoint, <%=vars.api_endpoint%>.
* `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.
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.
<pre class="terminal">
$ cf login -a -u username<span>@</span>
API endpoint:
Select an org (or press enter to skip):
1. example-org
2. example-other-org
Org> 1
Targeted org example-org
Select a space (or press enter to skip):
1. development
2. staging
3. production
Space> 1
Targeted 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.
Upon successful login, the cf CLI saves a `config.json` file containing 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 your `~/.cf` directory. The `CF_HOME` environment variable allows you to locate the `config.json` file wherever you like.
## <a id='user-roles'></a> Users and Roles ##
The cf CLI includes commands that list users and assign roles in orgs and spaces. See the [Orgs, Spaces, Roles, and Permissions](../concepts/roles.html) topic.
### <a id='listing-users'></a>Commands for Listing Users ###
These commands take an org or space as an argument:
* [cf org-users](
* [cf space-users](
For example, to list the users who are members of an org:
<pre class="terminal">
$ cf org-users example-org
Getting users in org example-org as username<span>@</span>
### <a id='managing-roles'></a>Commands for Managing Roles ###
These commands require <%=vars.product_short%> admin permissions and take username, org or space, and role as arguments:
* [cf set-org-role](
* [cf unset-org-role](
* [cf set-space-role](
* [cf unset-space-role](
Available roles are `OrgManager`, `BillingManager`, `OrgAuditor`, `SpaceManager`, `SpaceDeveloper`, and `SpaceAuditor`. For example, to grant the Org Manager role to a user within an org:
<pre class="terminal">
$ cf set-org-role example-org OrgManager
Assigning role OrgManager to user huey<span>@</span> in org example-org as username<span>@</span>
<p class="note"><strong>Note</strong>: If you are not a <%=vars.product_short%> admin, you see this message when you try to run these commands:
<code>error code: 10003, message: You are not authorized to perform the requested action</code></p>
#### <a id='multi-origin'></a>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 `set` and `unset` role commands above return an error:
`The user exists in multiple origins. Specify an origin for the requested user from: ‘uaa’, ‘other’`
To resolve this ambiguity, the operator can 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.
## <a id='push'></a>Push
The [cf push]( command pushes a new app or syncs changes to an existing app.
If you do not provide a hostname (also known as subdomain), `cf push` routes your app to a URL of the form `APPNAME.DOMAIN` based on the name of your app and your default domain.
If you want to map a different route to your app, see the [Routes and Domains](../devguide/deploy-apps/routes-domains.html) topic for information about creating routes.
The `cf push` command supports many options that determine how and where the app instances are deployed. For details about the `cf push` command, see the [push]( page in the Cloud Foundry CLI Reference Guide.
The following example pushes an app called `my-awesome-app` to the URL `` and specifies the Ruby buildpack with the `-b` flag.
<p class="note"><strong>Note</strong>: When you push an app and specify a buildpack with the <code>-b</code> flag, the app remains permanently linked to that buildpack. To use the app with a different buildpack, you must delete the app and re-push it.</p>
<pre class="terminal">
$ cf push my-awesome-app -b ruby_buildpack
Creating app my-awesome-app in org example-org / space development as
Creating route
1 of 1 instances running
App started
requested state: started
instances: 1/1
usage: 1G x 1 instances
last uploaded: Wed Jun 8 23:43:15 UTC 2016
stack: cflinuxfs2
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
For more information about available buildpacks, see the <a href="../buildpacks/">Buildpacks</a> topic.
## <a id='user-provided'></a> User-Provided Service Instances ##
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.
The cf CLI has three ways of supplying these parameters to create or update an instance of a service: interactively, non-interactively, and in conjunction with
third-party log management software as described in [RFC 6587]( When used with third-party logging, the cf CLI sends data formatted according to [RFC 5424](
You create a service instance with `cf cups` and update one with `cf uups` as described below.
### <a id='user-cups'></a>The cf create-user-provided-service (cups) Command ###
Use [cf create-user-provided-service]( (alias `cf cups`) creates a new service instance.
**To supply service instance parameters interactively:** Specify parameters in a comma-separated list after the `-p` flag. This example command-line session creates a service instance for a database service.
<pre class="terminal">$ cf cups sql-service-instance -p "host, port, dbname, username, password"
port> 1433
dbname> mysqldb
username> admin
password> Pa55w0rd
Creating user provided service sql-service-instance in org example-org / space development as
**To supply service instance parameters to `cf cups` non-interactively:** Pass parameters and their values in as a JSON hash, bound by single quotes, after the `-p` tag. This example is a non-interactive version of the `cf cups` session above.
<pre class="terminal">$ cf cups sql-service-instance -p '{"host":"", "port":"1433", "dbname":"mysqldb", "username":"admin","password":"pa55woRD"}'
Creating user provided service sql-service-instance in org example-org / space development as username<span>@</span>
**To create a service instance that sends data to a third-party:** Use the `-l` option followed by the external destination URL. This example creates a service instance that sends log information to the syslog drain URL of a third-party log management service. For specific log service instructions, see the [Service-Specific Instructions for Streaming Application Logs](../devguide/services/log-management-thirdparty-svc.html) topic.
<pre class="terminal">$ cf cups mylog -l syslog://
Creating user provided service mylog in org example-org / space development as username<span>@</span>
After you create a user-provided service instance, you bind it to an app with [cf bind-service](,
unbind it with [cf unbind-service](, rename it with [cf rename-service](, and delete it with [cf delete-service](
### <a id='user-uups'></a> The cf update-user-provided-service (uups) Command ###
Use [cf update-user-provided-service]( (alias `cf uups`) to update one or more of the parameters for an existing user-provided service instance.
The `cf uups` command uses the same syntax as `cf cups` [above](#user-cups) to set parameter values. The `cf uups` command does not update any parameter values that you do not supply.
## <a id='return-codes'></a> cf CLI Return Codes ##
The cf CLI uses exit codes, which help with scripting and confirming that a command has run successfully. For example, after you run a cf CLI command, you can retrieve its return code by running `echo $?` (on Windows, `echo %ERRORLEVEL%`). If the return code is `0`, the command was successful.
## <a id='help'></a> The cf help Command ##
The [cf help]( command lists the cf CLI commands and a brief description of each.
Passing the `-h` flag to any command lists detailed help, including any aliases. For example, to see detailed help for `cf delete`, run:
<pre class="terminal">
$ cf delete -h
delete - Delete an app
cf delete APP_NAME [-f -r]
-f Force deletion without confirmation
-r Also delete any mapped routes