add CLI reference docs - part 1

Signed-off-by: Feynman Zhou <[email protected]>

docs/CLI_Reference/index.md

@@ -0,0 +1,55 @@
+# Use the ORAS command line
+
+To list available commands, either run `oras` with no parameters or execute `oras help`:
+
+## Options
+
+```
+$ oras
+Usage:
+  oras [command]
+
+Available Commands:
+  attach      Attach files to an existing artifact
+  blob        Blob operations
+  completion  Generate the autocompletion script for the specified shell
+  cp          Copy artifacts from one target to another
+  discover    Discover referrers of a manifest in the remote registry
+  help        Help about any command
+  login       Log in to a remote registry
+  logout      Log out from a remote registry
+  manifest    Manifest operations
+  pull        Pull files from remote registry
+  push        Push files to remote registry
+  repo        Repository operations
+  tag         Tag a manifest in the remote registry
+  version     Show the oras version information
+
+Flags:
+  -h, --help   help for oras
+
+Use "oras [command] --help" for more information about a command.
+```
+
+### SEE ALSO
+
+* [oras attach](oras_attach.md)	 - Attach files to an existing artifact
+* oras blob - Blob operations
+    * [oras blob delete](oras_blob_delete.md)	 - Delete a blob from a remote registry
+    * [oras blob fetch](oras_blob_fetch.md)	 - Fetch a blob from a remote registry
+    * [oras blob push](oras_blob_push.md)	 - Push a blob to a remote registry
+    * [oras copy](oras_copy.md)	 - Copy artifacts from one target to another
+* [oras discover](oras_discover.md)	 - Discover referrers of a manifest in the remote registry
+* [oras login](oras_login.md)	 - Log in to a remote registry
+* [oras logout](oras_logout.md)	 - Log out from a remote registry
+* oras manifest - Manifest operations
+    * [oras manifest delete](oras_manifest_delete.md)	 - Delete a manifest from a remote registry
+    * [oras manifest fetch-config](oras_manifest_fetch-config.md)	 - Fetch the config of a manifest from a remote registry
+    * [oras manifest fetch](oras_manifest_fetch.md)	 - Fetch manifest of the target artifact
+    * [oras manifest push](oras_manifest_push.md)	 - Push a manifest to a remote registry
+* [oras pull](oras_pull.md)	 - Pull files from a remote registry
+* [oras push](oras_push.md)	 - Push files to a remote registry
+* [oras repository](oras_repository.md)	 - Repository operations
+* [oras tag](oras_tag.md)	 - Tag a manifest in the remote registry
+* [oras version](oras_version.md)	 - Show ORAS CLI version
+

docs/CLI_Reference/oras_attach.md

@@ -0,0 +1,56 @@
+## oras attach
+
+[Preview] Attach files to an existing artifact
+
+### Synopsis
+
+[Preview] Attach files to an existing artifact
+
+** This command is in preview and under development. **
+
+Example - Attach file 'hi.txt' with type 'doc/example' to manifest 'hello:test' in registry 'localhost:5000'
+  oras attach --artifact-type doc/example localhost:5000/hello:test hi.txt
+
+Example - Attach file 'hi.txt' and add annotations from file 'annotation.json'
+  oras attach --artifact-type doc/example --annotation-file annotation.json localhost:5000/hello:latest hi.txt
+
+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 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
+
+
+```
+oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]
+```
+
+### Options
+
+```
+  -a, --annotation stringArray    manifest annotations
+      --annotation-file string    path of the annotation file
+      --artifact-type string      artifact type
+      --ca-file string            server certificate authority file for the remote registry
+      --concurrency int           concurrency level (default 5)
+  -d, --debug                     debug mode
+      --disable-path-validation   skip path validation
+      --export-manifest path      path of the pushed manifest
+  -h, --help                      help for attach
+      --insecure                  allow connections to SSL registry without certs
+  -p, --password string           registry password or identity token
+      --password-stdin            read password or identity token from stdin
+      --plain-http                allow insecure connections to registry without SSL check
+      --registry-config path      path of the authentication file
+  -u, --username string           registry username
+  -v, --verbose                   verbose output
+```
+
+### SEE ALSO
+
+* [oras](oras.md)	 - 
+
+###### Auto generated by spf13/cobra on 8-Nov-2022

docs/CLI_Reference/oras_blob_delete.md

@@ -0,0 +1,47 @@
+## oras blob delete
+
+Delete a blob from a remote registry.
+
+```
+oras blob delete [flags] <name>@<digest>
+```
+
+## Examples
+
+
+Delete a blob:
+
+```
+oras blob delete localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
+```
+
+Delete a blob without prompting confirmation:
+
+```
+oras blob delete --yes localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
+```
+
+Delete a blob and print its descriptor:
+
+```
+oras blob delete --descriptor --yes localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
+```  
+
+## Options
+
+```
+      --ca-file string         server certificate authority file for the remote registry
+  -d, --debug                  debug mode
+      --descriptor             output the descriptor
+  -h, --help                   help for delete
+      --insecure               allow connections to SSL registry without certs
+  -p, --password string        registry password or identity token
+      --password-stdin         read password or identity token from stdin
+      --plain-http             allow insecure connections to registry without SSL check
+      --pretty                 prettify JSON objects printed to stdout
+      --registry-config path   path of the authentication file
+  -u, --username string        registry username
+  -v, --verbose                verbose output
+  -y, --yes                    do not prompt for confirmation
+```
+

docs/CLI_Reference/oras_blob_fetch.md

