forked from cloudfoundry/docs-cf-cli
/
use-cli-plugins.html.md.erb
165 lines (97 loc) · 6.61 KB
/
use-cli-plugins.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
---
title: Using cf CLI Plugins
owner: CLI
---
This topic describes using Cloud Foundry Command Line Interface (cf CLI) plugins.
## <a id='overview'></a> Overview
The cf CLI 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. For a current list of community-supported plugins, see the [Cloud Foundry Community CLI Plugin page](https://plugins.cloudfoundry.org). For information about submitting your own plugin, see the [Cloud Foundry CLI Plugin Repository (CLIPR)](https://github.com/cloudfoundry-incubator/cli-plugin-repo) repository on GitHub.
<p class='note warning'><strong>Warning:</strong> Plugins are not vetted in any way, including for security or functionality. Use plugins at your own risk.</p>
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.
<p class="note"><strong>Note:</strong> The cf CLI uses case-sensitive commands, but plugin management commands accept plugin and repository names irrespective of their casing.</p>
## <a id="plugin-directory"></a> Change the Plugin Directory
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 plugins in that location. For example, if you set `CF_PLUGIN_HOME` to `/my-folder`, cf CLI stores plugins in `/my-folder/.cf/plugins`.
## <a id="plugin-install"></a> Install a Plugin
To install a plugin:
1. Download a binary or the source code for a plugin from a trusted provider.
<p class="note"><strong>Note:</strong> 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.</p>
1. Run:
```
cf install-plugin BINARY-FILENAME
```
Where `BINARY-FILENAME` is the path to and name of your binary file.
<p class="note"><strong>Note:</strong> You cannot install a plugin that has the same name or that uses the same command as an existing plugin. If you attempt to do so, you are prompted to uninstall the existing plugin.</p>
<p class="note"><strong>Note:</strong> 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 <code>cf push</code> command, the cf CLI halts the installation.</p>
For more information, see [install-plugin](http://cli.cloudfoundry.org/en-US/cf/install-plugin.html) in the _Cloud Foundry CLI Reference Guide_.
## <a id="plugin-run-cmd"></a> Manage Plugins and Run Plugin Commands
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:
1. List all installed plugins and all commands that the plugins provide by running:
```
cf plugins
```
1. Execute a plugin command by running:
```
cf PLUGIN-COMMAND
```
Where `PLUGIN-COMMAND` is the plugin command you want to execute.
## <a id="plugins-outdated"></a> Check for Plugin Updates
To check all registered plugin repositories for newer versions of currently installed plugins:
1. Run:
```
cf plugins --outdated
```
1. See the output of the above command, as in the example below:
<pre class="terminal">
$ 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.
</pre>
For more information about the `cf plugins` command, see [cf plugins](http://cli.cloudfoundry.org/en-US/cf/plugins.html) in the _Cloud Foundry CLI Reference Guide_.
## <a id="plugin-uninstall"></a> Uninstall a Plugin
To uninstall a plugin:
1. View the names of all installed plugins by running:
```
cf plugins
```
1. Run:
```
cf uninstall-plugin PLUGIN-NAME
```
Where `PLUGIN-NAME` is the name of the plugin you want to uninstall.
<p class='note'><strong>Note:</strong> You must use the name of the plugin to uninstall it, not the binary filename.</p>
For more information, see [uninstall-plugin](http://cli.cloudfoundry.org/en-US/cf/uninstall-plugin.html) in the _Cloud Foundry CLI Reference Guide_.
## <a id="adding-plugin-repo"></a> Add a Plugin Repository
To add a plugin repository:
1. Run:
```
cf add-plugin-repo REPOSITORY-NAME-URL
```
Where `REPOSITORY-NAME-URL` is the URL of the plugin repository you want to add.
For more information, see [add-plugin-repo](http://cli.cloudfoundry.org/en-US/cf/add-plugin-repo.html) in the _Cloud Foundry CLI Reference Guide_.
## <a id="listing-plugin-repo"></a> List Available Plugin Repositories
To view your available plugin repositories:
1. Run:
```
cf list-plugin-repos
```
For more information, see [list-plugin-repos](http://cli.cloudfoundry.org/en-US/cf/list-plugin-repos.html) in the _Cloud Foundry CLI Reference Guide_.
## <a id="listing-plugin-repo"></a> List All Plugins by Repository
To show all plugins from all available repositories:
1. Run:
```
cf repo-plugins
```
For more information, see [repo-plugins](http://cli.cloudfoundry.org/en-US/cf/repo-plugins.html) in the _Cloud Foundry CLI Reference Guide_.
## <a id="troubleshoot"></a> Troubleshooting
The cf CLI provides the error messages described below to help you troubleshoot installation and usage issues. Third-party plugins can provide their own error messages.
### <a id='permission-denied'></a> 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.
### <a id='plugin-command-collision'></a> 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.