@oclif/plugin-plugins

plugins plugin for oclif

• What is this?
• Usage
• Friendly names
• Aliases
• Commands

What is this?

This plugin is used to allow users to install plugins into your oclif CLI at runtime. For example, in the VTEX CLI this is used to allow people to install plugins such as the VTEX Autoupdate plugin:

$ vtex plugins install autoupdate
$ vtex autoupdate

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.

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.

Usage

First add the plugin to your project with yarn add @oclif/plugin-plugins, then add it to the package.json of the oclif CLI:

{
  "name": "mycli",
  "version": "0.0.0",
  // ...
  "oclif": {
    "plugins": ["@oclif/plugin-help", "@oclif/plugin-plugins"]
  }
}

Now the user can run any of the commands below to manage plugins at runtime.

Friendly names

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.

To set this up, simply set the oclif.scope to the name of your npm org. In the example above, this would be mynpmorg.

Aliases

Over time in the VTEX 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.

For renaming plugins, add an alias section to oclif.aliases in package.json:

"aliases": {
  "old-name-plugin": "new-name-plugin"
}

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.

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:

"aliases": {
  "old-name-plugin": null
}

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.

Commands

• vtex plugins install PLUGIN
• vtex plugins link PLUGIN
• vtex plugins:list
• vtex plugins source PLUGIN
• vtex plugins uninstall PLUGIN
• vtex plugins:update

vtex plugins install PLUGIN

Installs a plugin into the CLI.

USAGE
  $ vtex plugins install PLUGIN

ARGUMENTS
  PLUGIN  plugin to install

OPTIONS
  -f, --force    Refetches all packages, even the ones that were previously installed.
  -h, --help     show CLI help
  -v, --verbose

ALIASES
  $ vtex plugins:add

EXAMPLES
  vtex plugins install lighthouse
  vtex plugins install https://github.com/vtex/cli-plugin-someplugin
  vtex plugins install @vtex/cli-plugin-someplugin

See code: src/commands/plugins/install.ts

vtex plugins link PLUGIN

Links a plugin into the CLI for development.

USAGE
  $ vtex plugins link PLUGIN

ARGUMENTS
  PATH  [default: .] Plugin path.

OPTIONS
  -h, --help     show CLI help
  -v, --verbose

EXAMPLE
  vtex plugins link myplugin

See code: src/commands/plugins/link.ts

vtex plugins:list

Lists all plugins installed on your machine.

USAGE
  $ vtex plugins:list

OPTIONS
  --core  Shows core plugins.

EXAMPLE
  vtex plugins list

See code: src/commands/plugins/list.ts

vtex plugins source PLUGIN

Lists all plugins supported by VTEX.

USAGE
  $ vtex plugins source PLUGIN

ARGUMENTS
  PATH  [default: .] Plugin path.

OPTIONS
  -h, --help     show CLI help
  -v, --verbose

EXAMPLE
  vtex plugins source myplugin

See code: src/commands/plugins/source.ts

vtex plugins uninstall PLUGIN

Removes a plugin from the CLI

USAGE
  $ vtex plugins uninstall PLUGIN

ARGUMENTS
  PLUGIN  Plugin to uninstall.

OPTIONS
  -h, --help     show CLI help
  -v, --verbose

ALIASES
  $ vtex plugins:unlink
  $ vtex plugins:remove

See code: src/commands/plugins/uninstall.ts

vtex plugins:update

Updates all plugins installed on your machine.

USAGE
  $ vtex plugins:update

OPTIONS
  -h, --help     show CLI help
  -v, --verbose

See code: src/commands/plugins/update.ts