doc(spec): add subcommands to Notation plugin spec (notaryproject#555)

Spec changes to improve the UX for plugin installation and removal using the NotationCLI. --------- Signed-off-by: Josh Duffney <[email protected]> Signed-off-by: GitHub <[email protected]> Co-authored-by: Shiwei Zhang <[email protected]> Signed-off-by: Josh Duffney <[email protected]>
duffney · Mar 30, 2023 · c7652cc · c7652cc
1 parent 1bf0449
commit c7652cc
Showing 1 changed file with 44 additions and 3 deletions.
diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md
@@ -16,6 +16,8 @@ Usage:
 
 Available Commands:
   list        List installed plugins
+  install     Installs a plugin
+  remove      Removes a plugin
 
 Flags:
   -h, --help          help for plugin
@@ -36,15 +38,54 @@ Aliases:
   list, ls
 ```
 
+### notation plugin install
+
+```text
+Installs a plugin
+
+Usage:
+  notation plugin install [flags] <plugin path>
+
+Flags:
+  -h, --help                    help for install
+  -f, --force                   force the installation of a plugin
+
+Aliases:
+  install, add
+```
+
+### notation plugin remove 
+
+```text
+Removes a plugin
+
+Usage:
+  notation plugin remove [flags] <plugin name>
+
+Flags:
+  -h, --help          help for remove
+
+Aliases:
+  remove, rm, uninstall, delete
+```
+
 ## Usage
 
 ### Install a plugin
 
-Currently there is no subcommand available for plugin installation. Plugin publisher should provide instructions to download and install the plugin.
+```shell
+notation plugin install <plugin path>
+```
+
+Upon successful execution, the plugin is copied to plugins directory and name+version of plugin is displayed. If the plugin directory does not exist, it will be created. When an existing plugin is detected, the versions are compared and if the existing plugin is a lower version then it is replaced by the newer version.
 
 ### Uninstall a plugin
 
-Currently there is no subcommand available for plugin un-installation. Plugin publisher should provide instructions to uninstall the plugin.
+```shell
+notation plugin remove <plugin name>
+```
+
+Upon successful execution, the plugin is removed from the plugins directory. If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins.
 
 ### List installed plugins
 
@@ -58,5 +99,5 @@ An example of output from `notation plugin list`:
 
 ```text
 NAME       DESCRIPTION                                   VERSION             CAPABILITIES                ERROR
-azure-kv   Sign artifacts with keys in Azure Key Vault   v0.3.1-alpha.1      [SIGNATURE_GENERATOR.RAW]   <nil>
+azure-kv   Sign artifacts with keys in Azure Key Vault   v0.5.0-rc.1     [SIGNATURE_GENERATOR.RAW]   <nil>
 ```