doc: add examples in CLI help doc for notation sign and verify (notar…

…yproject#384) fix notaryproject#383 Signed-off-by: Feynman Zhou <[email protected]>
FeynmanZhou · Oct 14, 2022 · b9f1fb5 · b9f1fb5
1 parent 9a65243
commit b9f1fb5
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 4 deletions.
diff --git a/cmd/notation/common.go b/cmd/notation/common.go
@@ -16,7 +16,7 @@ var (
 	flagUsername = &pflag.Flag{
 		Name:      "username",
 		Shorthand: "u",
-		Usage:     "Username for registry operations (default from $NOTATION_USERNAME)",
+		Usage:     "username for registry operations (if not specified, defaults to $NOTATION_USERNAME)",
 	}
 	setflagUsername = func(fs *pflag.FlagSet, p *string) {
 		fs.StringVarP(p, flagUsername.Name, flagUsername.Shorthand, "", flagUsername.Usage)
@@ -25,7 +25,7 @@ var (
 	flagPassword = &pflag.Flag{
 		Name:      "password",
 		Shorthand: "p",
-		Usage:     "Password for registry operations (default from $NOTATION_PASSWORD)",
+		Usage:     "password for registry operations (if not specified, defaults to $NOTATION_PASSWORD)",
 	}
 	setFlagPassword = func(fs *pflag.FlagSet, p *string) {
 		fs.StringVarP(p, flagPassword.Name, flagPassword.Shorthand, "", flagPassword.Usage)

diff --git a/cmd/notation/sign.go b/cmd/notation/sign.go
@@ -34,7 +34,26 @@ func signCommand(opts *signOpts) *cobra.Command {
 	}
 	command := &cobra.Command{
 		Use:   "sign [reference]",
-		Short: "Signs artifacts",
+		Short: "Sign OCI artifacts",
+		Long: `Sign OCI artifacts
+
+Prerequisite: a signing key needs to be configured using the command "notation key".
+
+Example - Sign a container image using the default signing key, with the default JWS envelope:
+  notation sign <registry>/<repository>:<tag>
+
+Example - Sign a container image using the default signing key, with the COSE envelope:
+  notation sign --envelope-type cose <registry>/<repository>:<tag> 
+
+Example - Sign a container image using the specified key name
+  notation sign --key <key_name> <registry>/<repository>:<tag>
+
+Example - Sign a container image using a local testing key and certificate file directly
+  notation sign --key-file <key_path> --cert-file <cert_path> <registry>/<repository>:<tag>
+
+Example - Sign a container image using the image digest
+  notation sign <registry>/<repository>@<digest>
+`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
 				return errors.New("missing reference")

diff --git a/cmd/notation/verify.go b/cmd/notation/verify.go
@@ -34,7 +34,20 @@ func verifyCommand(opts *verifyOpts) *cobra.Command {
 	}
 	command := &cobra.Command{
 		Use:   "verify [reference]",
-		Short: "Verifies OCI Artifacts",
+		Short: "Verify OCI artifacts",
+		Long: `Verify OCI artifacts
+
+Prerequisite: a trusted certificate needs to be generated or added using the command "notation cert". 
+
+Example - Verify a signature using the trusted certificate:
+  notation verify <registry>/<repository>:<tag>
+
+Example - Verify a signature associated with an OCI artifact identified by the digest:
+  notation verify <registry>/<repository>@<digest>
+
+Example - Verify a signature using a trusted certificate in a specified path:
+  notation verify --cert-file <cert_path> <registry>/<repository>:<tag>
+`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
 				return errors.New("missing reference")