cli

module
v6.14.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2015 License: Apache-2.0

README

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

Downloads

Latest stable: Download the installer or compressed binary for your platform:

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

From the command line: Download examples with curl for Mac OS X and Linux

# ...download & extract Mac OS X binary
$ curl -L "https://cli.run.pivotal.io/stable?release=macosx64-binary&source=github" | tar -zx
# ...or Linux binary
$ curl -L "https://cli.run.pivotal.io/stable?release=linux64-binary&source=github" | tar -zx
# ...and confirm you got the version you expected
$ ./cf --version
cf version x.y.z-...

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

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

Also, edge binaries are published for Mac OS X 64 bit, Windows 64 bit and Linux 64 bit 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.

Releases: 32 bit releases and information about all 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.

Linux

Filing Bugs

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

If the error remains, run the command that exposes the bug with the environment variable CF_TRACE set to true and create an issue.

Include the below information when creating the issue:

  • The error that occurred
  • The stack trace (if applicable)
  • The command you ran (e.g. cf org-users)
  • The CLI Version (e.g. 6.13.0-dfba612)
  • Your platform details (e.g. Mac OS X 10.11, Windows 8.1 64-bit, Ubuntu 14.04.3 64-bit)
  • The shell you used (e.g. Terminal, iTerm, Powershell, Cygwin, gnome-terminal, terminator)
For simple bugs (eg: text formatting, help messages, etc), please provide
  • 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
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 github.com/cloudfoundry/cli
  • (Ignore any warnings about "no buildable Go source files")
  1. Run godep restore (note: this will modify the dependencies in your $GOPATH)
  2. Fork the repository
  3. 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 -u github.com/jteeuwen/go-bindata/...

  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.

Developing

  1. Install Mercurial
  2. Run go get golang.org/x/tools/cmd/vet
  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

Contributing

Major new feature proposals are given as a publically viewable google document with commenting allowed and discussed on the cf-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.

i18n

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.

Directories

