Skip to content

Clarify difference between --user-data, --attachments, and --attestation-data in attest commands #821

@dangrondahl

Description

@dangrondahl

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.goattestGenericLongDesc (line 26)
  • cmd/kosli/attestCustom.goattestCustomLongDesc (line 28)

Common flag registration: cmd/kosli/flags.go (lines 112-113)

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions