Merge pull request #462 from kosli-dev/minor-cli-reference-tidying

cli reference text fixing and tidying

Author: JonJagger

cmd/kosli/attestCustom.go

@@ -26,15 +26,18 @@ const attestCustomShortDesc = `Report a custom attestation to an artifact or a t
 
 const attestCustomLongDesc = attestCustomShortDesc + `
 The name of the custom attestation type is specified using the ^--type^ flag.
-` + attestationBindingDesc + commitDescription
+The path to the JSON file the custom type will evaluate is specified using the ^--attestation-data^ flag.
+` + attestationBindingDesc + `
+
+` + commitDescription
 
 const attestCustomExample = `
 # report a custom attestation about a pre-built container image artifact (kosli finds the fingerprint):
 kosli attest custom yourDockerImageName \
 	--artifact-type oci \
 	--type customTypeName \
 	--name yourAttestationName \
-	--data yourCustomData \
+	--attestation-data yourJsonFilePath \
 	--flow yourFlowName \
 	--trail yourTrailName \
 	--api-token yourAPIToken \
@@ -45,7 +48,7 @@ kosli attest custom \
 	--fingerprint yourDockerImageFingerprint \
 	--type customTypeName \
 	--name yourAttestationName \
-	--data yourCustomData \
+	--attestation-data yourJsonFilePath \
 	--flow yourFlowName \
 	--trail yourTrailName \
 	--api-token yourAPIToken \
@@ -55,7 +58,7 @@ kosli attest custom \
 kosli attest custom \
 	--type customTypeName \
 	--name yourAttestationName \
-	--data yourCustomData \
+	--attestation-data yourJsonFilePath \
 	--flow yourFlowName \
 	--trail yourTrailName \
 	--api-token yourAPIToken \
@@ -65,7 +68,7 @@ kosli attest custom \
 kosli attest custom \
 	--type customTypeName \
 	--name yourTemplateArtifactName.yourAttestationName \
-	--data yourCustomData \
+	--attestation-data yourJsonFilePath \
 	--flow yourFlowName \
 	--trail yourTrailName \
 	--commit yourArtifactGitCommit \
@@ -76,7 +79,7 @@ kosli attest custom \
 kosli attest custom \
     --type customTypeName \
 	--name yourAttestationName \
-	--data yourCustomData \
+	--attestation-data yourJsonFilePath \
 	--flow yourFlowName \
 	--trail yourTrailName \
 	--attachments yourAttachmentPathName \

cmd/kosli/attestation.go

@@ -9,9 +9,9 @@ import (
 	"github.com/kosli-dev/cli/internal/requests"
 )
 
-const commitDescription = `You can optionally associate the attestation to a git commit using ^--commit^ (requires access to a git repo). And you  
-can optionally redact some of the git commit data sent to Kosli using ^--redact-commit-info^. 
-Note that when the attestation is reported for an artifact that does not yet exist in Kosli, ^--commit^ becomes required to facilitate 
+const commitDescription = `You can optionally associate the attestation to a git commit using ^--commit^ (requires access to a git repo).
+You can optionally redact some of the git commit data sent to Kosli using ^--redact-commit-info^.
+Note that when the attestation is reported for an artifact that does not yet exist in Kosli, ^--commit^ is required to facilitate
 binding the attestation to the right artifact.`
 
 type URLInfo struct {

cmd/kosli/root.go

@@ -51,9 +51,8 @@ images in registries or "docker" for local docker images.
 
 	attestationBindingDesc = `
 
-The attestation can be bound to a trail using the trail name.
-
-If the attestation is for an artifact, the attestation can be bound to the artifact using one of two ways:
+The attestation can be bound to a *trail* using the trail name.  
+The attestation can be bound to an *artifact* in two ways:
 - using the artifact's SHA256 fingerprint which is calculated (based on the ^--artifact-type^ flag and the artifact name/path argument) or can be provided directly (with the ^--fingerprint^ flag).
 - using the artifact's name in the flow yaml template and the git commit from which the artifact is/will be created. Useful when reporting an attestation before creating/reporting the artifact.`
 	awsAuthDesc = `
@@ -77,7 +76,7 @@ The service principal needs to have the following permissions:
 	`
 	kosliIgnoreDesc = `To specify paths in a directory artifact that should always be excluded from the SHA256 calculation, you can add a ^.kosli_ignore^ file to the root of the artifact.
 Each line should specify a relative path or path glob to be ignored. You can include comments in this file, using ^#^.
-The ^.kosli_ignore^ will be treated as part of the artifact like any other file,unless it is explicitly ignored itself.`
+The ^.kosli_ignore^ will be treated as part of the artifact like any other file, unless it is explicitly ignored itself.`
 
 	// flags
 	apiTokenFlag                         = "The Kosli API token."

cmd/kosli/snapshotPath.go

@@ -20,7 +20,7 @@ const snapshotPathShortDesc = `Report a snapshot of a single artifact running in
 const snapshotPathLongDesc = snapshotPathShortDesc + `
 You can report a directory or file artifact. For reporting multiple artifacts in one go, use "kosli snapshot paths".
 You can exclude certain paths or patterns from the artifact fingerprint using ^--exclude^.
-The supported glob pattern syntax is what is documented here: https://pkg.go.dev/path/filepath#Match , 
+The supported glob pattern syntax is documented here: https://pkg.go.dev/path/filepath#Match ,
 plus the ability to use recursive globs "**"
 
 ` + kosliIgnoreDesc

cmd/kosli/snapshotPaths.go

@@ -19,7 +19,7 @@ const pathSpecFileDesc = `Paths files can be in YAML, JSON or TOML formats.
 They specify a list of artifacts to fingerprint. For each artifact, the file specifies a base path to look for the artifact in 
 and (optionally) a list of paths to exclude. Excluded paths are relative to the artifact path(s) and can be literal paths or
 glob patterns.  
-The supported glob pattern syntax is what is documented here: https://pkg.go.dev/path/filepath#Match , 
+The supported glob pattern syntax is documented here: https://pkg.go.dev/path/filepath#Match ,
 plus the ability to use recursive globs "**"
 
 ` + kosliIgnoreDesc + `

cmd/kosli/testdata/output/docs/snyk.md

@@ -19,15 +19,14 @@ By default, the `--scan-results` .json file is also uploaded to Kosli's evidence
 You can disable that by setting `--upload-results=false`
 
 
-The attestation can be bound to a trail using the trail name.
-
-If the attestation is for an artifact, the attestation can be bound to the artifact using one of two ways:
+The attestation can be bound to a *trail* using the trail name.  
+The attestation can be bound to an *artifact* in two ways:
 - using the artifact's SHA256 fingerprint which is calculated (based on the `--artifact-type` flag and the artifact name/path argument) or can be provided directly (with the `--fingerprint` flag).
 - using the artifact's name in the flow yaml template and the git commit from which the artifact is/will be created. Useful when reporting an attestation before creating/reporting the artifact.
 
-You can optionally associate the attestation to a git commit using `--commit` (requires access to a git repo). And you  
-can optionally redact some of the git commit data sent to Kosli using `--redact-commit-info`. 
-Note that when the attestation is reported for an artifact that does not yet exist in Kosli, `--commit` becomes required to facilitate 
+You can optionally associate the attestation to a git commit using `--commit` (requires access to a git repo).
+You can optionally redact some of the git commit data sent to Kosli using `--redact-commit-info`.
+Note that when the attestation is reported for an artifact that does not yet exist in Kosli, `--commit` is required to facilitate
 binding the attestation to the right artifact.
 
 ```shell