Arbitrary metadata
Managing arbitrary metadata via the Cloudsmith CLI
Early Access
Arbitrary metadata is currently available in early access for Ultra and Enterprise customers. To request early access, contact us.
You can add, view, update, and delete arbitrary key-value metadata for a package by using the cloudsmith push command, or the cloudsmith metadata command group.
- To add metadata when you push a new package, use the
cloudsmith pushcommand. - To add and manage metadata for an existing package, use the
cloudsmith metadatacommand group.
cloudsmith push command
Every cloudsmith push <format> subcommand now supports five metadata flags:
| Flag | Input |
|---|---|
--metadata-content-file | The path to a file containing the metadata payload as a JSON object, or - for stdin. |
--metadata-content | The metadata payload as a JSON object. |
--metadata-content-type | The schema of the metadata payload. For example, application/json. |
--metadata-source-identity | The identifier for the source of the metadata entry. Default: cloudsmith-cli@<version> |
--on-metadata-failure | The metadata failure mode: error or warn (defaults to error) Determines how validation/attach failures are handled. |
The CLI validates the payload locally before any file upload starts.
- If validation passes, the package is uploaded and metadata is attached in a single command.
- If validation or attachment fails, the push aborts with the HTTP status as the exit code, so CI surfaces broken metadata immediately.
Examples
Push a new package with metadata:
cloudsmith push raw ${ORG}/${REPO} payload.txt \
--name metadata-demo \
--metadata-content '{"build_id": "demo-inline", "git_sha": "abc123"}' \
--metadata-content-type application/jsonPush a new package with metadata, downgrading failures via the --on-metadata-failure flag:
cloudsmith push raw ${ORG}/${REPO} payload.txt \
--name metadata-demo \
--metadata-content-file metadata.json \
--metadata-content-type application/json \
--on-metadata-failure warnPush a new package with metadata, downgrading failures by using an environment variable:
CLOUDSMITH_METADATA_FAILURE_MODE=warn cloudsmith push raw ${ORG}/${REPO} payload.txt \
--name metadata-demo \
--metadata-content-file metadata.json \
--metadata-content-type application/jsonTo set the metadata failure mode persistently, add the following to ~/.cloudsmith/config.ini:
[default]
metadata_failure_mode = warncloudsmith metadata command group
You can add, view, update, and delete arbitrary key-value metadata for an existing package by using the cloudsmith metadata command group:
| Command | Description | Flags accepted |
|---|---|---|
cloudsmith metadata add | Attach a new metadata entry to an existing package. | --content-type, --source-identity, --content or --file |
cloudsmith metadata update | Replace the content or source-identity fields of a metadata entry. | --content or --file, and --source-identity |
cloudsmith metadata list | List metadata entries for a package. Filter by source kind and classification, with paginated results. | --source-kind and --classification |
cloudsmith metadata remove | Remove a specific metadata entry from a package. | -y or --yes cloudsmith metadata remove prompts for confirmation by default; use the -y or --yes flag to skip the prompt. |
Attaching key-value metadata to a package
To add key-value metadata to an existing package, use the cloudsmith metadata add command with the following flags:
| Command flag | Description |
|---|---|
--content-type | The content type describing the structure of the metadata payload. For example, application/json. |
--source-identity | The identifier for the source of this metadata. For example, upstream:npmjs. |
--content or --file | The metadata payload as a JSON object, or the path to a file containing the metadata payload. |
--output-format | Command output formatting style. Supported formats: json and pretty_json |
Example:
cloudsmith metadata add your-org/example-repo/package_slug_perm \
--content-type application/json \
--source-identity ci:release-42 \
--content '{"release":"2026.06","commit":"abc123"}'Update a metadata entry for a package
You can replace the source-identity and content values of a specific metadata entry by using the cloudsmith metadata update command.
Warning
Updating the metadata will replace the current values for the specified fields.
If you want to update the
contentfield, you must also resubmit the key-value pairs that you want to retain unchanged.
Example:
cloudsmith metadata update example-org/example-repo/package_slug_perm metadata_slug_perm \
--content '{"release":"2026.05","commit":"def456"}'View metadata for a package
You can list all of the metadata entries for a package, or retrieve a single entry by its slug_perm.
List all metadata entries for a package:
cloudsmith metadata list your-org/your-repo/package_slug_permRetrieve a single metadata entry by using its slug_perm:
cloudsmith metadata list your-org/your-repo/package_slug_perm metadata_slug_permFilter metadata for a package
The metadata list command supports filtering by --classification and --source-kind.
Note
Customer-provided key-value metadata has theGENERICclassification and theCUSTOMsource kind.
List all metadata entries for a package which have the GENERIC classification:
cloudsmith metadata list your-org/your-repo/package_slug_perm --classification GENERICRemove metadata from a package
You can remove a specific metadata entry from a package by using the slug_perm for the entry:
cloudsmith metadata remove your-org/your-repo/package_slug_perm metadata_slug_permSearch for packages with metadata filters
The cloudsmith list packages command supports a metadata: search filter.
For more information about searching packages via the CLI, see Searching packages via the Cloudsmith CLI.
