spec: add CLI specs for notation list/login/logout/plugin (notaryproj…

…ect#362)

Signed-off-by: Yi Zha <[email protected]>

specs/commandline/list.md

@@ -0,0 +1,51 @@
+# notation list
+
+## Description
+
+Use `notation list` to list all the signatures associated with signed artifact.
+
+`Tags` are mutable, but `Digests` uniquely and immutably identify an artifact. If a tag is used to identify a signed artifact, notation resolves the tag to the `digest` first.
+
+Upon successful execution, both the digest of the signed artifact and the digests of signatures associated with signed artifact are printed out as following:
+
+```shell
+<registry>/<repository>@<digest>
+└── application/vnd.cncf.notary.v2.signature
+    ├──<digest_of_signature>
+    └──<digest_of_signature>
+```
+
+## Outline
+
+```text
+List all the signatures associated with signed artifact
+
+Usage:
+  notation list [flags] <reference>
+
+Aliases:
+  list, ls
+
+Flags:
+  -h, --help              help for list
+  -p, --password string   password for registry operations (default to $NOTATION_PASSWORD if not specified)
+      --plain-http        registry access via plain HTTP
+  -u, --username string   username for registry operations (default to $NOTATION_USERNAME if not specified)
+```
+
+## Usage
+
+### List all the signatures of the signed container image
+
+```text
+notation list <registry>/<repository>:<tag>
+```
+
+An example output:
+
+```shell
+localhost:5000/net-monitor:v1
+└── application/vnd.cncf.notary.v2.signature
+    ├── sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    └── sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+```

specs/commandline/login.md

@@ -0,0 +1,37 @@
+# notation login
+
+## Description
+
+Use `notation login` to log in to an OCI registry. Users can execute `notation login` multiple times to log in multiple registries.
+
+## Outline
+
+```text
+Log in to an OCI registry
+
+Usage:
+  notation login [flags] <server>
+
+Flags:
+  -h, --help              help for login
+  -p, --password string   password for registry operations (default to $NOTATION_PASSWORD if not specified)
+      --password-stdin    take the password from stdin
+      --plain-http        registry access via plain HTTP
+  -u, --username string   username for registry operations (default to $NOTATION_USERNAME if not specified)
+```
+
+## Usage
+
+### Log in with provided username and password
+
+```shell
+notation login -u <username> -p <password> registry.example.com
+```
+
+### Log in using $NOTATION_USERNAME $NOTATION_PASSWORD variables
+
+```shell
+# Prerequisites:
+# set environment variable NOTATION_USERNAME and NOTATION_PASSWORD
+notation login registry.example.com
+```

specs/commandline/logout.md

@@ -0,0 +1,33 @@
+# notation logout
+
+## Description
+
+Use `notation logout` to log out from an OCI registry.
+
+## Outline
+
+```text
+Log out from an OCI registry
+
+Usage:
+  notation logout [flags] [server]
+
+Flags:
+      --all           log out from all logged in registries
+  -h, --help          help for logout
+      --plain-http    registry access via plain HTTP
+```
+
+## Usage
+
+### Log out from an OCI registry
+
+```shell
+notation logout registry.example.com
+```
+
+### Log out from all logged in registries
+
+```shell
+notation logout --all
+```

specs/commandline/plugin.md

@@ -0,0 +1,64 @@
+# notation plugin
+
+## Description
+
+Use `notation plugin` to manage plugins. See notation [plugin documentation](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. The `notation plugin` command by itself performs no action. In order to operate on a plugin, one of the subcommands must be used.
+
+## Outline
+
+### notation plugin
+
+```text
+Manage plugins
+
+Usage:
+  notation plugin <command>
+
+Available Commands:
+  list        List installed plugins
+
+Flags:
+  -h, --help          help for plugin
+
+RUN 'notation plugin <command> --help' for more information on a command.
+```
+
+### notation plugin list
+
+```text
+List installed plugins
+
+Usage:
+  notation plugin list [flags]
+
+Flags:
+  -h, --help          help for list
+
+Aliases:
+  list, ls
+```
+
+## Usage
+
+### Install a plugin
+
+Currently there is no subcommand available for plugin installation. Plugin publisher should provide instructions to download and install the plugin.
+
+### Uninstall a plugin
+
+Currently there is no subcommand available for plugin un-installation. Plugin publisher should provide instructions to uninstall the plugin.
+
+### List installed plugins
+
+```shell
+notation plugin list
+```
+
+Upon successful execution, a list of plugins are printed out with information of name, description, version, capabilities and errors. The capabilities show what the plugin is capable of, for example, the plugin can generate signatures or verify signatures. The errors column indicates whether the plugin was installed properly or not. `<nil>` of Error indicates that the plugin installed successfully.
+
+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>
+```