Path Synopsis
Godeps
_workspace/src/github.com/Sirupsen/logrus
Package logrus is a structured logger for Go, completely API compatible with the standard library logger.
Package logrus is a structured logger for Go, completely API compatible with the standard library logger.
This file was generated by counterfeiter
This file was generated by counterfeiter
_workspace/src/github.com/cloudfoundry-incubator/diego-ssh/keys/fake_keys
This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter
_workspace/src/github.com/cloudfoundry-incubator/diego-ssh/test_helpers/fake_io
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
_workspace/src/github.com/cloudfoundry-incubator/diego-ssh/test_helpers/fake_net
This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter
_workspace/src/github.com/cloudfoundry-incubator/diego-ssh/test_helpers/fake_ssh
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
_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/cloudfoundry/sonde-go/events
Package events is a generated protocol buffer package.
Package events is a generated protocol buffer package.
_workspace/src/github.com/docker/docker/pkg/term
Package term provides provides structures and helper functions to work with terminal (state, sizes).
Package term provides provides structures and helper functions to work with terminal (state, sizes).
_workspace/src/github.com/gogo/protobuf/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/golang/protobuf/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/golang/protobuf/proto/proto3_proto
Package proto3_proto is a generated protocol buffer package.
Package proto3_proto is a generated protocol buffer package.
_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/kr/pty
Package pty provides functions for working with Unix terminals.
Package pty provides functions for working with Unix terminals.
_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 The godoc documentation describes Ginkgo's API.
Ginkgo is a BDD-style testing framework for Golang The godoc documentation describes Ginkgo's API.
_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 is fully documented [here](http://onsi.github.io/ginkgo/#the_ginkgo_cli) You can also learn more by running: ginkgo help Here are some of the more commonly used commands: To install: go install github.com/onsi/ginkgo/ginkgo To run tests: ginkgo To run tests in all subdirectories: ginkgo -r To run tests in particular packages: ginkgo <flags> /path/to/package /path/to/another/package To pass arguments/flags to your tests: ginkgo <flags> <packages> -- <pass-throughs> To run tests in parallel ginkgo -p this will automatically detect the optimal number of nodes to use.
The Ginkgo CLI The Ginkgo CLI is fully documented [here](http://onsi.github.io/ginkgo/#the_ginkgo_cli) You can also learn more by running: ginkgo help Here are some of the more commonly used commands: To install: go install github.com/onsi/ginkgo/ginkgo To run tests: ginkgo To run tests in all subdirectories: ginkgo -r To run tests in particular packages: ginkgo <flags> /path/to/package /path/to/another/package To pass arguments/flags to your tests: ginkgo <flags> <packages> -- <pass-throughs> To run tests in parallel ginkgo -p this will automatically detect the optimal number of nodes to use.
_workspace/src/github.com/onsi/ginkgo/internal/remote
Aggregator is a reporter used by the Ginkgo CLI to aggregate and present parallel test output coherently as tests complete.
Aggregator is a reporter used by the Ginkgo CLI to aggregate and present parallel test output coherently as tests complete.
_workspace/src/github.com/onsi/ginkgo/reporters
Ginkgo's Default Reporter A number of command line flags are available to tweak Ginkgo's default output.
Ginkgo's Default Reporter A number of command line flags are available to tweak Ginkgo's default output.
_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/ghttp/protobuf
Package protobuf is a generated protocol buffer package.
Package protobuf is a generated protocol buffer package.
_workspace/src/github.com/onsi/gomega/matchers
Gomega matchers This package implements the Gomega matchers and does not typically need to be imported.
Gomega matchers This package implements the Gomega matchers and does not typically need to be imported.
_workspace/src/golang.org/x/crypto/ssh
Package ssh implements an SSH client and server.
Package ssh implements an SSH client and server.
_workspace/src/golang.org/x/crypto/ssh/agent
Package agent implements a client to an ssh-agent daemon.
Package agent implements a client to an ssh-agent daemon.
_workspace/src/golang.org/x/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/golang.org/x/crypto/ssh/test
This package contains integration tests for the golang.org/x/crypto/ssh package.
This package contains integration tests for the golang.org/x/crypto/ssh package.
_workspace/src/golang.org/x/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/gopkg.in/yaml.v2
Package yaml implements YAML support for the Go language.
Package yaml implements YAML support for the Go language.
cf
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 This file was generated by counterfeiter
This file was generated by counterfeiter 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/plugin_repo/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
api/app_events/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
api/app_files/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
api/app_instances/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
api/application_bits/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
api/copy_application_source/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 This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter 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
api/stacks/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
app_files/fakes
This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter
configuration/fakes
This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter
configuration/plugin_config/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
i18n/detection/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
manifest/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
net
net/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
requirements/fakes
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
ssh
ssh/fakes
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
ssh/terminal/terminal_helper_fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
terminal/fakes
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
fixtures
fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
rpc
rpc/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
* * This is an example plugin where we use both arguments and flags.
* * This is an example plugin where we use both arguments and flags.
call_cli_cmd/main
* * This plugin is an example plugin that allows a user to call a cli-command * by typing `cf cli-command name-of-command args.....`.
* * This plugin is an example plugin that allows a user to call a cli-command * by typing `cf cli-command name-of-command args.....`.
test_rpc_server_example
* * This plugin demonstrate the use of Test driven development using the test rpc server * This allows the plugin to be tested independently without relying on CF CLI
* * This plugin demonstrate the use of Test driven development using the test rpc server * This allows the plugin to be tested independently without relying on CF CLI
testhelpers
commands
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter This file was generated by counterfeiter
io
net
rpc_server/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
fakes
This file was generated by counterfeiter
This file was generated by counterfeiter
generator/fakes
This file was generated by counterfeiter
This file was generated by counterfeiter

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL