release(eng-12003): Release of arbitrary metadata support

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.16.0
+current_version = 1.17.0
 commit = True
 tag = True
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<revision>\d+)

CHANGELOG.md

@@ -8,6 +8,25 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [1.17.0] - 2026-05-18
+
+### Added
+
+- Added `metadata` command group for managing arbitrary JSON metadata (SBOM, BuildInfo, custom) attached to a package.
+  - `metadata add`: Attach a new metadata entry to a package. Accepts inline `--content` or `--file` (with `-` for stdin), a required `--content-type`, and an optional `--source-identity`.
+  - `metadata list`: List metadata entries for a package, or fetch a single entry by slug. Supports filtering by `--source-kind` and `--classification`, with pagination flags.
+  - `metadata update`: Replace content or source identity on an existing entry. Content type is immutable after creation.
+  - `metadata remove`: Remove a metadata entry from a package. Supports `-y` to skip the confirmation prompt.
+  - Supports `--output-format json | pretty_json` for programmatic usage.
+- Added push-time metadata flags to every `cloudsmith push <format>` subcommand. Metadata is validated locally and against the API before any file upload, then attached to the package immediately after creation.
+  - `--metadata-content-file PATH`: Path to a JSON file containing the metadata content. Use `-` for stdin.
+  - `--metadata-content JSON`: Inline JSON content. Mutually exclusive with `--metadata-content-file`.
+  - `--metadata-content-type MIME`: MIME type of the metadata payload. Required when content is provided.
+  - `--metadata-source-identity TEXT`: Identifier indicating where the metadata originated. Defaults to `cloudsmith-cli@<version>`.
+  - `--on-metadata-failure [error|warn]`: Per-push override for how validation/attach failures are handled. `error` (default) aborts the push; `warn` downgrades to a warning and uploads the package anyway. Overrides `$CLOUDSMITH_METADATA_FAILURE_MODE` and the `metadata_failure_mode` config key for the current push.
+  - Failures abort the push by default with the HTTP status as the exit code. Downgrade failures to a warning (and emit a copy-paste `cloudsmith metadata add` retry hint) via any of: the `--on-metadata-failure warn` CLI flag, `CLOUDSMITH_METADATA_FAILURE_MODE=warn` (or `0`) env var, or the new `metadata_failure_mode` key in `config.ini`. Precedence: CLI flag → env var → config key → `error` default.
+  - Push JSON output now includes a `metadata_attachment` field on success and error envelopes.
+
 ## [1.16.0] - 2026-03-24
 
 ### Added

README.md

@@ -49,6 +49,11 @@ The CLI currently supports the following commands (and sub-commands):
   - `repos`:                List repositories for a namespace (owner).
 - `login`|`token`:        Retrieve your API authentication token/key via login.
 - `logout`:               Clear stored authentication credentials and SSO tokens (Keyring, API key from credential file and emit warning when `$CLOUDSMITH_API_KEY` is still set).
+- `metadata`:             Manage arbitrary JSON metadata (SBOM, BuildInfo, custom) attached to a package.
+  - `add`:                  Attach a new metadata entry to a package.
+  - `list`|`ls`:            List metadata entries for a package, or fetch a single entry by slug.
+  - `update`:               Replace content or source identity on an existing metadata entry.
+  - `remove`|`rm`:          Remove a metadata entry from a package.
 - `metrics`:              Metrics and statistics for a repository.
   - `tokens`:               Retrieve bandwidth usage for entitlement tokens.
   - `packages`:             Retrieve package usage for repository.
@@ -242,7 +247,7 @@ Although native uploads, i.e. those supported by the native ecosystem of a packa
 For example, if you wanted to upload a Debian package, you can do it in one-step. Assuming you have a package filename **libxml2-2.9.4-2.x86_64.deb**, representing **libxml 2.9.4**, for the **Ubuntu 16.04** distribution (which has a cloudsmith identifier of **ubuntu/xenial**):
 
 ```
-cloudsmith push deb your-account/your-repo/ubuntu/xenial libxml2-2.9.4-2.x86_64.deb
+cloudsmith push deb your-org/your-repo/ubuntu/xenial libxml2-2.9.4-2.x86_64.deb
 ```
 
 Want to know how to do it with another packaging format? Easy, just ask for help:
