tchigher / cli-1

The official command line client for Cloud Foundry

Cloud Foundry CLI

The official command line client for Cloud Foundry.

Announcement ==> The V7 CLI is now Generally Available!

View the latest help for each command here (or run cf help -a with either version of the CLI for help on all commands available).

---

Sections: Getting Started | Download | Known Issues | Bugs/Feature Requests | Plugin Development | Contributing

---

There are now two supported versions of the cf CLI:

1. The v7 cf CLI is backed by the v3 CC API (with the exception of plugins which will be migrated in the next major release). See our v7 documentation for more information.
2. The v6 cf CLI is backed by the v2 CC API See our v6 documentation for more information.

The initial GA of the v7 cf CLI is Opt-In

• You can pull down the GA release of the v7 cf CLI and/or the latest v6 cf CLI via our supported package managers using the same processes that were in place prior to the v7 GA (no changes are required initially)
• If you've been pulling down the v7 CF CLI beta previously, you will notice the name of the v7 binary has changed from cf7 to cf
• See our Version Switching section for instructions on how to support workflows which require switching back and forth between v7 and v6

A Note About Support:
Now that the v7 cf CLI is GA, all new features, enhancements, and fixes will be made on the v7 line.
The v7 CLI's minimum supported version of the CC API is v3.85.0 (published in CAPI release v1.95.0).
The v7 CLI's minimum supported version of the CF-Deployment is v13.5.0.

Going forward, the v6 CLI will only be updated to resolve the most severe defects and/or security issues. At some point in the future, the v2 CC API endpoint will be deprecated by CAPI (see the v2 CC API deprecation plan) and the v6 CLI will be incompatible CAPI once a capi-release that deprecates the v2 endpoint has been published. Until the v2 CC API is deprecated, you can expect the v6 CLI to be fully functional, however, the CLI team's CI/CD resources are now focused on the v7 CLI so the v6 CLIs official maximum supported version of the CC APIs are now capped at v2.149.0 and v3.84.0 (published in CAPI release v1.94.0), and the V6 CLIs official maximum supported version of the CF-Deployment is now capped at v13.4.0.

The v6 CLI's minimum supported version of the CF-Deployment is v7.0.0. If you are on an older version of CF Deployment, we recommend you upgrade to CF-Deployment v7.0.0+.

If you have any questions, ask away on the #cli channel in our Slack community and the cf-dev mailing list, or open a GitHub issue. You can follow our development progress on Core CF CLI Pivotal Tracker.

Getting Started

Download and install the cf CLI from the Downloads Section for either the v7 cf CLI or the v6 cf CLI.

Once installed, you can log in and push an app.

Need to switch back and forth between CLI versions? See the Version Switching section for instructions.

Check out our community contributed CLI plugins to further enhance your CLI experience.

Downloads

It is recommended to download installers from the published URLs or using one of the documented package managers (APT/deb/homebrew repos). Published URLs may redirect requests to URLs that may change over time, so may installer filenames change over time.

Downloading the latest CF CLI

As of 6/29/2020, the instructions in this section will result in pulling the latest v6 cf CLI however at some point in the near future, we'll make updates to point to the v7 line instead.

Installing using a package manager

Mac OS X and Linux using Homebrew via the cloudfoundry tap:

brew install cloudfoundry/tap/cf-cli

Note: cf tab completion requires bash-completion to be installed properly in order to work.

Debian and Ubuntu based Linux distributions:

# ...first add the Cloud Foundry Foundation public key and package repository to your system
wget -q -O - https://packages.cloudfoundry.org/debian/cli.cloudfoundry.org.key | sudo apt-key add -
echo "deb https://packages.cloudfoundry.org/debian stable main" | sudo tee /etc/apt/sources.list.d/cloudfoundry-cli.list
# ...then, update your local package index, then finally install the cf CLI
sudo apt-get update
sudo apt-get install cf-cli

Enterprise Linux and Fedora systems (RHEL6/CentOS6 and up):

# ...first configure the Cloud Foundry Foundation package repository
sudo wget -O /etc/yum.repos.d/cloudfoundry-cli.repo https://packages.cloudfoundry.org/fedora/cloudfoundry-cli.repo
# ...then, install the cf CLI (which will also download and add the public key to your system)
sudo yum install cf-cli

Installers and compressed binaries

	Mac OS X 64 bit	Windows 64 bit	Linux 64 bit
Installers	pkg	zip	rpm / deb
Binaries	tgz	zip	tgz

Release notes, and 32 bit releases can be found here.

Download examples with curl for Mac OS X and Linux binaries

