getting-started.html.md.erb

---
title: Getting Started with the cf CLI
owner: CLI
---

This topic describes configuring and getting started with the Cloud Foundry Command Line Interface (cf CLI).


## <a id='overview'></a> 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, spaces, and users
in your environment.


## <a id='prerequisite'></a> Prerequisite

To do the procedures in this topic, you must download and install the latest version of the cf CLI. For more information, see [Installing the Cloud Foundry Command Line Interface](./install-go-cli.html).


## <a id='login'></a> 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 for which ones to log in to. Otherwise, it targets your org and space automatically.

To log in to the cf CLI:

1. Run:

    ```
    cf login -a API-URL -u USERNAME -p PASSWORD -o ORG -s SPACE
    ```
    Where:
    * `API-URL` is your API endpoint, <%= vars.api_endpoint %>.
    * `USERNAME` is your username.
    * `PASSWORD` is your password. <%= vars.company_name %> discourages using the `-p` option, as it may record 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 like the example below:

<pre class="terminal">
$ cf login -a https://api.example.com -u username<span>@</span>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<span>@</span>example.com
Org:            example-org
Space:          development

</pre>


## <a id='login'></a> 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:

1. Target your API by running:

    ```
    cf api API-URL
    ```
    Where `API-URL` is your API endpoint, <%= vars.api_endpoint %>.
    <br>
    <br>
    For more information, see [api](http://cli.cloudfoundry.org/en-US/cf/api.html) in the _Cloud Foundry CLI Reference Guide_.

1. Authenticate by running:

    ```
    cf auth USERNAME PASSWORD
    ```
    Where:
    * `USERNAME` is your username.
    * `PASSWORD` is your password. <%= vars.company_name %> discourages using the `-p` option,
       because it may record your password in your shell history.
    <br>
    <br>
    For more information, see [auth](http://cli.cloudfoundry.org/en-US/cf/auth.html) in the _Cloud Foundry CLI Reference Guide_.

1. 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.
    <br>
    <br>
    For more information, see [target](http://cli.cloudfoundry.org/en-US/cf/target.html) 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. You can relocate the `config.json` file using the `CF_HOME` environment variable.


## <a id='i18n'></a> 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 these 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](http://cli.cloudfoundry.org/en-US/cf/config.html) in the _Cloud Foundry CLI Reference Guide_.

<p class='note'><strong>Note:</strong> Localization with <code>cf config --locale</code> affects only messages that the cf CLI generates.</p>

To set the language of the cf CLI:

1. Log in to the cf CLI:

    ```
    cf login
    ```

1. Run:

    ```
    cf config --locale LANGUAGE
    ```
    Where `LANGUAGE` is code of the language you want to set.

1. Confirm the language change by running:

    ```
    cf help
    ```
    The command returns output similar to the example below:

    <pre class="terminal">
    $ 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
       ...
    </pre>


## <a id='user-roles'></a> Manage Users and Roles

The cf CLI includes commands that list users and assign roles in orgs and spaces.

### <a id='listing-users'></a> List Users

To list all users in an org or a space:

1. Log in to the cf CLI:

    ```
    cf login
    ```

1. Run one of these commands:
  * To list org users, run:

      ```
      cf org-users
      ```
  * To list space users, run:

      ```
      cf space-users
      ```

The command returns output similar to the example below:

<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>

For more information, see [org-users](http://cli.cloudfoundry.org/en-US/cf/org-users.html) and [space-users](http://cli.cloudfoundry.org/en-US/cf/space-users.html) in the _Cloud Foundry CLI Reference Guide_.

### <a id='managing-roles'></a> Manage Roles

You use the commands listed below to manage roles in the cf CLI.
These commands require admin permissions and take username,
org or space, and role as arguments:

* `cf set-org-role`<br>For more information, see [set-org-role](http://cli.cloudfoundry.org/en-US/cf/set-org-role.html) in the _Cloud Foundry CLI Reference Guide_.

* `cf unset-org-role`<br>For more information, see [unset-org-role](http://cli.cloudfoundry.org/en-US/cf/unset-org-role.html) in the _Cloud Foundry CLI Reference Guide_.

* `cf set-space-role`<br>For more information, see [set-space-role](http://cli.cloudfoundry.org/en-US/cf/set-space-role.html) in the _Cloud Foundry CLI Reference Guide_.

* `cf unset-space-role`<br>For more information, see [unset-space-role](http://cli.cloudfoundry.org/en-US/cf/unset-space-role.html) in the _Cloud Foundry CLI Reference Guide_.

The available roles are:

* `OrgManager`
* `BillingManager`
* `OrgAuditor`
* `SpaceManager`
* `SpaceDeveloper`
* `SpaceAuditor`

For more information about user roles, see [Orgs, Spaces, Roles, and Permissions](../concepts/roles.html).

The example below shows the cf CLI output for assigning 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 an 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> 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 this error:

<pre class="terminal">The user exists in multiple origins. Specify an origin for the requested user from: ‘uaa’, ‘other’</pre>

To resolve this ambiguity, you can construct a `curl` command that uses the API to perform the desired role management function. For an example, see [Associate Auditor with the Organization by Username](http://apidocs.cloudfoundry.org/280/organizations/associate_auditor_with_the_organization_by_username.html) in the Cloud Foundry API documentation.


## <a id='push'></a> 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, see [push](http://cli.cloudfoundry.org/en-US/cf/push.html) in the _Cloud Foundry CLI Reference Guide_.

### <a id='push-procedure'></a> Push a New App or Push Changes to an App

To push an app:

1. Log in to the cf CLI by running:

    ```
    cf login
    ```

1. Navigate to the directory of the app.

1. 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.

### <a id='push-path'></a> 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](http://cli.cloudfoundry.org/en-US/cf/push.html) in the _Cloud Foundry CLI Reference Guide_.

<p class="note"><strong>Note:</strong> When you provide an app name at the command line, <code>cf push</code> 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.</p>

### <a id='push-buildpack'></a> 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](https://docs.cloudfoundry.org/buildpacks/).

The example below pushes an app called `awesome-app` to the URL `http://awesome-app.example.com` and specifies the Ruby buildpack with the `-b` flag:

<pre class="terminal">
$ cf push awesome-app -b ruby_buildpack
Creating app awesome-app in org example-org / space development as username@example.com...
OK

Creating route awesome-app.example.com...
OK
...

1 of 1 instances running

App started
...

requested state: started
instances: 1/1
usage: 1G x 1 instances
urls: 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
</pre>

### <a id='new-route'></a> 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 your default domain.

For information about mapping a route to your app, see [Routes and Domains](../devguide/deploy-apps/routes-domains.html).

To map a route to the app:

1. Log in to the cf CLI by running:

    ```
    cf login
    ```

1. Map a route by running:

    ```
    cf push APP-NAME --hostname APP-HOSTNAME
    ```
    Where:
      * `APP-NAME` is the name of the app.
      * `APP-HOSTNAME` is the hostname of the app.


## <a id='user-provided'></a> Manage User-Provided Service Instances

These sections describe how to create or update a service instance.

### <a id='user-cups'></a> Create a Service Instance

To create a new service instance, use the `cf create-user-provided-service` or `cf cups` commands. For more information, see [create-user-provided-service](http://cli.cloudfoundry.org/en-US/cf/create-user-provided-service.html) in the _Cloud Foundry CLI Reference Guide_.

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 these ways:

* Interactively. For more information, see [Supply Parameters Interactively](#interactive).

* Non-interactively. For more information, see [Supply Parameters Non-Interactively](#non-interactive).

* With third-party log management software as described in RFC 6587. For more information, see [Supply Parameters Through a Third Party](#third-party) and [RFC 6587](http://tools.ietf.org/html/rfc6587).
    <p class="note"><strong>Note:</strong> When used with third-party logging, the cf CLI sends data formatted according to RFC 5424. For more information, see [RFC 5424](http://tools.ietf.org/html/rfc5424).</p>

#### <a id='interactive'></a> Supply Parameters Interactively

To create a new service while supplying parameters interactively:

1. Log in to the cf CLI by running:

    ```
    cf login
    ```

1. 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.

#### <a id='non-interactive'></a> Supply Parameters Non-Interactively

To create a new service while supplying parameters non-interactively:

1. Log in to the cf CLI by running:

    ```
    cf login
    ```

1. 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.

#### <a id='third-party'></a> Supply Parameters Through a Third Party

For specific log service instructions, see [Service-Specific Instructions for Streaming App Logs](../devguide/services/log-management-thirdparty-svc.html).

To create a service instance that sends data to a third party:

1. Log in to the cf CLI:

    ```
    cf login
    ```
1. 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.

### <a id='bind-unbind'></a> 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, see [bind-service](http://cli.cloudfoundry.org/en-US/cf/bind-service.html) in the _Cloud Foundry CLI Reference Guide_.

* Unbind the service with `cf unbind-service`. For more information, see [unbind-service](http://cli.cloudfoundry.org/en-US/cf/unbind-service.html) in the _Cloud Foundry CLI Reference Guide_.

* Rename the service with `cf rename-service`. For more information, see [rename-service](http://cli.cloudfoundry.org/en-US/cf/rename-service.html) in the _Cloud Foundry CLI Reference Guide_.

* Delete the service with `cf delete-service`. For more information, see [delete-service](http://cli.cloudfoundry.org/en-US/cf/delete-service.html) in the _Cloud Foundry CLI Reference Guide_.

### <a id='user-uups'></a> 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](http://cli.cloudfoundry.org/en-US/cf/update-user-provided-service.html) in the _Cloud Foundry CLI Reference Guide_.

<p class="note"><strong>Note:</strong> The <code>cf uups</code> command does not update any parameter values that you do not supply.</p>


## <a id='return-codes'></a> 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:

1. Log in to the cf CLI by running:

    ```
    cf login
    ```

1. To check that the login was successful, run one of these commands, depending on your OS:
    * For Mac OS, run:

        ```
        echo $?
        ```
    * For Windows, run:

        ```
        echo %ERRORLEVEL%
        ```

If the command succeeds, the exit code is `0`.


## <a id='help'></a> View CLI Help Output

The `cf help` command lists the cf CLI commands and a brief description of each. For more information, see [help](http://cli.cloudfoundry.org/en-US/cf/help.html) in the _Cloud Foundry CLI Reference Guide_.

To list detailed help for any cf CLI command, add the `-h` flag to the command.

The example below shows detailed help output for the `cf delete` command:

<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>