1 | @oclif/plugin-plugins
|
2 | =====================
|
3 |
|
4 | plugins plugin for oclif
|
5 |
|
6 | [![Version](https://img.shields.io/npm/v/@oclif/plugin-plugins.svg)](https://npmjs.org/package/@oclif/plugin-plugins)
|
7 | [![CircleCI](https://circleci.com/gh/oclif/plugin-plugins/tree/main.svg?style=shield)](https://circleci.com/gh/oclif/plugin-plugins/tree/main)
|
8 | [![Appveyor CI](https://ci.appveyor.com/api/projects/status/github/oclif/plugin-plugins?branch=main&svg=true)](https://ci.appveyor.com/project/oclif/plugin-plugins/branch/main)
|
9 | [![Known Vulnerabilities](https://snyk.io/test/github/oclif/plugin-plugins/badge.svg)](https://snyk.io/test/github/oclif/plugin-plugins)
|
10 | [![Downloads/week](https://img.shields.io/npm/dw/@oclif/plugin-plugins.svg)](https://npmjs.org/package/@oclif/plugin-plugins)
|
11 | [![License](https://img.shields.io/npm/l/@oclif/plugin-plugins.svg)](https://github.com/oclif/plugin-plugins/blob/main/package.json)
|
12 |
|
13 |
|
14 | * [What is this?](#what-is-this)
|
15 | * [Usage](#usage)
|
16 | * [Friendly names](#friendly-names)
|
17 | * [Aliases](#aliases)
|
18 | * [Commands](#commands)
|
19 |
|
20 |
|
21 | # What is this?
|
22 |
|
23 | This plugin is used to allow users to install plugins into your oclif CLI at runtime. For example, in the Heroku CLI this is used to allow people to install plugins such as the Heroku Kafka plugin:
|
24 |
|
25 | ```sh-session
|
26 | $ heroku plugins:install heroku-kafka
|
27 | $ heroku kafka
|
28 | ```
|
29 |
|
30 | This is useful to allow users to create their own plugins to work in your CLI or to allow you to build functionality that users can optionally install.
|
31 |
|
32 | One particular way this is useful is for building functionality you aren't ready to include in a public repository. Build your plugin separately as a plugin, then include it as a core plugin later into your CLI.
|
33 |
|
34 | # Usage
|
35 |
|
36 | First add the plugin to your project with `yarn add @oclif/plugin-plugins`, then add it to the `package.json` of the oclif CLI:
|
37 |
|
38 | ```js
|
39 | {
|
40 | "name": "mycli",
|
41 | "version": "0.0.0",
|
42 | // ...
|
43 | "oclif": {
|
44 | "plugins": ["@oclif/plugin-help", "@oclif/plugin-plugins"]
|
45 | }
|
46 | }
|
47 | ```
|
48 |
|
49 | Now the user can run any of the commands below to manage plugins at runtime.
|
50 |
|
51 | # Friendly names
|
52 |
|
53 | To make it simpler for users to install plugins, we have "friendly name" functionality. With this, you can run `mycli plugins:install myplugin` and it will first check if `@mynpmorg/plugin-myplugin` exists on npm before trying to install `myplugin`. This is useful if you want to use a generic name that's already taken in npm.
|
54 |
|
55 | To set this up, simply set the `oclif.scope` to the name of your npm org. In the example above, this would be `mynpmorg`.
|
56 |
|
57 | # Aliases
|
58 |
|
59 | Over time in the Heroku CLI we've changed plugin names, brought plugins into the core of the CLI, or sunset old plugins that no longer function. There is support in this plugin for dealing with these situations.
|
60 |
|
61 | For renaming plugins, add an alias section to `oclif.aliases` in `package.json`:
|
62 |
|
63 | ```json
|
64 | "aliases": {
|
65 | "old-name-plugin": "new-name-plugin"
|
66 | }
|
67 | ```
|
68 |
|
69 | If a user had `old-name-plugin` installed, the next time the CLI is updated it will remove `old-name-plugin` and install `new-name-plugin`. If a user types `mycli plugins:install old-name-plugin` it will actually install `new-name-plugin` instead.
|
70 |
|
71 | For removing plugins that are no longer needed (either because they're sunset or because they've been moved into core), set the alias to null:
|
72 |
|
73 | ```json
|
74 | "aliases": {
|
75 | "old-name-plugin": null
|
76 | }
|
77 | ```
|
78 |
|
79 | `old-name-plugin` will be autoremoved on the next update and will not be able to be installed with `mycli plugins:install old-name-plugin`.
|
80 |
|
81 | # Commands
|
82 |
|
83 | * [`mycli plugins`](#mycli-plugins)
|
84 | * [`mycli plugins:inspect PLUGIN...`](#mycli-pluginsinspect-plugin)
|
85 | * [`mycli plugins:install PLUGIN...`](#mycli-pluginsinstall-plugin)
|
86 | * [`mycli plugins:link PLUGIN`](#mycli-pluginslink-plugin)
|
87 | * [`mycli plugins:uninstall PLUGIN...`](#mycli-pluginsuninstall-plugin)
|
88 | * [`mycli plugins:update`](#mycli-pluginsupdate)
|
89 |
|
90 | ## `mycli plugins`
|
91 |
|
92 | List installed plugins.
|
93 |
|
94 | ```
|
95 | USAGE
|
96 | $ mycli plugins [--core]
|
97 |
|
98 | FLAGS
|
99 | --core Show core plugins.
|
100 |
|
101 | DESCRIPTION
|
102 | List installed plugins.
|
103 |
|
104 | EXAMPLES
|
105 | $ mycli plugins
|
106 | ```
|
107 |
|
108 | _See code: [src/commands/plugins/index.ts](https://github.com/oclif/plugin-plugins/blob/v2.1.0/src/commands/plugins/index.ts)_
|
109 |
|
110 | ## `mycli plugins:inspect PLUGIN...`
|
111 |
|
112 | Displays installation properties of a plugin.
|
113 |
|
114 | ```
|
115 | USAGE
|
116 | $ mycli plugins:inspect PLUGIN...
|
117 |
|
118 | ARGUMENTS
|
119 | PLUGIN [default: .] Plugin to inspect.
|
120 |
|
121 | FLAGS
|
122 | -h, --help Show CLI help.
|
123 | -v, --verbose
|
124 |
|
125 | DESCRIPTION
|
126 | Displays installation properties of a plugin.
|
127 |
|
128 | EXAMPLES
|
129 | $ mycli plugins:inspect myplugin
|
130 | ```
|
131 |
|
132 | _See code: [src/commands/plugins/inspect.ts](https://github.com/oclif/plugin-plugins/blob/v2.1.0/src/commands/plugins/inspect.ts)_
|
133 |
|
134 | ## `mycli plugins:install PLUGIN...`
|
135 |
|
136 | Installs a plugin into the CLI.
|
137 |
|
138 | ```
|
139 | USAGE
|
140 | $ mycli plugins:install PLUGIN...
|
141 |
|
142 | ARGUMENTS
|
143 | PLUGIN Plugin to install.
|
144 |
|
145 | FLAGS
|
146 | -f, --force Run yarn install with force flag.
|
147 | -h, --help Show CLI help.
|
148 | -v, --verbose
|
149 |
|
150 | DESCRIPTION
|
151 | Installs a plugin into the CLI.
|
152 |
|
153 | Can be installed from npm or a git url.
|
154 |
|
155 | Installation of a user-installed plugin will override a core plugin.
|
156 |
|
157 | e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
|
158 | will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
|
159 | the CLI without the need to patch and update the whole CLI.
|
160 |
|
161 | ALIASES
|
162 | $ mycli plugins:add
|
163 |
|
164 | EXAMPLES
|
165 | $ mycli plugins:install myplugin
|
166 |
|
167 | $ mycli plugins:install https://github.com/someuser/someplugin
|
168 |
|
169 | $ mycli plugins:install someuser/someplugin
|
170 | ```
|
171 |
|
172 | _See code: [src/commands/plugins/install.ts](https://github.com/oclif/plugin-plugins/blob/v2.1.0/src/commands/plugins/install.ts)_
|
173 |
|
174 | ## `mycli plugins:link PLUGIN`
|
175 |
|
176 | Links a plugin into the CLI for development.
|
177 |
|
178 | ```
|
179 | USAGE
|
180 | $ mycli plugins:link PLUGIN
|
181 |
|
182 | ARGUMENTS
|
183 | PATH [default: .] path to plugin
|
184 |
|
185 | FLAGS
|
186 | -h, --help Show CLI help.
|
187 | -v, --verbose
|
188 |
|
189 | DESCRIPTION
|
190 | Links a plugin into the CLI for development.
|
191 |
|
192 | Installation of a linked plugin will override a user-installed or core plugin.
|
193 |
|
194 | e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
|
195 | command will override the user-installed or core plugin implementation. This is useful for development work.
|
196 |
|
197 | EXAMPLES
|
198 | $ mycli plugins:link myplugin
|
199 | ```
|
200 |
|
201 | _See code: [src/commands/plugins/link.ts](https://github.com/oclif/plugin-plugins/blob/v2.1.0/src/commands/plugins/link.ts)_
|
202 |
|
203 | ## `mycli plugins:uninstall PLUGIN...`
|
204 |
|
205 | Removes a plugin from the CLI.
|
206 |
|
207 | ```
|
208 | USAGE
|
209 | $ mycli plugins:uninstall PLUGIN...
|
210 |
|
211 | ARGUMENTS
|
212 | PLUGIN plugin to uninstall
|
213 |
|
214 | FLAGS
|
215 | -h, --help Show CLI help.
|
216 | -v, --verbose
|
217 |
|
218 | DESCRIPTION
|
219 | Removes a plugin from the CLI.
|
220 |
|
221 | ALIASES
|
222 | $ mycli plugins:unlink
|
223 | $ mycli plugins:remove
|
224 | ```
|
225 |
|
226 | _See code: [src/commands/plugins/uninstall.ts](https://github.com/oclif/plugin-plugins/blob/v2.1.0/src/commands/plugins/uninstall.ts)_
|
227 |
|
228 | ## `mycli plugins:update`
|
229 |
|
230 | Update installed plugins.
|
231 |
|
232 | ```
|
233 | USAGE
|
234 | $ mycli plugins:update [-h] [-v]
|
235 |
|
236 | FLAGS
|
237 | -h, --help Show CLI help.
|
238 | -v, --verbose
|
239 |
|
240 | DESCRIPTION
|
241 | Update installed plugins.
|
242 | ```
|
243 |
|
244 | _See code: [src/commands/plugins/update.ts](https://github.com/oclif/plugin-plugins/blob/v2.1.0/src/commands/plugins/update.ts)_
|
245 |
|