chore: clean up CLI help

csaf/csaf-cli/README.md

@@ -31,7 +31,7 @@ and emit a URL per line with the discovered documents.
 Example:
 
 ```
-cargo run -- discover https://redhat.com
+cargo run -- discover redhat.com
 ```
 
 ### Download
@@ -78,7 +78,7 @@ a `file` URL, it needs to point to a local file system location created by `sync
 must be a domain name that will be used for discovering the CSAF provider metadata according to the specification.
 
 **NOTE:** The structure of the filesystem storage is currently not considered an API. It is only guaranteed that
-whatever is store can be read back by tools of the same version. Also, is it currently not a format which can be
+whatever is store can be read back by tools of the same version. Also, it is currently not a format which can be
 hosted directly as a new CSAF repository.
 
 ### Signature verification

csaf/csaf-cli/src/cmd/mod.rs

@@ -15,7 +15,9 @@ pub mod sync;
 #[derive(Debug, clap::Parser)]
 #[command(next_help_heading = "Discovery")]
 pub struct DiscoverArguments {
-    /// Source to scan from, will be suffixed with "/.well-known/csaf/provider-metadata.json" unless "--full" is used.
+    /// Source to scan from.
+    ///
+    /// CSAF trusted provider base domain (e.g. `redhat.com`), the full URL to the provider metadata file, or a local `file:` source.
     pub source: String,
 }
 
@@ -82,15 +84,15 @@ impl TryFrom<StoreArguments> for StoreVisitor {
 #[derive(Debug, clap::Parser)]
 #[command(next_help_heading = "Skipping")]
 pub struct SkipArguments {
-    /// Provide a timestamp since when files will be considered changed.
+    /// Provide a timestamp since when files are considered changed.
     #[arg(short, long)]
     pub since: Option<StartTimestamp>,
 
     /// A file to read/store the last sync timestamp to at the end of a successful run.
     #[arg(short = 'S', long)]
     pub since_file: Option<PathBuf>,
 
-    /// A delta to add to the value loaded from the since state file.
+    /// A delta to add to the value loaded from the since-state file.
     #[arg(long)]
     pub since_file_offset: Option<humantime::Duration>,
 }

sbom/sbom-cli/Cargo.toml

@@ -8,7 +8,7 @@ license = "Apache-2.0"
 repository = "https://github.com/ctron/csaf-walker"
 categories = ["command-line-utilities", "data-structures"]
 keywords = ["sbom", "cli"]
-readme = "../../README.md"
+readme = "README.md"
 # based on clap
 rust-version = "1.74"
 

sbom/sbom-cli/README.md

@@ -0,0 +1,90 @@
+# sbom
+
+A tool to work with SBOM data from the command line.
+
+This tool can also be used as a library: <https://crates.io/crates/csaf-walker>
+
+## Usage
+
+```
+Commands:
+  parse     Parse advisories
+  download  Like sync, but doesn't validate
+  scan      Scan advisories
+  discover  Discover advisories, just lists the URLs
+  sync      Sync only what changed, and alidate
+  report    Analyze (and report) the state of the data
+  send      Walk a source and send validated/retrieved documents to a sink
+  metadata  Discover provider metadata
+  help      Print this message or the help of the given subcommand(s)
+```
+
+### Parse
+
+Parse a CSAF document, or fail trying.
+
+### Discover
+
+Discover a list of URLs, pointing to CSAF document on a remove server. This will perform the lookup of the metadata,
+and emit a URL per line with the discovered documents.
+
+Example:
+
+```
+cargo run -- discover https://redhat.com
+```
+
+### Download
+
+Discover and download CSAF documents.
+
+### Sync
+
+Discover, download, and validate CSAF documents.
+
+This works similar to the `download` command, but will also perform some integrity validation (like digest, signatures).
+It will, however, not verify the content of documents.
+
+### Report
+
+Discover, validate, and verify CSAF documents.
+
+This discovers and temporarily downloads CSAF documents, performing validation and verification of the content.
+
+**NOTE:** This commands works best of already downloaded data (a combination of running `download` and then `report`).
+
+### Send
+
+Discover, download, validate, and send CSAF documents to a remote endpoint.
+
+Instead of storing content locally, this forwards content to a remote endpoint.
+
+### Metadata
+
+Take a source and try to discover the provider metadata. Showing the resulting JSON.
+
+## Common options
+
+### Sources
+
+The CSAF tooling can discover and retrieve CSAF documents from two services: HTTP and file systems. Additionally,
+when downloading CSAF documents, the tool will write content into the file system, so that it can later be used
+as a file system source.
+
+The idea behind that is that it is possible to split up the process of downloading and processing documents.
+
+If a source string can be parsed as an `https` URL, it must point to the provider metadata. If the source string is
+a `file` URL, it needs to point to a local file system location created by `sync` or `download`. Otherwise, the source
+must be a domain name that will be used for discovering the CSAF provider metadata according to the specification.
+
+**NOTE:** The structure of the filesystem storage is currently not considered an API. It is only guaranteed that
+whatever is store can be read back by tools of the same version. Also, is it currently not a format which can be
+hosted directly as a new CSAF repository.
+
+### Signature verification
+
+When signatures get verified, it may be possible that signature algorithms are considered "too old". If that's the case,
+and you still want to allow them, it is possible to provide the "policy date", which sets the defaults for what is
+still allowed (also see: <https://docs.rs/sequoia-policy-config/latest/sequoia_policy_config/>).
+
+Specifically, when encountering GPG v3 signatures, one can also use the `-3` switch.

sbom/sbom-cli/src/cmd/discover.rs

@@ -3,7 +3,7 @@ use sbom_walker::{discover::DiscoveredSbom, source::new_source, walker::Walker};
 use std::convert::Infallible;
 use walker_common::{cli::client::ClientArguments, progress::Progress};
 
-/// Discover advisories, just lists the URLs.
+/// Discover SBOMs, just lists the URLs.
 #[derive(clap::Args, Debug)]
 pub struct Discover {
     #[command(flatten)]

sbom/sbom-cli/src/cmd/download.rs

@@ -7,12 +7,12 @@ use sbom_walker::{
     visitors::store::StoreVisitor,
 };
 use walker_common::{
-    cli::{client::ClientArguments, runner::RunnerArguments, validation::ValidationArguments},
+    cli::{client::ClientArguments, runner::RunnerArguments},
     progress::Progress,
     since::Since,
 };
 
-/// Like sync, but doesn't validate.
+/// Like `sync`, but doesn't validate.
 #[derive(clap::Args, Debug)]
 pub struct Download {
     #[command(flatten)]
@@ -24,9 +24,6 @@ pub struct Download {
     #[command(flatten)]
     runner: RunnerArguments,
 
-    #[command(flatten)]
-    validation: ValidationArguments,
-
     #[command(flatten)]
     skip: SkipArguments,
 

sbom/sbom-cli/src/cmd/mod.rs

@@ -14,13 +14,10 @@ pub mod sync;
 #[derive(Debug, clap::Parser)]
 #[command(next_help_heading = "Discovery")]
 pub struct DiscoverArguments {
-    /// Source to scan from, will be suffixed with "/.well-known/csaf/provider-metadata.json" unless "--full" is used.
+    /// Source to scan from
     pub source: String,
-    #[arg(long)]
-    /// Treat the "source" as a full URL to the metadata.
-    pub full: bool,
     #[arg(short = 'k', long = "key")]
-    /// URLs to keys which should be used for validation. The fragment part of a key can be used as fingerprint.
+    /// URLs to keys which should be used for validation. The fragment part of a key can be used as the fingerprint.
     pub keys: Vec<Url>,
 }
 
@@ -42,7 +39,7 @@ impl TryFrom<StoreArguments> for StoreVisitor {
     fn try_from(value: StoreArguments) -> Result<Self, Self::Error> {
         let base = match value.data {
             Some(base) => base,
-            None => std::env::current_dir().context("Get current working directory")?,
+            None => std::env::current_dir().context("Get the current working directory")?,
         };
 
         Ok(Self::new(base).no_timestamps(value.no_timestamps))
@@ -52,15 +49,15 @@ impl TryFrom<StoreArguments> for StoreVisitor {
 #[derive(Debug, clap::Parser)]
 #[command(next_help_heading = "Skipping")]
 pub struct SkipArguments {
-    /// Provide a timestamp since when files will be considered changed.
+    /// Provide a timestamp since when files are considered changed.
     #[arg(short, long)]
     pub since: Option<StartTimestamp>,
 
     /// A file to read/store the last sync timestamp to at the end of a successful run.
     #[arg(short = 'S', long)]
     pub since_file: Option<PathBuf>,
 
-    /// A delta to add to the value loaded from the since state file.
+    /// A delta to add to the value loaded from the since-state file.
     #[arg(long)]
     pub since_file_offset: Option<humantime::Duration>,
 }

sbom/sbom-cli/src/cmd/scan.rs

@@ -12,7 +12,7 @@ use walker_common::{
     progress::Progress,
 };
 
-/// Scan advisories
+/// Scan SBOMs
 #[derive(clap::Args, Debug)]
 pub struct Scan {
     #[command(flatten)]

sbom/sbom-cli/src/cmd/sync.rs

@@ -15,7 +15,7 @@ use walker_common::{
     validate::ValidationOptions,
 };
 
-/// Sync only what changed, and don't validate.
+/// Sync only what changed.
 #[derive(clap::Args, Debug)]
 pub struct Sync {
     #[command(flatten)]