@@ -0,0 +1,51 @@
+## oras blob fetch
+
+Fetch a blob from a remote registry.
+
+```
+oras blob fetch [flags] {--output <file> | --descriptor} <name>@<digest>
+```
+
+## Examples
+
+Fetch the blob and save it to a local file:
+
+```
+oras blob fetch --output blob.tar.gz localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
+```
+
+Fetch the blob and print the raw blob content:
+
+```
+oras blob fetch --output - localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
+```
+
+Fetch and print the descriptor of a blob:
+
+```
+oras blob fetch --descriptor localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5
+```
+
+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
+```
+
+## Options
+
+```
+      --ca-file string         server certificate authority file for the remote registry
+  -d, --debug                  debug mode
+      --descriptor             output the descriptor
+  -h, --help                   help for fetch
+      --insecure               allow connections to SSL registry without certs
+  -o, --output path            output file path, use - for stdout
+  -p, --password string        registry password or identity token
+      --password-stdin         read password or identity token from stdin
+      --plain-http             allow insecure connections to registry without SSL check
+      --pretty                 prettify JSON objects printed to stdout
+      --registry-config path   path of the authentication file
+  -u, --username string        registry username
+  -v, --verbose                verbose output
+```

docs/CLI_Reference/oras_blob_push.md

@@ -0,0 +1,70 @@
+## oras blob push
+
+Push a blob to a remote registry.
+
+```
+oras blob push [flags] <name>[@digest] <file>
+```
+
+## Examples
+
+Push blob "hi.txt":
+
+```
+oras blob push localhost:5000/hello hi.txt
+```
+
+Push blob "hi.txt" with the specific digest:
+
+```
+oras blob push localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 hi.txt
+```
+
+Push blob from stdin with blob size and digest:
+
+```
+oras blob push --size 12 localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5 -
+```
+
+Push blob "hi.txt" and output the descriptor:
+
+```
+oras blob push --descriptor localhost:5000/hello hi.txt
+```
+
+Push blob "hi.txt" with the specific returned media type in the descriptor:
+
+```
+oras blob push --media-type application/vnd.oci.image.config.v1+json --descriptor localhost:5000/hello hi.txt
+```
+
+Push blob "hi.txt" and output the prettified descriptor:
+
+```
+oras blob push --descriptor --pretty localhost:5000/hello hi.txt
+```
+
+Push blob without TLS:
+
+```
+oras blob push --insecure localhost:5000/hello hi.txt
+```
+
+## Options
+
+```
+      --ca-file string         server certificate authority file for the remote registry
+  -d, --debug                  debug mode
+      --descriptor             output the descriptor
+  -h, --help                   help for push
+      --insecure               allow connections to SSL registry without certs
+      --media-type string      specify the returned media type in the descriptor if --descriptor is used (default "application/vnd.oci.image.layer.v1.tar")
+  -p, --password string        registry password or identity token
+      --password-stdin         read password or identity token from stdin
+      --plain-http             allow insecure connections to registry without SSL check
+      --pretty                 prettify JSON objects printed to stdout
+      --registry-config path   path of the authentication file
+      --size int               provide the blob size (default -1)
+  -u, --username string        registry username
+  -v, --verbose                verbose output
+```

docs/CLI_Reference/oras_copy.md

@@ -0,0 +1,61 @@
+## oras copy
+
+Copy artifacts from one target to another.
+
+```
+oras copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]
+```
+
+## Examples
+
+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
+```
+
+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
+```
+
+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 
+```
+
+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
+```
+
+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
+```
+
+### Options
+
+```
+      --concurrency int                             concurrency level (default 3)
+  -d, --debug                                       debug mode
+      --from-ca-file string                         server certificate authority file for the remote source registry
+      --from-insecure                               allow connections to source SSL registry without certs
+      --from-password string                        source registry password or identity token
+      --from-plain-http                             allow insecure connections to source registry without SSL check
+      --from-username string                        source registry username
+  -h, --help                                        help for copy
+      --platform os[/arch][/variant][:os_version]   request platform in the form of os[/arch][/variant][:os_version]
+  -r, --recursive                                   recursively copy the artifact and its referrer artifacts
+      --registry-config path                        path of the authentication file
+      --to-ca-file string                           server certificate authority file for the remote destination registry
+      --to-insecure                                 allow connections to destination SSL registry without certs
+      --to-password string                          destination registry password or identity token
+      --to-plain-http                               allow insecure connections to destination registry without SSL check
+      --to-username string                          destination registry username
+  -v, --verbose                                     verbose output
+```

docs/CLI_Reference/oras_discover.md

@@ -0,0 +1,46 @@
+## oras discover
+
+[Preview] Discover referrers of a manifest in the remote registry
+
+### Synopsis
+
+[Preview] Discover referrers of a manifest in the remote registry
+
+** This command is in preview and under development. **
+
+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' 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':
+  oras discover --artifact-type test-artifact localhost:5000/hello
+
+
+```
+oras discover [flags] <name>{:<tag>|@<digest>}
+```
+
+### Options
+
+```
+      --artifact-type string   artifact type
+      --ca-file string         server certificate authority file for the remote registry
+  -d, --debug                  debug mode
+  -h, --help                   help for discover
+      --insecure               allow connections to SSL registry without certs
+  -o, --output string          format in which to display referrers (table, json, or tree). tree format will also show indirect referrers (default "table")
+  -p, --password string        registry password or identity token
+      --password-stdin         read password or identity token from stdin
+      --plain-http             allow insecure connections to registry without SSL check
+      --registry-config path   path of the authentication file
+  -u, --username string        registry username
+  -v, --verbose                verbose output
+```
+
+### SEE ALSO
+
+* [oras](oras.md)	 - 
+
+###### Auto generated by spf13/cobra on 8-Nov-2022