This README discusses how to develop a cf CLI plugin. For user-focused documentation, see Using the cf CLI.

• Golang installed
• Tagged version of CLI release source code that supports plugins; cf CLI v.6.7.0 and above

The cf CLI plugin architecture model follows the remote procedure call (RPC) model. The cf CLI invokes each plugin, runs it as an independent executable, and handles all start, stop, and clean up tasks for plugin executable resources.

Plugins that you develop for the cf CLI must conform to a predefined plugin interface that we discuss below.

To write a plugin for the cf CLI, implement the predefined plugin interface.

The interface uses a Run(...) method as the main entry point between the CLI and a plugin. This method receives the following arguments:

• A struct plugin.CliConnection that contains methods for invoking cf CLI commands
• A string array that contains the arguments passed from the cf process

The GetMetadata() function informs the CLI of the name of a plugin, the commands it implements, and help text for each command that users can display with cf help.

To initialize a plugin, call plugin.Start(new(MyPluginStruct)) from within the main() method of your plugin. The plugin.Start(...) function requires a new reference to the struct that implements the defined interface.

This repo contains a basic plugin example here.

The Run(...) method accepts the command line arguments and flags that you define for a plugin.

See the [command line arguments example] (https://github.com/cloudfoundry/cli/blob/master/plugin_examples/echo.go) included in this repo.

You can invoke CLI commands with cliConnection.CliCommand([]args) from within a plugin's Run(...) method. The Run(...) method receives the cliConnection as its first argument.

The cliConnection.CliCommand([]args) returns the output printed by the command and an error. The output is returned as a slice of strings. The error will be present if the call to the CLI command fails.

See the calling CLI commands example included in this repo.

Because a plugin has access to stdin during a call to the Run(...) method, you can create interactive plugins. See the interactive plugin example included in this repo.

The cf CLI requires an executable file to install the plugin. You must compile the source code with the go build command before distributing the plugin, or instruct your users to compile the plugin source code before installing the plugin. For information about compiling Go source code, see Compile packages and dependencies.

After you compile a plugin, use the following commands to install and manage the plugin.

To install a plugin, run:

cf install-plugin PATH_TO_PLUGIN_BINARY

To display a list of installed plugins and the commands available from each plugin, run:

cf plugins

To remove a plugin, run:

cf uninstall-plugin PLUGIN_NAME

• When invoking a CLI command using cliConnection.CliCommand([]args) a plugin developer will not receive output generated by the codegangsta/cli package. This includes usage failures when executing a cli command, cf help, or cli SOME-COMMAND -h.