README
¶
Cloud Foundry CLI ![Build Status](https://travis-ci.org/cloudfoundry/cli.png?branch=master)
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...
OK
$ cf login
API endpoint: https://api.[my-cloudfoundry].com
Email> [my-email]
Password> [my-password]
Authenticating...
OK
$ 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
.
Finally, if you are still stuck, feel free to open a GitHub issue.
Downloads
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
Troubleshooting / FAQs
Linux
- "bash: .cf: No such file or directory". Ensure that you're using the correct binary or installer for your architecture. See http://askubuntu.com/questions/133389/no-such-file-or-directory-but-the-file-exists
Filing Bugs
- the command you ran
- what occurred
- what you expected to occur
- the command you ran
- the trace output
- a high-level description of the bug
- the command you ran
- the stack trace generated (if any)
- any other relevant information
Forking the repository for development
- Install Go
- Ensure your $GOPATH is set correctly
- Install godep
- Get the cli source code:
go get github.com/cloudfoundry/cli
- (Ignore any warnings about "no buildable Go source files")
- Fork the repository
- Add your fork as a remote:
cd $GOPATH/src/github.com/cloudfoundry/cli && git remote add your_name https://github.com/your_name/cli
Building
To prepare your build environment, run go get github.com/jteeuwen/go-bindata/...
- Run
./bin/build
- The binary will be built into the
./out
directory.
Optionally, you can use bin/run
to compile and run the executable in one step.
Developing
- Install Mercurial
- Run
go get code.google.com/p/go.tools/cmd/vet
- Write a Ginkgo test.
- Run
bin/test
and watch the test fail. - Make the test pass.
- Submit a pull request to the
master
branch.
Contributing
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() command_metadata.CommandMetadata
GetRequirements(requirementsFactory requirements.Factory, c *cli.Context) (reqs []requirements.Requirement, err error)
Run(c *cli.Context)
}
Metadata()
is just a description of the command name, usage and flags:
type CommandMetadata struct {
Name string
ShortName string
Usage string
Description string
Flags []cli.Flag
SkipFlagParsing bool
}
GetRequirements()
returns a list of requirements that need to be met before a command can be invoked.
Run()
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
).
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/commands/factory.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 commands factory. The app uses the command factory (in cf/commands/factory.go
)
to instantiate them, this allows not sharing the knowledge of their dependencies with the app itself.
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
.
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.
Directories
¶
Path | Synopsis |
---|---|
Godeps
|
|
_workspace/src/code.google.com/p/go.crypto/ssh/terminal
Package terminal provides support functions for dealing with terminals, as commonly found on UNIX systems.
|
Package terminal provides support functions for dealing with terminals, as commonly found on UNIX systems. |
_workspace/src/code.google.com/p/go.net/websocket
Package websocket implements a client and server for the WebSocket protocol as specified in RFC 6455.
|
Package websocket implements a client and server for the WebSocket protocol as specified in RFC 6455. |
_workspace/src/code.google.com/p/gogoprotobuf/proto
Package proto converts data structures to and from the wire format of protocol buffers.
|
Package proto converts data structures to and from the wire format of protocol buffers. |
_workspace/src/github.com/cloudfoundry/loggregator_consumer
Package loggregator_consumer provides a simple, channel-based API for clients to communicate with loggregator servers.
|
Package loggregator_consumer provides a simple, channel-based API for clients to communicate with loggregator servers. |
_workspace/src/github.com/codegangsta/cli
Package cli provides a minimal framework for creating and organizing command line Go applications.
|
Package cli provides a minimal framework for creating and organizing command line Go applications. |
_workspace/src/github.com/gorilla/websocket
Package websocket implements the WebSocket protocol defined in RFC 6455.
|
Package websocket implements the WebSocket protocol defined in RFC 6455. |
_workspace/src/github.com/gorilla/websocket/examples/autobahn
Command server is a test server for the Autobahn WebSockets Test Suite.
|
Command server is a test server for the Autobahn WebSockets Test Suite. |
_workspace/src/github.com/nicksnyder/go-i18n/i18n
Package i18n supports string translations with variable substitution and CLDR pluralization.
|
Package i18n supports string translations with variable substitution and CLDR pluralization. |
_workspace/src/github.com/nicksnyder/go-i18n/i18n/bundle
Package bundle manages translations for multiple languages.
|
Package bundle manages translations for multiple languages. |
_workspace/src/github.com/nicksnyder/go-i18n/i18n/language
Package language defines languages that implement CLDR pluralization.
|
Package language defines languages that implement CLDR pluralization. |
_workspace/src/github.com/nicksnyder/go-i18n/i18n/translation
Package translation defines the interface for a translation.
|
Package translation defines the interface for a translation. |
_workspace/src/github.com/onsi/ginkgo
Ginkgo is a BDD-style testing framework for Golang
|
Ginkgo is a BDD-style testing framework for Golang |
_workspace/src/github.com/onsi/ginkgo/config
Ginkgo accepts a number of configuration options.
|
Ginkgo accepts a number of configuration options. |
_workspace/src/github.com/onsi/ginkgo/ginkgo
The Ginkgo CLI
|
The Ginkgo CLI |
_workspace/src/github.com/onsi/ginkgo/reporters
Ginkgo's Default Reporter
|
Ginkgo's Default Reporter |
_workspace/src/github.com/onsi/gomega
Gomega is the Ginkgo BDD-style testing framework's preferred matcher library.
|
Gomega is the Ginkgo BDD-style testing framework's preferred matcher library. |
_workspace/src/github.com/onsi/gomega/format
Gomega's format package pretty-prints objects.
|
Gomega's format package pretty-prints objects. |
_workspace/src/github.com/onsi/gomega/gbytes
Package gbytes provides a buffer that supports incrementally detecting input.
|
Package gbytes provides a buffer that supports incrementally detecting input. |
_workspace/src/github.com/onsi/gomega/gexec
Package gexec provides support for testing external processes.
|
Package gexec provides support for testing external processes. |
_workspace/src/github.com/onsi/gomega/ghttp
Package ghttp supports testing HTTP clients by providing a test server (simply a thin wrapper around httptest's server) that supports registering multiple handlers.
|
Package ghttp supports testing HTTP clients by providing a test server (simply a thin wrapper around httptest's server) that supports registering multiple handlers. |
_workspace/src/github.com/onsi/gomega/matchers
Gomega matchers
|
Gomega matchers |
actors/broker_builder/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
actors/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
actors/plan_builder/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
actors/service_builder/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/environment_variable_groups/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/feature_flags/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/organizations/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/quotas/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/security_groups/defaults/running/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/security_groups/defaults/staging/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/security_groups/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/security_groups/spaces/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
api/space_quotas/fakes
This file was generated by counterfeiter
|
This file was generated by counterfeiter |
testhelpers
|
|