Managing plugins

This section explains how to install, configure, and manage plug-ins for an application that is built on the Imperative CLI Framework.

Your CLI application must have plug-ins enabled at the time of initialization if you want to install, configure, and manage plugins with the commands in this section. For more information about how a CLI developer can enable or disable plug-ins, see [Enable Plug-ins].

• How Plug-ins Work
• Plugins Command Group

How Plug-ins Work

The Plugin Management Facility (PMF) maintains plug-ins implemented under Imperative CLI Framework. The developer of your CLI application must enable the PMF.

You can use commands in the plugins command group to interact with the PMF, if the PMF is enabled.

Plugins.json

Plugins.json is the file that Imperative CLI Framework uses to manage and load installed plug-ins. Every plug-in has a package.json file that contains the code structure of the plug-in.

Use commands in the plugins command group to register the package that is defined in package.json in plugins.json.

How Plug-in Validation Works

Before you install a plug-in, understand how the PMF verifies that the plug-in integrates with the application.

1. You issue a cli plugins install command to install the plug-in to an application.
2. The PMF registers the plug-in in plugins.json.
3. A user issues a command from the command line that initializes the application.
4. The PMF verifies that the structure of each plug-in is correct and that plug-in commands do not conflict with existing functionality or with other plug-ins. The PMF presents error messages during validation when a plug-in does not integrate with existing functionality.

How to Validate a Plug-in Manually

After you install a plug-in to a CLI application, you can issue the following command at any time to run validation against the plug-in: cli plugins validate

The command response provides you with details or error messages about how a plug-in integrates with the application.

Plugins Command Group

When your CLI has plug-ins enabled, a command group named plugin is added to the base CLI by the Imperative CLI Framework. The plugins command group lets you to manage plug-in packages for your application.

Note: If your CLI does NOT have plug-ins enabled, the plugins command group is not available for use. For more information about how a CLI developer can enable or disable plug-ins, see [Enable Plug-ins].

The plugins group contains the following commands for managing the installed CLI plug-ins:

• install - Install plug-ins.
• list - List installed plug-ins.
• uninstall - Uninstall plug-ins.
• update - Update plug-ins.
• validate - Verify that plug-ins integrate with the base application properly.

The following syntax is the format of a command in the plugins command group, where cli is the root name of the application:

cli plugins <command>

Install Command

The install command lets you install new plug-ins to a base application. After a successful installation, the plugins.json file contains the new plug-in.

A plug-in is a Node Package Manager (npm) package, but it can be stored in npm, in a different registry, or in a folder on your PC.

The command is equivalent to using npm install to install a package.

Install Command Usage

The install command has the following syntax:

cli plugins install [plugin...] [--registry <registry>] [--file <config>]

where:

• [plugin...] is an npm package or a pointer to a URI (either local or remote).
  • Tip: You can specify a version of a plug-in to install, for example cli plugin install plugin@^1.0.0. The specified version is saved in the plugins.json file. If you do not specify a plug-in version, the latest version is installed and given the same prefix that is stored in npm save-prefix. For more information, see npm save prefix. For more information on npm semantic versioning, see npm semver.
  • Tip: You can install multiple plug-ins with one command. For example, cli plugin install plugin1 plugin2 plugin3
• [--registry <registry>] is an optional flag that is similar to the npm install --registry flag.
• [--file <config>] lets you specify which configuration file to use. For example, you could share plug-ins with your team in a custom configuration file. The configuration file should be in the format of a plugin.json file.
  • Tip: If you use this parameter, you should not specify any plug-ins in the command.
  • Tip: If you do not use this parameter and you do not specify any plugins on the command line, this parameter will default to the location of the original plugins.json file. This is useful if you want to restore your plug-ins after a re-install of the base CLI.

List Command

The list command allows you to generate a list of plug-ins that are currently installed to the application.

List Command Usage

The list command has the following syntax:

cli plugins list

There are no positional parameters for the list command.

Uninstall Command

The uninstall command lets you uninstall plug-ins from a base application. After a successful uninstall, the plugins.json file no longer contains the configuration for the plug-in.

The command is equivalent to using npm uninstall to uninstall a package.

Uninstall Command Usage

The uninstall command has the following syntax:

cli plugins uninstall [plugin]

where:

• <plugin> is the name of a plug-in in plugins.json that you want to uninistall.

Update Command

The update command lets you update a plug-in to the most current version. After a successful update, plugins.json file contains the latest version of a plug-in.

The command is equivalent to using npm update to update a package, or using npm install@latest to update a package.

Update Command Usage

The update command has the following syntax:

cli plugins update [plugin...] [--registry <registry>]

where:

• [plugin...] is the name of an installed plug-in package in package.json.
  • Tip: You can use npm semantic versioning to specify a plug-in version to update to. If you do not include a version, the command refers to the plugins.json file to determine the version to update. For more information, see npm semver.
• [--registry <registry>] lets you install a plug-in from a registry that is different from the registry of the original installation. This flag is optional. If you omit this flag, the registry is retrieved from plug-ins.json.

Validate Command

The validate command runs tests against all plug-ins (or against a plug-in that you specify) and verifies that plug-ins integrate with the base application properly. The tests confirm that the plug-in does not conflict with existing command groups in the base application.

We recommend that you issue the validate command when you encounter problems with a plug-in.

Validate Command Usage

The validate command has the following syntax:

cli plugins validate [plugin]

where:

• [plugin] is the name of a plug-in that you want to validate. If you do not specify a plug-in name, all installed plug-ins are validated.

Note: The plug-in name is not always the same as name of the NPM package name.