# ...download & extract Mac OS X binary
curl -L "https://packages.cloudfoundry.org/stable?release=macosx64-binary&source=github" | tar -zx
# ...or Linux 64-bit binary
curl -L "https://packages.cloudfoundry.org/stable?release=linux64-binary&source=github" | tar -zx
# ...move it to /usr/local/bin or a location you know is in your $PATH
mv cf /usr/local/bin
# ...copy tab completion file on Ubuntu (takes affect after re-opening your shell)
sudo curl -o /usr/share/bash-completion/completions/cf https://raw.githubusercontent.com/cloudfoundry/cli-ci/master/ci/installers/completion/cf
# ...and to confirm your cf CLI version
cf version

Edge binaries

Edge binaries are not intended for wider use; they're for developers to test new features and fixes as they are 'pushed' and passed through the CI. Follow these download links for Mac OS X 64 bit, Windows 64 bit and Linux 64 bit.

---

Downloading the latest V6 CF CLI

Installing using a package manager

Mac OS X and Linux using Homebrew via the cloudfoundry tap:

brew install cloudfoundry/tap/cf-cli@6

Note: cf tab completion requires bash-completion to be installed properly in order to work.

Debian and Ubuntu based Linux distributions:

# ...first add the Cloud Foundry Foundation public key and package repository to your system
wget -q -O - https://packages.cloudfoundry.org/debian/cli.cloudfoundry.org.key | sudo apt-key add -
echo "deb https://packages.cloudfoundry.org/debian stable main" | sudo tee /etc/apt/sources.list.d/cloudfoundry-cli.list
# ...then, update your local package index, then finally install the cf CLI
sudo apt-get update
sudo apt-get install cf-cli

Enterprise Linux and Fedora systems (RHEL6/CentOS6 and up):

# ...first configure the Cloud Foundry Foundation package repository
sudo wget -O /etc/yum.repos.d/cloudfoundry-cli.repo https://packages.cloudfoundry.org/fedora/cloudfoundry-cli.repo
# ...then, install the cf CLI (which will also download and add the public key to your system)
sudo yum install cf-cli

Installers and compressed binaries

	Mac OS X 64 bit	Windows 64 bit	Linux 64 bit
Installers	pkg	zip	rpm / deb
Binaries	tgz	zip	tgz

Release notes, and 32 bit releases can be found here.

Download examples with curl for Mac OS X and Linux binaries

# ...download & extract Mac OS X binary
curl -L "https://packages.cloudfoundry.org/stable?release=macosx64-binary&source=github&version=v6" | tar -zx
# ...or Linux 64-bit binary
curl -L "https://packages.cloudfoundry.org/stable?release=linux64-binary&source=github&version=v6" | tar -zx
# ...move it to /usr/local/bin or a location you know is in your $PATH
mv cf /usr/local/bin
# ...copy tab completion file on Ubuntu (takes affect after re-opening your shell)
sudo curl -o /usr/share/bash-completion/completions/cf https://raw.githubusercontent.com/cloudfoundry/cli-ci/master/ci/installers/completion/cf
# ...and to confirm your cf CLI version
cf version

Edge binaries

Edge binaries are not intended for wider use; they're for developers to test new features and fixes as they are 'pushed' and passed through the CI. Follow these download links for Mac OS X 64 bit, Windows 64 bit and Linux 64 bit.

---

Downloading the latest V7 CF CLI

Important Note: The v7 CF CLI is now GA and the binary has been renamed from cf7 to cf. If you're already using the v7 CLI in parallel to the v6 CLI, you may need to change your workflow to accomodate the binary name change. See the Version Switching section for instructions. For more information and general status on the v7 CLI, please check releases.

Compatibility

The v7 CLI's minimum supported version of the CC API is v3.85.0 (published in CAPI release v1.95.0). See the releases page for the minimum CAPI versions required for each V7 release.

Installing using a package manager

Mac OS X and Linux using Homebrew via the cloudfoundry tap:

brew install cloudfoundry/tap/cf-cli@7

Note: cf tab completion requires bash-completion to be installed properly in order to work.

Debian and Ubuntu based Linux distributions:

# ...first add the Cloud Foundry Foundation public key and package repository to your system
wget -q -O - https://packages.cloudfoundry.org/debian/cli.cloudfoundry.org.key | sudo apt-key add -
echo "deb https://packages.cloudfoundry.org/debian stable main" | sudo tee /etc/apt/sources.list.d/cloudfoundry-cli.list
# ...then, update your local package index, then finally install the cf CLI
sudo apt-get update
sudo apt-get install cf7-cli

Enterprise Linux and Fedora systems (RHEL6/CentOS6 and up):

# ...first configure the Cloud Foundry Foundation package repository
sudo wget -O /etc/yum.repos.d/cloudfoundry-cli.repo https://packages.cloudfoundry.org/fedora/cloudfoundry-cli.repo
# ...then, install the cf CLI (which will also download and add the public key to your system)
sudo yum install cf7-cli

