fix(submit): send labels (not tags); drop --group, keep --label

Align submit with the DevRadar API: the grouping field on POST /v1/sboms is
`labels`, but the client was sending `tags`, which the server ignored — so
grouping labels were silently dropped. Rename the wire field and SubmitRequest
field to Labels, remove the --group flag (keep --label), and rename the env var
DEVRADAR_TAGS -> DEVRADAR_LABELS.

Docs realigned to the API field table (README config table + --tag/--image-ref
rows; DEVELOPMENT.md and CLAUDE.md API contract, incl. optional format_hint /
generated_at the CLI does not send).

Author: mchmarny

.claude/CLAUDE.md

@@ -54,7 +54,7 @@ Thin `main.go` → `internal/cli`. Nothing is meant for external import, hence
   - `ref.go` — `SplitRef`/`Repository`/`Tag` (ported from devradar `pkg/sbom/ref.go`).
   - `digest.go` — manifest digest resolution **in-process** via `go-containerregistry` (crane lib); no `crane` binary needed.
   - `generate.go` — shells out to `syft` (`-q --scope all-layers -o cyclonedx-json <ref>`); `EnsureSyft` fails fast if absent.
-- `internal/client` — HTTP client for `POST /v1/sboms` (Bearer auth, base64 `sbom`, optional `image_ref`/`version`/`tags`).
+- `internal/client` — HTTP client for `POST /v1/sboms` (Bearer auth, base64 `sbom`, optional `image_ref`/`version`/`labels`).
 - `internal/logging` — slog setup; **warn** default level, `--debug` → debug, `--log-json` → JSON handler.
 
 ## Key conventions
@@ -66,9 +66,11 @@ Thin `main.go` → `internal/cli`. Nothing is meant for external import, hence
 ## API contract
 
 `POST {base}/v1/sboms`, header `Authorization: Bearer <token>`, body
-`{ "sbom": <base64>, "image_ref"?, "version"?, "tags"?[] }`. Response
-`{ sbom_id, image_ref, digest, format, existing }`. Source of truth:
-devradar `pkg/server/ingest.go`. Default base URL `https://devradar.thingz.io`.
+`{ "sbom": <base64>, "image_ref"?, "version"?, "labels"?[], "format_hint"?, "generated_at"? }`.
+The CLI sends `sbom`/`image_ref`/`version`/`labels` only. Response
+`{ sbom_id, image_ref, digest, format, existing }`. Source of truth: devradar
+`pkg/server/ingest.go` (details in its `IMPLEMENTATION.md`). Default base URL
+`https://devradar.thingz.io`.
 
 ## Release
 

DEVELOPMENT.md

@@ -74,14 +74,24 @@ hence `internal/` rather than `pkg/`.
 
 ## API contract
 
-`POST {base}/v1/sboms`, header `Authorization: Bearer <token>`, body:
-
-```json
-{ "sbom": "<base64>", "image_ref": "…", "version": "…", "tags": ["…"] }
-```
-
-Response: `{ sbom_id, image_ref, digest, format, existing }`. Only `sbom` is
-required. Source of truth: devradar `pkg/server/ingest.go`.
+`POST {base}/v1/sboms`, header `Authorization: Bearer <token>`. Only `sbom` is
+required:
+
+| Field          | Req? | Purpose                                                   |
+| -------------- | ---- | --------------------------------------------------------- |
+| `sbom`         | yes  | base64 SBOM bytes                                         |
+| `image_ref`    | no   | override the image reference                              |
+| `version`      | no   | the image tag (e.g. `v1.20.2`); else parsed from image_ref |
+| `format_hint`  | no   | `cyclonedx`\|`spdx` fast-fail assist (auto-detect otherwise) |
+| `generated_at` | no   | RFC3339 timestamp override                                |
+| `labels`       | no   | grouping labels (e.g. `team-x`, `prod`)                   |
+
+devradarctl sets `sbom`, `image_ref`, `version`, and `labels`; it relies on
+syft for format auto-detection and the SBOM's own `generated_at`, so it does not
+send `format_hint` or `generated_at`.
+
+Response: `{ sbom_id, image_ref, digest, format, existing }`. Source of truth:
+devradar `pkg/server/ingest.go` (see also its `IMPLEMENTATION.md`).
 
 ## Releasing
 

README.md

