doc: refine CLI help doc (#619)

Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>

cmd/oras/attach.go

@@ -59,9 +59,11 @@ Example - Attach file 'hi.txt' and add annotations from file 'annotation.json'
 Example - Attach an artifact with manifest annotations
   oras attach --artifact-type doc/example --annotation "key1=val1" --annotation "key2=val2" localhost:5000/hello:latest
 
-Example - Attach a file and add manifest annotations
+Example - Attach file 'hi.txt' and add manifest annotations
   oras attach --artifact-type doc/example --annotation "key=val" localhost:5000/hello:latest hi.txt
 
+Example - Attach file 'hi.txt' and export the pushed manifest to 'manifest.json'
+  oras attach --artifact-type doc/example --export-manifest manifest.json localhost:5000/hello:latest hi.txt
 `,
 		Args: cobra.MinimumNArgs(1),
 		PreRunE: func(cmd *cobra.Command, args []string) error {

cmd/oras/blob/fetch.go

@@ -51,13 +51,13 @@ func fetchCmd() *cobra.Command {
 Example - Fetch the blob and save it to a local file:
   oras blob fetch --output blob.tar.gz localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
 
-Example - Fetch the blob and stdout the raw blob content:
+Example - Fetch the blob and print the raw blob content:
   oras blob fetch --output - localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
 
-Example - Fetch and stdout the descriptor of a blob:
+Example - Fetch and print the descriptor of a blob:
   oras blob fetch --descriptor localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
 
-Example - Fetch the blob, save it to a local file and stdout the descriptor:
+Example - Fetch the blob, save it to a local file and print the descriptor:
   oras blob fetch --output blob.tar.gz --descriptor localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
 `,
 		Args: cobra.ExactArgs(1),
@@ -79,7 +79,7 @@ Example - Fetch the blob, save it to a local file and stdout the descriptor:
 		},
 	}
 
-	cmd.Flags().StringVarP(&opts.outputPath, "output", "o", "", "output file path")
+	cmd.Flags().StringVarP(&opts.outputPath, "output", "o", "", "output file `path`, use - for stdout")
 	option.ApplyFlags(&opts, cmd.Flags())
 	return cmd
 }

cmd/oras/copy.go