Installers and compressed binaries

	Mac OS X 64 bit	Windows 64 bit	Linux 64 bit
Installers	pkg	zip	rpm / deb
Binaries	tgz	zip	tgz

Release notes, and 32 bit releases can be found here.

Download examples with curl for Mac OS X and Linux binaries

# ...download & extract Mac OS X binary
curl -L "https://packages.cloudfoundry.org/stable?release=macosx64-binary&version=v7&source=github" | tar -zx
# ...or Linux 64-bit binary
curl -L "https://packages.cloudfoundry.org/stable?release=linux64-binary&version=v7&source=github" | tar -zx
# ...move it to /usr/local/bin or a location you know is in your $PATH
mv cf /usr/local/bin
# ...copy tab completion file on Ubuntu (takes affect after re-opening your shell)
sudo curl -o /usr/share/bash-completion/completions/cf7 https://raw.githubusercontent.com/cloudfoundry/cli-ci/master/ci/installers/completion/cf7
# ...and to confirm your cf CLI version
cf version

Edge binaries

Edge binaries are not intended for wider use; they're for developers to test new features and fixes as they are 'pushed' and passed through the CI. Follow these download links for Mac OS X 64 bit, Windows 64 bit and Linux 64 bit.

Version Switching

The GA'd v7 cf CLI binary is named cf whereas all the beta release v7 binaries were named cf7. Workflows that require switching between the v7 and v6 CLIs can be scripted to accomodate utilizing binaries of the same name on a single computer.

Below you'll find instructions for each of the package managers we support.

Switching CLI versions Using Brew

• Assuming you've installed both the v6 and v7 CLIs as follows...
  • brew install cf-cli@7
  • brew install cf-cli@6
• Switch from v6 to v7:
  • brew unlink cf-cli@6 && brew unlink cf-cli@7 && brew link cf-cli@7 && cf version
• Switch from v7 to v6:
  • brew unlink cf-cli@7 && brew unlink cf-cli@6 && brew link cf-cli@6 && cf version

Switching CLI versions Using Yum or Apt

We're working on a robust soluiton that will faciliate more seamless switching via these package managers, but for now you must uninstall one version of the CLI and install the other version of the CLI to switch between them.

• Currently on v6, want to switch to v7:
  • yum: sudo yum remove cf-cli && sudo yum install cf7-cli && cf version
  • apt: sudo apt-get remove cf-cli && sudo apt-get cf7-cli && cf version
• Currently on v7, want to switch to v6:
  • yum: sudo yum remove cf7-cli && sudo yum install cf-cli && cf version
  • apt: sudo apt-get remove cf7-cli && sudo apt-get cf-cli && cf version

Switching CLI Versions Pulled via GitHub or CLAW

The following is a simple approach:

• Download the v6 and v7 binaries into separate directories
• Write a scipt that updates your PATH so it points to the binary for the version of the CLI you need to run:
  • export PATH=/path/to/your/v6-or-v7/binary/:$PATH

Known Issues

• On Windows in Cygwin and Git Bash, interactive password prompts (in cf login) do not hide the password properly from stdout (issue #1835). Please use an alternative command (non-interactive authentication cf auth instead of cf login) to work around this. Or, use the Windows cmd command line.
• On Windows, cf ssh may not display correctly if the TERM is not set. We've found that setting TERM to msys fixes some of these issues.
• On Windows, cf ssh will hang when run from the MINGW32 or MINGW64 shell. A workaround is to use PowerShell instead.
• CF CLI/GoLang do not use OpenSSL. Custom/Self Signed Certificates need to be installed in specific locations in order to login/auth without --skip-ssl-validation.
• API tracing to terminal (using CF_TRACE=true, -v option or cf config --trace) doesn't work well with some CLI plugin commands. Trace to file works fine. On Linux, CF_TRACE=/dev/stdout works too. See this Diego-Enabler plugin issue for more information.
• .cfignore used in cf push must be in UTF-8 encoding for CLI to interpret correctly. (issue #281)
• On Linux, when encountering message "bash: .cf: No such file or directory", ensure that you're using the correct binary or installer for your architecture.

Filing Issues & Feature Requests

First, update to the latest cli and try the command again.

If the error remains or feature still missing, check the open issues and if not already raised please file a new issue with the requested details.

Plugin Development

The CF CLI supports external code execution via the plugins API. For more information follow:

• The CF CLI plugin development guide
• The official plugins repository

When importing the plugin code use import "code.cloudfoundry.org/cli/plugin". Older plugins that import github.com/cloudfoundry/cli/plugin will still work as long they vendor the plugins directory.

Contributing & Build Instructions

Please read the contributors' guide

If you'd like to submit updated translations, please see the i18n README for instructions on how to submit an update.