@@ -49,7 +49,7 @@ it does everything in one step: resolves the manifest digest, generates an
 every layer, not just the final squashed filesystem), and submits it.
 
 ```sh
-echo "$DEVRADAR_TOKEN" | devradarctl submit --image alpine:3.20 --group team-x --group prod
+echo "$DEVRADAR_TOKEN" | devradarctl submit --image alpine:3.20 --label team-x --label prod
 ```
 
 This requires [`syft`](https://github.com/anchore/syft) on `PATH`.
@@ -70,7 +70,9 @@ DEVRADAR_TOKEN=xxx devradarctl submit --file alpine.cdx.json --image-ref alpine@
 | ---------------- | -------------------- | ----------------------------- | --------------------------------------------- |
 | `--base-url`     | `DEVRADAR_BASE_URL`  | `https://devradar.thingz.io`  | DevRadar service base URL                     |
 | (token)          | `DEVRADAR_TOKEN`     | —                             | API token (or piped via stdin)               |
-| `--group`        | `DEVRADAR_TAGS`      | —                             | Grouping label(s); repeatable / comma env     |
+| `--label`        | `DEVRADAR_LABELS`    | —                             | Grouping label(s); repeatable                 |
+| `--tag`          | —                    | image's tag                   | Image version to record (e.g. `v1.20.2`)      |
+| `--image-ref`    | —                    | —                             | Digest-pinned image reference (file mode)     |
 | `--syft-path`    | `DEVRADAR_SYFT_PATH` | `syft`                        | Path to the syft binary                       |
 | `--scope`        | —                    | `all-layers`                  | syft cataloging scope                         |
 | `--debug`        | `DEVRADAR_DEBUG`     | `false`                       | Debug logging (default level is warn)         |

internal/cli/flags.go

@@ -16,7 +16,7 @@ const (
 	flagFile     = "file"
 	flagImageRef = "image-ref"
 	flagTag      = "tag"
-	flagGroup    = "group"
+	flagLabel    = "label"
 	flagBaseURL  = "base-url"
 )
 

internal/cli/submit.go

@@ -44,10 +44,9 @@ func submitCmd() *cli.Command {
 				Usage: "human version tag to record (e.g. v1.20.2); defaults to the image's tag",
 			},
 			&cli.StringSliceFlag{
-				Name:    flagGroup,
-				Aliases: []string{"label"},
+				Name:    flagLabel,
 				Usage:   "grouping label(s) to attach; repeatable",
-				Sources: cli.EnvVars("DEVRADAR_TAGS"),
+				Sources: cli.EnvVars("DEVRADAR_LABELS"),
 			},
 			&cli.StringFlag{
 				Name:    flagBaseURL,
@@ -76,7 +75,7 @@ func runSubmit(ctx context.Context, c *cli.Command) error {
 	}
 
 	req := client.SubmitRequest{
-		Tags:    c.StringSlice(flagGroup),
+		Labels:  c.StringSlice(flagLabel),
 		Version: c.String(flagTag),
 	}
 

internal/client/client.go

@@ -48,10 +48,10 @@ type SubmitRequest struct {
 	SBOM []byte
 	// ImageRef is the digest-pinned image reference (repo@sha256:…), optional.
 	ImageRef string
-	// Version is the human tag (e.g. "v1.20.2"), optional.
+	// Version is the image tag (e.g. "v1.20.2"), optional.
 	Version string
-	// Tags are tenant grouping labels (e.g. "team-x", "prod"), optional.
-	Tags []string
+	// Labels are tenant grouping labels (e.g. "team-x", "prod"), optional.
+	Labels []string
 }
 
 // SubmitResponse mirrors the POST /v1/sboms response body.
@@ -63,12 +63,12 @@ type SubmitResponse struct {
 	Existing bool   `json:"existing"`
 }
 
-// wireRequest is the JSON shape sent to the service.
+// wireRequest is the JSON shape sent to the service (POST /v1/sboms).
 type wireRequest struct {
 	SBOM     string   `json:"sbom"`
 	ImageRef string   `json:"image_ref,omitempty"`
 	Version  string   `json:"version,omitempty"`
-	Tags     []string `json:"tags,omitempty"`
+	Labels   []string `json:"labels,omitempty"`
 }
 
 // Submit posts an SBOM to {baseURL}/v1/sboms and returns the decoded response.
@@ -81,14 +81,14 @@ func (c *Client) Submit(ctx context.Context, in SubmitRequest) (*SubmitResponse,
 		SBOM:     base64.StdEncoding.EncodeToString(in.SBOM),
 		ImageRef: in.ImageRef,
 		Version:  in.Version,
-		Tags:     in.Tags,
+		Labels:   in.Labels,
 	})
 	if err != nil {
 		return nil, fmt.Errorf("encode request: %w", err)
 	}
 
 	url := c.baseURL + "/v1/sboms"
-	slog.Debug("submitting SBOM", "url", url, "image_ref", in.ImageRef, "version", in.Version, "tags", in.Tags, "bytes", len(in.SBOM))
+	slog.Debug("submitting SBOM", "url", url, "image_ref", in.ImageRef, "version", in.Version, "labels", in.Labels, "bytes", len(in.SBOM))
 
 	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
 	if err != nil {

internal/client/client_test.go

@@ -32,7 +32,7 @@ func TestSubmit_Success(t *testing.T) {
 		SBOM:     sbomDoc,
 		ImageRef: "alpine@sha256:x",
 		Version:  "3.20",
-		Tags:     []string{"team-x", "prod"},
+		Labels:   []string{"team-x", "prod"},
 	})
 	if err != nil {
 		t.Fatalf("Submit: %v", err)
@@ -54,8 +54,8 @@ func TestSubmit_Success(t *testing.T) {
 	if gotBody.ImageRef != "alpine@sha256:x" || gotBody.Version != "3.20" {
 		t.Errorf("body image_ref/version = %q/%q", gotBody.ImageRef, gotBody.Version)
 	}
-	if len(gotBody.Tags) != 2 {
-		t.Errorf("body.tags = %v, want 2 tags", gotBody.Tags)
+	if len(gotBody.Labels) != 2 {
+		t.Errorf("body.labels = %v, want 2 labels", gotBody.Labels)
 	}
 	if resp.SBOMID != "sb-1" || resp.Format != "cyclonedx-json" {
 		t.Errorf("resp = %+v", resp)