@@ -259,39 +264,39 @@ You can download packages from repositories using the `cloudsmith download` comm
 For example, to download a specific package:
 
 ```
-cloudsmith download your-account/your-repo package-name
+cloudsmith download your-org/your-repo package-name
 ```
 
 You can filter by various attributes like version, format, architecture, operating system, and tags:
 
 ```
 # Download a specific version
-cloudsmith download your-account/your-repo package-name --version 1.2.3
+cloudsmith download your-org/your-repo package-name --version 1.2.3
 
 # Filter by format and architecture
-cloudsmith download your-account/your-repo package-name --format deb --arch amd64
+cloudsmith download your-org/your-repo package-name --format deb --arch amd64
 
 # Filter by package tag (e.g., latest, stable, beta)
-cloudsmith download your-account/your-repo package-name --tag latest
+cloudsmith download your-org/your-repo package-name --tag latest
 
 # Combine tag with metadata filters
-cloudsmith download your-account/your-repo package-name --tag stable --format deb --arch arm64
+cloudsmith download your-org/your-repo package-name --tag stable --format deb --arch arm64
 
 # Filter by filename (exact or glob pattern)
-cloudsmith download your-account/your-repo package-name --filename '*.nupkg'
-cloudsmith download your-account/your-repo package-name --filename 'mypackage-1.0.0.snupkg'
+cloudsmith download your-org/your-repo package-name --filename '*.nupkg'
+cloudsmith download your-org/your-repo package-name --filename 'mypackage-1.0.0.snupkg'
 
 # Download all matching packages (when multiple packages share the same name/version)
-cloudsmith download your-account/your-repo package-name --download-all
+cloudsmith download your-org/your-repo package-name --download-all
 
 # Combine --download-all with --filename to download a subset
-cloudsmith download your-account/your-repo package-name --download-all --filename '*.snupkg'
+cloudsmith download your-org/your-repo package-name --download-all --filename '*.snupkg'
 
 # Download all associated files (POM, sources, javadoc, etc.)
-cloudsmith download your-account/your-repo package-name --all-files
+cloudsmith download your-org/your-repo package-name --all-files
 
 # Preview what would be downloaded without actually downloading
-cloudsmith download your-account/your-repo package-name --dry-run
+cloudsmith download your-org/your-repo package-name --dry-run
 ```
 
 For more advanced usage and all available options:
