getting-started.html.md.erb

---
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](http://cli.cloudfoundry.org/en-US/cf/config.html) 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
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+dc6adf6-2015-12-22
   ...
</pre>

<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](http://cli.cloudfoundry.org/en-US/cf/login.html) 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 https://api.example.com -u username<span>@</span>example.com
API endpoint: https://api.example.com

Password>
Authenticating...
OK

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

</pre>

Alternatively, you can write a script to log in and set your target using the non-interactive [cf api](http://cli.cloudfoundry.org/en-US/cf/api.html), [cf auth](http://cli.cloudfoundry.org/en-US/cf/auth.html), and [cf target](http://cli.cloudfoundry.org/en-US/cf/target.html) 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](http://cli.cloudfoundry.org/en-US/cf/org-users.html)

* [cf space-users](http://cli.cloudfoundry.org/en-US/cf/space-users.html)

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>example.com...

ORG MANAGER
  username<span>@</span>example.com

BILLING MANAGER
  huey<span>@</span>example.com
  dewey<span>@</span>example.com

ORG AUDITOR
  louie<span>@</span>example.com
</pre>

### <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](http://cli.cloudfoundry.org/en-US/cf/set-org-role.html)

* [cf unset-org-role](http://cli.cloudfoundry.org/en-US/cf/unset-org-role.html)

* [cf set-space-role](http://cli.cloudfoundry.org/en-US/cf/set-space-role.html)

* [cf unset-space-role](http://cli.cloudfoundry.org/en-US/cf/unset-space-role.html)

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 huey@example.com example-org OrgManager

Assigning role OrgManager to user huey<span>@</span>example.com in org example-org as username<span>@</span>example.com...
OK
</pre>

<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='push'></a>Push

The [cf push](http://cli.cloudfoundry.org/en-US/cf/push.html) 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](http://cli.cloudfoundry.org/en-US/cf/push.html) page in the Cloud Foundry CLI Reference Guide.

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.

<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 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: 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
</pre>

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](http://tools.ietf.org/html/rfc6587). When used with third-party logging, the cf CLI sends data formatted according to [RFC 5424](http://tools.ietf.org/html/rfc5424).

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](http://cli.cloudfoundry.org/en-US/cf/create-user-provided-service.html) (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"
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
</pre>

**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":"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<span>@</span>example.com...
OK
</pre>

**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://logs4.example.com:25258
Creating user provided service mylog in org example-org / space development as username<span>@</span>example.com...
OK
</pre>

After you create a user-provided service instance, you bind it to an app with [cf bind-service](http://cli.cloudfoundry.org/en-US/cf/bind-service.html), 
unbind it with [cf unbind-service](http://cli.cloudfoundry.org/en-US/cf/unbind-service.html), rename it with [cf rename-service](http://cli.cloudfoundry.org/en-US/cf/rename-service.html), and delete it with [cf delete-service](http://cli.cloudfoundry.org/en-US/cf/delete-service.html).

### <a id='user-uups'></a> The cf update-user-provided-service (uups) Command ###

Use [cf update-user-provided-service](http://cli.cloudfoundry.org/en-US/cf/update-user-provided-service.html) (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](http://cli.cloudfoundry.org/en-US/cf) 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
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 routes
</pre>