From 56945b3c80bb5dae000fdfc81d5f8ca13e6af5a1 Mon Sep 17 00:00:00 2001
From: Josh Duffney <jduffney@microsoft.com>
Date: Tue, 28 Mar 2023 21:52:45 -0500
Subject: [PATCH] doc(spec): add subcommands to Notation plugin spec (#555)

Spec changes to improve the UX for plugin installation and removal using
the NotationCLI.

---------

Signed-off-by: Josh Duffney <jduffney@microsoft.com>
Signed-off-by: GitHub <noreply@github.com>
Co-authored-by: Shiwei Zhang <shizh@microsoft.com>
---
 specs/commandline/plugin.md | 47 ++++++++++++++++++++++++++++++++++---
 1 file changed, 44 insertions(+), 3 deletions(-)

diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md
index 5e17f62ae..58aeddd4e 100644
--- 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>
 ```