Skip to content

Commit

Permalink
docs: update zli for new 2.0 syntax
Browse files Browse the repository at this point in the history
Signed-off-by: mbshields <[email protected]>
  • Loading branch information
mbshields committed Sep 14, 2023
1 parent a9459ff commit 9b8470d
Showing 1 changed file with 145 additions and 72 deletions.
217 changes: 145 additions & 72 deletions docs/user-guides/zli.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,42 +70,41 @@ Use the [`zli config`](#_zli-config) command to list all configured URLs with th

### Listing images

You can list all images hosted on a zot server using the [`zli images`](#_zli-images) command with the server’s alias:
You can list all images hosted on a zot server using the [`zli image list`](#_zli-image) command with the server’s alias:

$ bin/zli images remote-zot
$ bin/zli image list --config local

IMAGE NAME TAG DIGEST SIZE
postgres 9.6.18-alpine ef27f3e1 14.4MB
postgres 9.5-alpine 264450a7 14.4MB
busybox latest 414aeb86 707.8KB
REPOSITORY TAG OS/ARCH DIGEST SIGNED SIZE
alpine latest linux/amd64 3fc10231 false 84MB
busybox latest linux/amd64 9172c5f6 false 2.2MB

You can also filter the image list to view a specific image by specifying the image name:

$ bin/zli images remote-zot -n busybox
$ bin/zli image name busybox:latest --config local

IMAGE NAME TAG DIGEST SIZE
busybox latest 414aeb86 707.8KB
REPOSITORY TAG OS/ARCH DIGEST SIGNED SIZE
busybox latest linux/amd64 9172c5f6 false 2.2MB

### Scanning images for known vulnerabilities

Using the [`zli cve`](#_zli-cve) command, you can fetch the CVE (Common Vulnerabilities and Exposures) information for images hosted on the zot server. This example shows how to learn which images are affected by a specific CVE:
Using the [`zli cve list`](#_zli-cve) command, you can fetch the CVE (Common Vulnerabilities and Exposures) information for images hosted on the zot server. This example shows how to learn which images are affected by a specific CVE:

$ bin/zli cve remote-zot -i CVE-2017-9935
$ bin/zli cve affected CVE-2017-9935 --config remote-zot

IMAGE NAME TAG DIGEST SIZE
c3/openjdk-dev commit-5be4d92 ac3762e2 335MB

This example displays a list all CVEs affecting a specific image:
This example displays a list of all CVEs affecting a specific image:

$ bin/zli cve remote-zot -I c3/openjdk-dev:0.3.19
$ bin/zli cve list c3/openjdk-dev:0.3.19 --config remote-zot

ID SEVERITY TITLE
CVE-2015-8540 LOW libpng: underflow read in png_check_keyword()
CVE-2017-16826 LOW binutils: Invalid memory access in the coff_s...

This example displays the detailed CVEs in JSON format:

$ bin/zli cve remote-zot -I c3/openjdk-dev:0.3.19 -o json
$ bin/zli cve list c3/openjdk-dev:0.3.19 --config remote-zot -f json
{
"Tag": "0.3.19",
"CVEList": [
Expand Down Expand Up @@ -135,23 +134,24 @@ This example displays the detailed CVEs in JSON format:

This example lists all images on a specific zot server that are affected by a specific CVE:

$ bin/zli cve remote-zot -I c3/openjdk-dev -i CVE-2017-9935
$ bin/zli cve affected --config remote-zot CVE-2017-9935 --repo c3/openjdk-dev

IMAGE NAME TAG DIGEST SIZE
c3/openjdk-dev commit-2674e8a 71046748 338MB
c3/openjdk-dev commit-bd5cc94 0ab7fc76

This example lists all images on a specific zot server where the CVE has been fixed:

$ bin/zli cve remote-zot -I c3/openjdk-dev -i CVE-2017-9935 --fixed
$ bin/zli cve fixed c3/openjdk-dev CVE-2017-9935 --config remote-zot

IMAGE NAME TAG DIGEST SIZE
c3/openjdk-dev commit-2674e8a-squashfs b545b8ba 321MB
c3/openjdk-dev commit-d5024ec-squashfs cd45f8cf 321MB


### Listing repositories

You can list all repositories hosted on a zot server using the [`zli repos`](#_zli-repos) command with the server’s alias:
You can list all repositories hosted on a zot server using the [`zli repo`](#_zli-repo) command with the server’s alias:

Searching... 🌍

Expand All @@ -168,7 +168,7 @@ You can locate repositories and images hosted on a zot server using the [`zli se

This example searches the zot registry named 'local' for a repository whose name contains the substring 'ng':

$ bin/zli search --query ng local
$ bin/zli search query ng --config local

NAME SIZE LAST UPDATED DOWNLOADS STARS
nginx 794MB 2023-03-01 18:44:17.707690369 +0000 UTC 0 0
Expand All @@ -177,7 +177,7 @@ This example searches the zot registry named 'local' for a repository whose name

This example searches the zot registry named 'local' for a repository named 'nginx'. Because the repository name is followed by a colon, the search results must match the name exactly.

$ bin/zli search --query nginx: local
$ bin/zli search query nginx: --config local

REPOSITORY TAG OS/ARCH DIGEST SIGNED SIZE
nginx 1.23.1 linux/amd64 d2ad9089 true 57MB
Expand Down Expand Up @@ -218,8 +218,8 @@ This example searches the zot registry named 'local' for a repository named 'ngi
config Configure zot registry parameters for CLI
cve Lookup CVEs in images hosted on the zot registry
help Help about any command
images List images hosted on the zot registry
repos List all repositories
image List images hosted on the zot registry
repo List all repositories
search Search images and their tags

Flags:
Expand Down Expand Up @@ -255,12 +255,10 @@ This command generates the autocompletion script for `zli` for the specified she

### zli config

This command modifies and lists modified settings for a running zot registry.
This command configures zot registry parameters for CLI.

$ bin/zli config --help

Configure zot registry parameters for CLI

Usage:
zli config <config-name> [variable] [value] [flags]
zli config [command]
Expand All @@ -284,9 +282,9 @@ This command modifies and lists modified settings for a running zot registry.
Use "zli config [command] --help" for more information about a command.

Useful variables:
url zot server URL
showspinner show spinner while loading data [true/false]
verify-tls enable TLS certificate verification of the server [default: true]
url zot server URL
showspinner show spinner while loading data [true/false]
verify-tls enable TLS certificate verification of the server [default: true]

<a name="_zli-cve"></a>

Expand All @@ -297,60 +295,80 @@ This command lists CVEs (Common Vulnerabilities and Exposures) of images hosted
$ ./zli cve --help

Usage:
zli cve [config-name] [flags]
zli cve [command]

Available Commands:
affected List images affected by a CVE
fixed List tags where a CVE is fixedRetryWithContext
list List CVEs by REPO:TAG or REPO@DIGEST

Flags:
-i, --cve-id string List images affected by a CVE
--config string Specify the registry configuration to use for connection
--debug Show debug output
--fixed List tags which have fixed a CVE
-f, --format string Specify output format [text/json/yaml]
-h, --help help for cve
-I, --image string List CVEs by IMAGENAME[:TAG]
-o, --output string Specify output format [text/json/yaml]. JSON and YAML format return all info for CVEs
-s, --search string Search specific CVEs by name/id
--url string Specify zot server URL if config-name is not mentioned
-u, --user string User Credentials of zot server in USERNAME:PASSWORD format
-u, --user string User Credentials of zot server in "username:password" format
--verbose Show verbose output

<a name="_zli-images"></a>
Use "zli cve [command] --help" for more information about a command.

### zli images
Run 'zli config -h' for details on [config-name] argument

<a name="_zli-image"></a>

### zli image

This command lists images hosted on the zot registry.

$ ./zli images --help
$ ./zli image --help

Usage:
zli images [config-name] [flags]
zli image [command]

Available Commands:
base List images that are base for the given image
cve List all CVE's of the image
derived List images that are derived from given image
digest List images that contain a blob(manifest, config or layer) with the given digest
list List all images
name List image details by name

Flags:
-b, --base-images string List images that are base for the given image
--debug Show debug output
-D, --derived-images string List images that are derived from given image
-d, --digest string List images containing a specific manifest, config, or layer digest
-h, --help help for images
-n, --name string List image details by name
-o, --output string Specify output format [text/json/yaml]
--config string Specify the registry configuration to use for connection
--debug Show debug output
-f, --format string Specify output format [text/json/yaml]
-h, --help help for image
--url string Specify zot server URL if config-name is not mentioned
-u, --user string User Credentials of zot server in "username:password" format
--verbose Show verbose output

Use "zli image [command] --help" for more information about a command.

Run 'zli config -h' for details on [config-name] argument

<a name="_zli-repos"></a>
<a name="_zli-repo"></a>

### zli repos
### zli repo

This command lists all repositories in the zot registry.

$ ./zli repos --help
$ ./zli repo --help

Usage:
zli repos [config-name] [flags]
zli repo [command]

Available Commands:
list List all repositories

Flags:
--debug Show debug output
-h, --help help for repos
--url string Specify zot server URL if config-name is not mentioned
-u, --user string User Credentials of zot server in "username:password" format
--config string Specify the registry configuration to use for connection
--debug Show debug output
-h, --help help for repo
--url string Specify zot server URL if config-name is not mentioned
-u, --user string User Credentials of zot server in "username:password" format

Use "zli repo [command] --help" for more information about a command.

Run 'zli config -h' for details on [config-name] argument

Expand All @@ -365,28 +383,83 @@ The `search` command allows smart searching for a repository by its name or for
$ ./zli search --help

Search repos or images
Example:
# For repo search specify a substring of the repo name without the tag
zli search --query test/repo

# For image search specify the full repo name followed by the tag or a prefix of the tag
zli search --query test/repo:2.1.
Usage:
zli search [command]

# For referrers search specify the referred subject using its full digest or tag
zli search --subject repo@sha256:f9a0981...
zli search --subject repo:tag
Available Commands:
query Fuzzy search for repos and their tags.
subject List all referrers for this subject.

Flags:
--config string Specify the registry configuration to use for connection
--debug Show debug output
-f, --format string Specify output format [text/json/yaml]
-h, --help help for search
--url string Specify zot server URL if config-name is not mentioned
-u, --user string User Credentials of zot server in "username:password" format
--verbose Show verbose output

Use "zli search [command] --help" for more information about a command.

Run 'zli config -h' for details on [config-name] argument

#### zli search query

$ ./zli search query --help

Fuzzy search for repos and their tags.

Usage:
zli search query [flags]

Examples:
# For repo search specify a substring of the repo name without the tag
zli search query "test/repo"
# For image search specify the full repo name followed by the tag or a prefix of the tag.
zli search query "test/repo:2.1."

# To search all tags in all repos.
zli search query ":"

Flags:
-h, --help help for query

Global Flags:
--config string Specify the registry configuration to use for connection
--debug Show debug output
-f, --format string Specify output format [text/json/yaml]
--url string Specify zot server URL if config-name is not mentioned
-u, --user string User Credentials of zot server in "username:password" format
--verbose Show verbose output

Run 'zli config -h' for details on [config-name] argument

#### zli search subject

$ ./zli search subject --help

List all referrers for this subject. The subject can be specified by tag(repo:tag) or by digest" +
"(repo@digest)

Usage:
zli search [config-name] [flags]
zli search subject [repo:tag]|[repo@digest] [flags]

Examples:
# For referrers search specify the referred subject using its full digest or tag:
zli search subject "repo@sha256:f9a0981..."
zli search subject "repo:tag"

Flags:
--debug Show debug output
-h, --help help for search
-o, --output string Specify output format [text/json/yaml]
-q, --query string Specify what repo or image (repo:tag) to be searched
-s, --subject string List all referrers for this subject. The subject can be specified by tag (repo:tag) or by digest (repo@digest)
--url string Specify zot server URL if config-name is not mentioned
-u, --user string User Credentials of zot server in "username:password" format
--verbose Show verbose output

Run 'zli config -h' for details on [config-name] argument
-h, --help help for subject

Global Flags:
--config string Specify the registry configuration to use for connection
--debug Show debug output
-f, --format string Specify output format [text/json/yaml]
--url string Specify zot server URL if config-name is not mentioned
-u, --user string User Credentials of zot server in "username:password" format
--verbose Show verbose output

Run 'zli config -h' for details on [config-name] argument

0 comments on commit 9b8470d

Please sign in to comment.