@@ -301,6 +306,125 @@ cloudsmith download --help
 ```
 
 
+## Package Metadata
+
+Arbitrary JSON metadata can be attached to any package — SBOMs, JFrog BuildInfo documents, or custom payloads. Metadata is validated against the declared content type and stays with the package for its lifetime.
+
+Metadata can be attached at push time with `cloudsmith push` (see [Attaching Metadata During Push](#attaching-metadata-during-push)) or managed afterwards with the `cloudsmith metadata` command group.
+
+To attach metadata to an existing package:
+
+```
+cloudsmith metadata add your-org/your-repo/your-pkg \
+  --content-type application/json \
+  --content '{"build_id": "demo-123", "git_sha": "abc123"}'
+```
+
+To attach metadata from a file (use `-` to read from stdin):
+
+```
+cloudsmith metadata add your-org/your-repo/your-pkg \
+  --content-type application/vnd.jfrog.buildinfo+json \
+  --file buildinfo.json
+```
+
+To list all metadata entries on a package, or fetch a single entry by slug:
+
+```
+cloudsmith metadata list your-org/your-repo/your-pkg
+cloudsmith metadata list your-org/your-repo/your-pkg meta-slug-perm
+```
+
+Filter entries by source kind or classification when listing:
+
+```
+cloudsmith metadata list your-org/your-repo/your-pkg --classification sbom
+cloudsmith metadata list your-org/your-repo/your-pkg --source-kind third_party
+```
+
+To replace the content or source identity of an existing entry (content type is fixed after creation):
+
+```
+cloudsmith metadata update your-org/your-repo/your-pkg meta-slug-perm \
+  --content '{"build_id": "demo-124"}'
+```
+
+To remove a metadata entry:
+
+```
+cloudsmith metadata remove your-org/your-repo/your-pkg meta-slug-perm
+```
+
+For all available options:
+
+```
+cloudsmith metadata --help
+```
+
+
+## Attaching Metadata During Push
+
+Every `cloudsmith push <format>` subcommand accepts a set of `--metadata-*` flags. When provided, metadata is validated locally and against the API before any file upload, then attached to the package immediately after creation. This avoids a separate `cloudsmith metadata add` step and prevents malformed metadata from leaving orphan packages behind.
+
+Available flags on every push subcommand:
+
+- `--metadata-content-file PATH`: Path to a JSON file containing the metadata content. Use `-` for stdin.
+- `--metadata-content JSON`: Inline JSON content. Mutually exclusive with `--metadata-content-file`.
+- `--metadata-content-type MIME`: MIME type of the metadata payload (e.g. `application/json`, `application/vnd.jfrog.buildinfo+json`). Required when content is provided.
+- `--metadata-source-identity TEXT`: Identifier indicating where the metadata originated. Defaults to `cloudsmith-cli@<version>`.
+- `--on-metadata-failure [error|warn]`: How to handle push-time metadata failures for this push only. `error` (default) aborts the push so CI/CD surfaces broken SBOM/BuildInfo payloads; `warn` downgrades to a warning and lets the package upload regardless. Overrides `$CLOUDSMITH_METADATA_FAILURE_MODE` and the `metadata_failure_mode` config key.
+
+Push a package with inline metadata:
+
+```
+cloudsmith push raw your-org/your-repo payload.txt \
+  --name demo --version 1.0.0 \
+  --metadata-content '{"build_id": "demo-inline", "git_sha": "abc123"}' \
+  --metadata-content-type application/json
+```
+
+Push a package with metadata loaded from a file:
+
+```
+cloudsmith push raw your-org/your-repo payload.txt \
+  --name demo --version 1.0.0 \
+  --metadata-content-file buildinfo.json \
+  --metadata-content-type application/vnd.jfrog.buildinfo+json
+```
+
+### Failure Behavior
+
+By default, push aborts when metadata validation or attachment fails. The HTTP status from the failed request is used as the exit code, so CI pipelines surface broken SBOMs or BuildInfo payloads instead of silently uploading a package without metadata.
+
+To downgrade failures to a warning (the package is still uploaded, and a copy-paste `cloudsmith metadata add` retry hint is printed), use any of the following — listed in order of precedence (highest first):
+
+1. The `--on-metadata-failure warn` CLI flag on `cloudsmith push` (per-push override):
+
+   ```
+   cloudsmith push raw your-org/your-repo payload.txt \
+     --name demo --version 1.0.0 \
+     --metadata-content-file buildinfo.json \
+     --metadata-content-type application/vnd.jfrog.buildinfo+json \
+     --on-metadata-failure warn
+   ```
+
+2. The `CLOUDSMITH_METADATA_FAILURE_MODE` environment variable set to `warn` or `0` (per-shell):
+
+   ```
+   CLOUDSMITH_METADATA_FAILURE_MODE=warn cloudsmith push raw your-org/your-repo payload.txt \
+     --name demo --version 1.0.0 \
+     --metadata-content-file buildinfo.json \
+     --metadata-content-type application/vnd.jfrog.buildinfo+json
+   ```
+
+3. The `metadata_failure_mode` key in `config.ini` set to `error`, `warn`, or `0` (persistent default):
+
+   ```ini
+   [default]
+   metadata_failure_mode = warn
+   ```
+
+
 ## Contributing
 
 Yes! Please do contribute, this is why we love open source.  Please see [CONTRIBUTING](https://github.com/cloudsmith-io/cloudsmith-cli/blob/master/CONTRIBUTING.md) for contribution guidelines when making code changes or raising issues for bug reports, ideas, discussions and/or questions (i.e. help required).

cloudsmith_cli/data/VERSION

@@ -1 +1 @@
-1.16.0
+1.17.0