Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A CLI for Cloud Foundry written in Go
Go Shell NSIS Batchfile Ruby Makefile
Failed to load latest commit information.
Godeps Update dependencies away from
bin Update to use renamed i18n4go binary name
cf More privatisation.
ci Fix hanging in herd-cats -linux ci script
commands_loader Add cf router-groups command
fileutils use go 1.4 to detect symlink file in windows
fixtures Support yaml '<<' merge type
flags implement Default Value in flags package
generic switch to godeps
glob switch to godeps
installers remove unneccessary scripts and binaries from bin
json Surface error when json from file is invalid
main gofmt main
plugin Fix copypasta example name in cli_rpc_server_test
plugin_examples Update
release Add a script for updating links to stable release
testhelpers Update dependencies away from
utils move version checking methods into utils package
words Change fake_word_generator to a counterfeiter fake
.gitignore fake out cf config for testing
.travis.yml Move to go 1.5.1 [#104131294] Update dependencies away from Update rename gcf to cf
LICENSE Added copyright owner to LICENSE Fix apostrophe mistake
VERSION Bump version to 6.12.4
cf_commands_excluded.json Changes cf commands to return a 1 when failing requirements.
excluded.json Adding 'quota' to excluded file. This should have been here.
makefile Updating go vet location in install-dev-tools target, as it has moved.

Cloud Foundry CLI Build Status

This is the official command line client for Cloud Foundry.

You can follow our development progress on Pivotal Tracker.

Getting Started

Download and run the installer for your platform from the Downloads Section.

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

$ cd [my-app-directory]
$ cf api api.[my-cloudfoundry].com
Setting api endpoint to https://api.[my-cloudfoundry].com...

$ cf login
API endpoint: https://api.[my-cloudfoundry].com

Email> [my-email]

Password> [my-password]

$ cf push

Further Reading and Getting Help

  • You can find further documentation at the docs page for the CLI here.
  • There is also help available in the CLI itself; type cf help for more information.
  • Each command also has help output available via cf [command] --help or cf [command] -h.
  • For development guide on writing a cli plugin, see here.
  • Finally, if you are still stuck or have any questions or issues, feel free to open a GitHub issue.


WARNING: Edge binaries are published with each new 'push' that passes though CI. These binaries are not intended for wider use; they're for developers to test new features and fixes as they are completed.

Stable Installers Stable Binaries Edge Binaries
Mac OS X 64 bit Mac OS X 64 bit Mac OS X 64 bit
Windows 32 bit Windows 32 bit Windows 32 bit
Windows 64 bit Windows 64 bit Windows 64 bit
Redhat 32 bit Linux 32 bit Linux 32 bit
Redhat 64 bit Linux 64 bit Linux 64 bit
Debian 32 bit
Debian 64 bit

Experimental: Install CF for OSX through Homebrew via the pivotal's homebrew-tap:

$ brew tap pivotal/tap
$ brew install cloudfoundry-cli

Releases: Information about our releases can be found here

Troubleshooting / FAQs

Known Issues

  • .cfignore used in cf push must be in UTF8 encoding for CLI to interpret correctly.


Filing Bugs

For simple bugs (eg: text formatting, help messages, etc), please provide
  • the command you ran
  • what occurred
  • what you expected to occur
For bugs related to HTTP requests or strange behavior, please run the command with env var CF_TRACE=true and provide
  • the command you ran
  • the trace output
  • a high-level description of the bug
For panics and other crashes, please provide
  • the command you ran
  • the stack trace generated (if any)
  • any other relevant information

Forking the repository for development

  1. Install Go
  2. Ensure your $GOPATH is set correctly
  3. Install godep
  4. Get the cli source code: go get
    • (Ignore any warnings about "no buildable Go source files")
  5. Run godep restore (note: this will modify the dependencies in your $GOPATH)
  6. Fork the repository
  7. Add your fork as a remote: cd $GOPATH/src/ && git remote add your_name


To prepare your build environment, run go get

  1. Run ./bin/build
  2. The binary will be built into the ./out directory.

Optionally, you can use bin/run to compile and run the executable in one step.

If you want to run the tests with ginkgo, or build with go build you should first run bin/generate-language-resources. bin/build and bin/test generate language files automatically.


  1. Install Mercurial
  2. Run go get
  3. Write a Ginkgo test.
  4. Run bin/test and watch the test fail.
  5. Make the test pass.
  6. Submit a pull request to the master branch.

* For development guide on writing a cli plugin, see here


Major new feature proposals are given as a publically viewable google document with commenting allowed and discussed on the vcap-dev mailing list.

Pull Requests

Pull Requests should be made against the master branch.

Architecture overview

A command is a struct that implements this interface:

type Command interface {
    MetaData() CommandMetadata
    SetDependency(deps Dependency, pluginCall bool) Command
    Requirements(requirementsFactory requirements.Factory, context flags.FlagContext) (reqs []requirements.Requirement, err error)
    Execute(context flags.FlagContext)

Source code

Metadata() is just a description of the command name, usage and flags:

type CommandMetadata struct {
    Name            string
    ShortName       string
    Usage           string
    Description     string
    Flags           map[string]flags.FlagSet
    SkipFlagParsing bool
    TotalArgs       int

Source code

Requirements() returns a list of requirements that need to be met before a command can be invoked.

Execute() is the method that your command implements to do whatever it's supposed to do. The context object provides flags and arguments.

When the command is run, it communicates with api using repositories (they are in cf/api).

SetDependency() is where a command obtains its dependencies. Dependencies are typically declared as an interface type, and not a concrete type, so tests can inject a fake. The bool argument pluginCall indicates whether the command is invoked by one of the CLI's plugin API methods.

Dependencies are injected into each command, so tests can inject a fake. This means that dependencies are typically declared as an interface type, and not a concrete type. (see cf/command_registry/dependency.go)

Some dependencies are managed by a repository locator in cf/api/repository_locator.go.

Repositories communicate with the api endpoints through a Gateway (see cf/net).

Models are data structures related to Cloud Foundry (see cf/models). For example, some models are apps, buildpacks, domains, etc.

Managing dependencies

Command dependencies are managed by the command registry package. The app uses the package (in cf/command_registry/dependency.go)to instantiate them, this allows not sharing the knowledge of their dependencies with the app itself.

For commands that use another command as dependency, command_registry is used for retrieving the command dependency. For example, the command restart has a dependency on command start and stop, and this is how the command dependency is retrieved: restart.go

As for repositories, we use the repository locator to handle their dependencies. You can find it in cf/api/repository_locator.go.

Example command

Create Space is a good example of a command. Its tests include checking arguments, requiring the user to be logged in, and the actual behavior of the command itself. You can find it in cf/commands/space/create_space.go.


All pull requests which include user-facing strings should include updated translation files. These files are generated/ maintained using i18n4go.

To add/ update translation strings run the command i18n4go -c fixup. For each change or update, you will be presented with the choices new or upd. Type in the appropriate choice. If upd is chosen, you will be asked to confirm which string is being updated using a numbered list.

Current conventions

Creating Commands

Resources that include several commands have been broken out into their own sub-package using the Resource name. An example of this convention is the Space resource and package (see cf/commands/space)

In addition, command file and methods naming follows a CRUD like convention. For example, the Space resource includes commands such a CreateSpace, ListSpaces, DeleteSpace, etc.

Creating Repositories

Although not ideal, we use the name "Repository" for API related operations as opposed to "Service". Repository was chosen to avoid confusion with Service model objects (i.e. creating Services and Service Instances within Cloud Foundry).

By convention, Repository methods return a model object and an error. Models are used in both Commands and Repositories to model Cloud Foundry data. This convention provides a consistent method signature across repositories.

Something went wrong with that request. Please try again.