@@ -52,19 +52,19 @@ func copyCmd() *cobra.Command {
 
 ** This command is in preview and under development. **
 
-Example - Copy the artifact tagged 'v1' from repository 'localhost:5000/net-monitor' to repository 'localhost:5000/net-monitor-copy' 
+Example - Copy the artifact tagged with 'v1' from repository 'localhost:5000/net-monitor' to repository 'localhost:5000/net-monitor-copy' 
   oras copy localhost:5000/net-monitor:v1 localhost:5000/net-monitor-copy:v1
 
-Example - Copy the artifact tagged 'v1' and its referrers from repository 'localhost:5000/net-monitor' to 'localhost:5000/net-monitor-copy'
+Example - Copy the artifact tagged with 'v1' and its referrers from repository 'localhost:5000/net-monitor' to 'localhost:5000/net-monitor-copy'
   oras copy -r localhost:5000/net-monitor:v1 localhost:5000/net-monitor-copy:v1
 
-Example - Copy the artifact tagged 'v1' from repository 'localhost:5000/net-monitor' to 'localhost:5000/net-monitor-copy' with certain platform
+Example - Copy the artifact tagged with 'v1' from repository 'localhost:5000/net-monitor' to 'localhost:5000/net-monitor-copy' with certain platform
   oras copy --platform linux/arm/v5 localhost:5000/net-monitor:v1 localhost:5000/net-monitor-copy:v1 
 
-Example - Copy the artifact tagged 'v1' from repository 'localhost:5000/net-monitor' to 'localhost:5000/net-monitor-copy' with multiple tags
+Example - Copy the artifact tagged with 'v1' from repository 'localhost:5000/net-monitor' to 'localhost:5000/net-monitor-copy' with multiple tags
   oras copy localhost:5000/net-monitor:v1 localhost:5000/net-monitor-copy:v1,tag2,tag3
 
-Example - Copy the artifact tagged 'v1' from repository 'localhost:5000/net-monitor' to 'localhost:5000/net-monitor-copy' with multiple tags and concurrency level tuned
+Example - Copy the artifact tagged with 'v1' from repository 'localhost:5000/net-monitor' to 'localhost:5000/net-monitor-copy' with multiple tags and concurrency level tuned
   oras copy --concurrency 6 localhost:5000/net-monitor:v1 localhost:5000/net-monitor-copy:v1,tag2,tag3
 `,
 		Args: cobra.ExactArgs(2),
@@ -77,7 +77,7 @@ Example - Copy the artifact tagged 'v1' from repository 'localhost:5000/net-moni
 		},
 	}
 
-	cmd.Flags().BoolVarP(&opts.recursive, "recursive", "r", false, "recursively copy artifacts and its referrer artifacts")
+	cmd.Flags().BoolVarP(&opts.recursive, "recursive", "r", false, "recursively copy the artifact and its referrer artifacts")
 	opts.src.ApplyFlagsWithPrefix(cmd.Flags(), "from", "source")
 	opts.dst.ApplyFlagsWithPrefix(cmd.Flags(), "to", "destination")
 	cmd.Flags().Int64VarP(&opts.concurrency, "concurrency", "", 3, "concurrency level")

cmd/oras/discover.go

@@ -54,7 +54,7 @@ func discoverCmd() *cobra.Command {
 Example - Discover direct referrers of manifest 'hello:latest' in registry 'localhost:5000':
   oras discover localhost:5000/hello
 
-Example - Discover all the referrers of manifest 'hello:latest' in registry 'localhost:5000' in a tree view:
+Example - Discover all the referrers of manifest 'hello:latest' in registry 'localhost:5000' and display in a tree view:
   oras discover -o tree localhost:5000/hello
 
 Example - Discover referrers with type 'test-artifact' of manifest 'hello:latest' in registry 'localhost:5000':

cmd/oras/internal/option/packer.go

@@ -52,7 +52,7 @@ type Packer struct {
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *Packer) ApplyFlags(fs *pflag.FlagSet) {
-	fs.StringVarP(&opts.ManifestExportPath, "export-manifest", "", "", "export the pushed manifest")
+	fs.StringVarP(&opts.ManifestExportPath, "export-manifest", "", "", "`path` of the pushed manifest")
 	fs.StringArrayVarP(&opts.ManifestAnnotations, "annotation", "a", nil, "manifest annotations")
 	fs.StringVarP(&opts.AnnotationFilePath, "annotation-file", "", "", "path of the annotation file")
 	fs.BoolVarP(&opts.PathValidationDisabled, "disable-path-validation", "", false, "skip path validation")

cmd/oras/internal/option/remote.go

@@ -74,7 +74,7 @@ func (opts *Remote) ApplyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description
 	fs.StringVarP(&opts.CACertFilePath, flagPrefix+"ca-file", "", "", "server certificate authority file for the remote "+notePrefix+"registry")
 
 	if fs.Lookup("registry-config") == nil {
-		fs.StringArrayVarP(&opts.Configs, "registry-config", "", nil, "auth config path")
+		fs.StringArrayVarP(&opts.Configs, "registry-config", "", nil, "`path` of the authentication file")
 	}
 }
 

cmd/oras/login.go

@@ -41,22 +41,22 @@ func loginCmd() *cobra.Command {
 		Short: "Log in to a remote registry",
 		Long: `Log in to a remote registry
 
-Example - Login with username and password from command line:
+Example - Log in with username and password from command line flags:
   oras login -u username -p password localhost:5000
 
-Example - Login with username and password from stdin:
+Example - Log in with username and password from stdin:
   oras login -u username --password-stdin localhost:5000
 
-Example - Login with identity token from command line:
+Example - Log in with identity token from command line flags:
   oras login -p token localhost:5000
 
-Example - Login with identity token from stdin:
+Example - Log in with identity token from stdin:
   oras login --password-stdin localhost:5000
 
-Example - Login with username and password by prompt:
+Example - Log in with username and password in an interactive terminal:
   oras login localhost:5000
 
-Example - Login with insecure registry from command line:
+Example - Log in with username and password in an interactive terminal and no TLS check:
   oras login --insecure localhost:5000
 `,
 		Args: cobra.ExactArgs(1),

cmd/oras/manifest/fetch.go

@@ -80,7 +80,7 @@ Example - Fetch manifest with prettified json result:
 	}
 
 	cmd.Flags().StringSliceVarP(&opts.mediaTypes, "media-type", "", nil, "accepted media types")
-	cmd.Flags().StringVarP(&opts.outputPath, "output", "o", "", "output file path")
+	cmd.Flags().StringVarP(&opts.outputPath, "output", "o", "", "file `path` to write the fetched manifest to, use - for stdout")
 	option.ApplyFlags(&opts, cmd.Flags())
 	return cmd
 }

cmd/oras/manifest/fetch_config.go

@@ -84,7 +84,7 @@ Example - Fetch and print the prettified descriptor of the config:
 		},
 	}
 
-	cmd.Flags().StringVarP(&opts.outputPath, "output", "o", "", "output file path")
+	cmd.Flags().StringVarP(&opts.outputPath, "output", "o", "", "file `path` to write the fetched config to, use - for stdout")
 	option.ApplyFlags(&opts, cmd.Flags())
 	return cmd
 }

cmd/oras/push.go

@@ -54,19 +54,22 @@ func pushCmd() *cobra.Command {
 		Short: "Push files to remote registry",
 		Long: `Push files to remote registry
 
-Example - Push file "hi.txt" with the "application/vnd.oci.image.layer.v1.tar" media type (default):
+Example - Push file "hi.txt" with media type "application/vnd.oci.image.layer.v1.tar" (default):
   oras push localhost:5000/hello:latest hi.txt
 
-Example - Push file "hi.txt" with the custom "application/vnd.me.hi" media type:
+Example - Push file "hi.txt" and export the pushed manifest to a specified path
+  oras push --export-manifest manifest.json localhost:5000/hello:latest hi.txt
+
+Example - Push file "hi.txt" with the custom media type "application/vnd.me.hi":
   oras push localhost:5000/hello:latest hi.txt:application/vnd.me.hi
 
 Example - Push multiple files with different media types:
   oras push localhost:5000/hello:latest hi.txt:application/vnd.me.hi bye.txt:application/vnd.me.bye
 
-Example - Push file "hi.txt" with "application/vnd.me.config" as config type:
+Example - Push file "hi.txt" with config type "application/vnd.me.config":
   oras push --artifact-type application/vnd.me.config localhost:5000/hello:latest hi.txt
 
-Example - Push file "hi.txt" with the custom manifest config "config.json" of the custom "application/vnd.me.config" media type:
+Example - Push file "hi.txt" with the custom manifest config "config.json" of the custom media type "application/vnd.me.config":
   oras push --config config.json:application/vnd.me.config localhost:5000/hello:latest hi.txt
 
 Example - Push file to the insecure registry:

cmd/oras/tag/tag.go

@@ -50,7 +50,7 @@ Example - Tag the manifest with digest sha256:9463e0d192846bc994279417b501146067
 Example - Tag the manifest 'v1.0.1' in 'localhost:5000/hello' to 'v1.0.2', 'latest'
   oras tag localhost:5000/hello:v1.0.1 v1.0.2 latest
 
-Example - Tag the manifest 'v1.0.1' in 'localhost:5000/hello' to 'v1.0.2' 'latest' with concurrency level tuned:
+Example - Tag the manifest 'v1.0.1' in 'localhost:5000/hello' to 'v1.0.1', 'v1.0.2', 'latest' with concurrency level tuned:
   oras tag --concurrency 1 localhost:5000/hello:v1.0.1 v1.0.2 latest
 `,
 		Args: cobra.MinimumNArgs(2),