Using cf CLI Plugins

Page last updated: October 15, 2015

The Cloud Foundry Command Line Interface (cf CLI) v.6.7 and higher includes plugin functionality. These plugins enable developers to add custom commands to the cf CLI. You can install and use plugins that Cloud Foundry developers and third-party developers create. You can review the Cloud Foundry Community CLI Plugin page for a current list of community-supported plugins. You can find information about submitting your own plugin to the community in the Cloud Foundry CLI plugin repository on GitHub.

The cf CLI identifies a plugin by its binary filename, its developer-defined plugin name, and the commands that the plugin provides. You use the binary filename only to install a plugin. You use the plugin name or a command for any other action.

Note: The cf CLI uses case-sensitive plugin names and commands, but not case-sensitive binary filenames.

Prerequisites

Using plugins requires cf CLI v.6.7 or higher. Refer to the Installing the cf Command Line Interface topic for information about downloading, installing, and uninstalling the cf CLI.

Changing the Plugin Directory

By default, the cf CLI stores plugins in $HOME/.cf/plugins on your workstation. To change the root directory of this path from $HOME, set the CF_PLUGIN_HOME environment variable. The cf CLI appends .cf/plugins to the CF_PLUGIN_HOME path that you specify and stores plugins in that location.

For example, if you set CF_PLUGIN_HOME to /my-folder, cf CLI stores plugins in /my-folder/.cf/plugins.

Installing a Plugin

  1. Download a binary or the source code for a plugin from a trusted provider.

    Note: The cf CLI requires a binary file compiled from source code written in Go. If you download source code, you must compile the code to create a binary.

  2. Run cf install-plugin BINARY_FILENAME to install a plugin. Replace BINARY_FILENAME with the path to and name of your binary file.

    Note: You cannot install a plugin that has the same name or that uses the same command as an existing plugin. You must first uninstall the existing plugin.

    Note: The cf CLI prohibits you from implementing any plugin that uses a native cf CLI command name or alias. For example, if you attempt to install a third-party plugin that includes the command cf push, the cf CLI halts the installation.

Running a Plugin Command

Use the contents of the cf help PLUGIN and PLUGIN COMMANDS sections to manage plugins and run plugin commands.

  1. Run cf plugins to list all installed plugins and all commands that the plugins provide.
  2. Run cf PLUGIN_COMMAND to execute a plugin command.

Uninstalling a Plugin

Use the PLUGIN_NAME to remove a plugin, not the BINARY_FILENAME.

  1. Run cf plugins to view the names of all installed plugins.
  2. Run cf uninstall-plugin PLUGIN_NAME to remove a plugin.

Adding a Plugin Repo

Run cf add-plugin-repo REPO_NAME URL to add a plugin repo.

Example: 

$ cf add-plugin-repo CF-Community http://plugins.cloudfoundry.org
OK
http://plugins.cloudfoundry.org/list added as 'CF-Community'

Listing Available Plugin Repos

Run cf list-plugin-repos to view your available plugin repos.

Example: 

$ cf list-plugin-repos
OK



Repo Name      Url
CF-Community   http://plugins.cloudfoundry.org

Listing All Plugins by Repo

Run cf repo-plugins to show all plugins from all available repos.

Troubleshooting

The cf CLI provides the following error messages to help you troubleshoot installation and usage issues. Third-party plugins can provide their own error messages.

Permission Denied

If you receive a permission denied error message, you lack required permissions to the plugin. You must have read and execute permissions to the plugin binary file.

Plugin Command Collision

Plugin names and commands must be unique. The CLI displays an error message if you attempt to install a plugin with a non-unique name or command.

If the plugin has the same name or command as a currently installed plugin, you must first uninstall the existing plugin to install the new plugin.

If the plugin has a command with the same name as a native cf CLI command or alias, you cannot install the plugin.