The Cloud Foundry CLI (cf CLI) includes plug-in capability. Plug-ins allow you to add custom commands to the cf CLI.
You can install and use the plug-in that Cloud Foundry developers and third-party developers create. For a current list of community-supported plug-ins, see the Cloud Foundry Community CLI Plug-in page. For information about submitting your own plug-in, see the Cloud Foundry CLI Plugin Repository (CLIPR) repository on GitHub.
Important Plug-ins are not vetted for security or function. Use plug-ins at your own risk.
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.
The cf CLI uses case-sensitive commands, but plug-in management commands accept plug-in and repository names irrespective of their casing.
By default, the cf CLI stores plugins on your workstation in $CF_HOME/.cf/plugins
, which defaults to $HOME/.cf/plugins
.
To change the root directory of this path from $CF_HOME
, you must set the CF_PLUGIN_HOME
environment variable.
The cf CLI appends .cf/plugins
to the CF_PLUGIN_HOME
path that you specify and stores plug ins in that location. For example, if you set CF_PLUGIN_HOME
to /my-folder
, cf CLI stores plug-ins in /my-folder/.cf/plugins
.
To install a plugin:
Download a binary or the source code for a plugin from a trusted provider. 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.
Run:
cf install-plugin BINARY-FILENAME
Where BINARY-FILENAME
is the path to and name of your binary file.
Additional notes:
You cannot install a plug in that has the same name or that uses the same command as an existing plugin. If you try this, you are prompted to uninstall the existing plugin.
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 cf push
command, the cf CLI halts the installation.
For more information, see install-plugin in the Cloud Foundry CLI Reference Guide.
Use the contents of the cf help
CLI plugin management and Commands offered by installed plugins sections to manage plugins and run plugin commands.
To manage plugins and run plugin commands:
List all installed plugins and all commands that the plugins provide by running:
cf plugins
Execute a plugin command by running:
cf PLUGIN-COMMAND
Where PLUGIN-COMMAND
is the plug-in command that you want to run.
To check all registered plugin repositories for newer versions of currently installed plugins:
Run:
cf plugins --outdated
See the output of the above command, as in the example below:
$ cf plugins --outdated Searching CF-Community, company-repo for newer versions of installed plugins... plugin version latest version coffeemaker 1.1.2 1.2.0 Use 'cf install-plugin' to update a plugin to the latest version.
For more information about the cf plugins
command, see cf plugins in the Cloud Foundry CLI Reference Guide.
To uninstall a plugin:
View the names of all installed plugins by running:
cf plugins
Run:
cf uninstall-plugin PLUGIN-NAME
Where PLUGIN-NAME
is the name of the plug-in you want to uninstall.
You must use the name of the plug-in, not the binary filename, to uninstall it.
For more information, see uninstall-plugin in the Cloud Foundry CLI Reference Guide.
To add a plugin repository:
Run:
cf add-plugin-repo REPOSITORY-NAME-URL
Where REPOSITORY-NAME-URL
is the URL of the plug-in repository that you want to add.
For more information, see add-plugin-repo in the Cloud Foundry CLI Reference Guide.
To view your available plugin repositories:
Run:
cf list-plugin-repos
For more information, see list-plugin-repos in the Cloud Foundry CLI Reference Guide.
To show all plugins from all available repositories:
Run:
cf repo-plugins
For more information, see repo-plugins in the Cloud Foundry CLI Reference Guide.
The cf CLI provides the following error messages to help you troubleshoot installation and usage issues. Third-party plug-ins provide their own error messages.
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 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.