improve clairctl documentation and add examples for commands

[flomickl]

The documentation from clairctl seems to be a little bit outdated on this page [1]

In clairctl version v4.7.4 (claircore v1.5.27) many commands have changed

clairctl --help
NAME:
   clairctl - interact with a clair API

USAGE:
   clairctl [global options] command [command options] [arguments...]

VERSION:
   v4.7.4 (claircore v1.5.27)

DESCRIPTION:
   A command-line tool for clair v4.

COMMANDS:
   manifest         print a clair manifest for the named container
   report           request vulnerability reports for the named containers
   export-updaters  run updaters and export results
   import-updaters  import updates
   delete           deletes index reports for given manifest digests
   check-config     print a fully-resolved clair config
   help, h          Shows a list of commands or help for one command
   Advanced:
     admin  run administrator task

GLOBAL OPTIONS:
   -D                           print debugging logs (default: false)
   -q                           quieter log output (default: false)
   --config value, -c value     clair configuration file (default: "config.yaml") [$CLAIR_CONF]
   --issuer value, --iss value  jwt "issuer" to use when making authenticated requests (default: "clairctl")
   --help, -h                   show help
   --version, -v                print the version

I also think some practicable showcases, how the commands are working on an example would help to understand how clairctl and clair is working.
For example the admin part is undocumented or are there some other documentations?
I would have no clue what this really means.

clairctl report --help
NAME:
   clairctl report - request vulnerability reports for the named containers

USAGE:
   clairctl report [command options] container...

DESCRIPTION:
   Request and print a Clair vulnerability report for the named container(s).

OPTIONS:
   --host value           URL for the clairv4 v1 API. (default: "http://localhost:6060/") [$CLAIR_API]
   --out value, -o value  output format: text, json, xml (default: text)
   --keep-going, -k       when requesting more than one report, don't stop at the first error reported (default: false)
   --novel                only upload novel manifests (default: false)
   --help, -h             show help

A short code examples with description
sometimes the usage description is not really clear if new users.

I needed a while to came to the result that I have to use the global options before report

clairctl [global options]  report [command options] container...

in my case, scanning the clair container

clairctl  --iss my-issuername report  -host https://clair.example.com  quay.io/projectquay/clair:4.7.4

By the way. How is the key trom my auth issuer is transmitted in this case???

Same with the following commands

• export-updaters run updaters and export results
• import-updaters import updates
• delete deletes index reports for given manifest digests
• check-config print a fully-resolved clair config

How is the documented [1] created and how is it possible to contribute a little bit?
A section with download sources would be good in the clairctl section as well, I guess.

Perhaps we can also discuss other clairctl command options that should be added, and cross-references to other information in the documentation here in general [2] ?

[1] https://quay.github.io/clair/reference/clairctl.html#clairctl
[2]

[flomickl]

I found out where the chapter in question is located in the repo [1], namely here [2], so I have already answered the first part of the question myself.

[1] https://quay.github.io/clair/reference/clairctl.html#clairctl
[2] https://github.com/quay/clair/blob/main/Documentation/reference/clairctl.md

[hdonnay]

Looks like you found the source for that documentation page. It's seemingly out of date, which is annoying I agree.

The complaint about flag ordering and display is a shortcoming of the package.

By the way. How is the key [from] my auth issuer is transmitted in this case???

It's in the supplied configuration.

I also think some practicable showcases, how the commands are working on an example would help to understand how clairctl and clair is working.

This would be a nice contribution to the docs, as long as there's some way to check that it's staying in sync with the actual CLI. Otherwise, it'll just decay and be confusing. I don't think examples belong in the command-printed documentation.