Description
The CLI help text (and generated docs) for kosli attest generic and kosli attest custom
don't clearly explain the practical difference between three flags that all accept file paths:
| Flag |
Available on |
What it does |
--user-data |
generic, custom |
Attaches structured JSON data visible/queryable in the attestation |
--attachments |
generic, custom |
Uploads files/dirs to the evidence vault as compressed downloads |
--attestation-data |
custom only |
JSON data evaluated by the custom type's jq policy for compliance |
The flag descriptions are technically accurate but the practical difference isn't obvious —
especially between --user-data and --attachments (both take file paths, very different
purposes), or between --user-data and --attestation-data on kosli attest custom.
Suggestion
Improve the flag description constants and/or the command long descriptions to clarify
"when to use which". For example:
--user-data — additional context (build metadata, environment info) stored and
visible alongside the attestation in the Kosli UI
--attachments — files archived in the evidence vault for later download
(e.g., test reports, scan output)
--attestation-data (custom only) — the JSON payload the custom type's jq
expression evaluates to determine compliance
Files to change
Flag description constants in cmd/kosli/root.go:
attestationUserDataFlag (line 131)
attachmentsFlag (line 218)
attestationCustomDataFileFlag (line 213)
Command long descriptions:
cmd/kosli/attestGeneric.go — attestGenericLongDesc (line 26)
cmd/kosli/attestCustom.go — attestCustomLongDesc (line 28)
Common flag registration: cmd/kosli/flags.go (lines 112-113)
Description
The CLI help text (and generated docs) for
kosli attest genericandkosli attest customdon't clearly explain the practical difference between three flags that all accept file paths:
--user-data--attachments--attestation-dataThe flag descriptions are technically accurate but the practical difference isn't obvious —
especially between
--user-dataand--attachments(both take file paths, very differentpurposes), or between
--user-dataand--attestation-dataonkosli attest custom.Suggestion
Improve the flag description constants and/or the command long descriptions to clarify
"when to use which". For example:
--user-data— additional context (build metadata, environment info) stored andvisible alongside the attestation in the Kosli UI
--attachments— files archived in the evidence vault for later download(e.g., test reports, scan output)
--attestation-data(custom only) — the JSON payload the custom type's jqexpression evaluates to determine compliance
Files to change
Flag description constants in
cmd/kosli/root.go:attestationUserDataFlag(line 131)attachmentsFlag(line 218)attestationCustomDataFileFlag(line 213)Command long descriptions:
cmd/kosli/attestGeneric.go—attestGenericLongDesc(line 26)cmd/kosli/attestCustom.go—attestCustomLongDesc(line 28)Common flag registration:
cmd/kosli/flags.go(lines 112-113)