feat(eng-12001): add metada commands (CRUD)

[BartoszBlizniak]

Description

Adds a new cloudsmith metadata command group for managing metadata entries attached to packages.

The command group supports:

• cloudsmith metadata list / ls to list metadata for a package, with optional --source-kind and --classification filters.
• cloudsmith metadata list OWNER/REPO/PACKAGE METADATA_SLUG_PERM to retrieve a single metadata entry (filters and pagination flags are ignored in this mode).
• cloudsmith metadata add to attach metadata from inline JSON, a JSON file, or stdin (--file -). --source-identity defaults to cloudsmith-cli@<version>.
• cloudsmith metadata update to patch metadata content and/or source-identity. content_type is immutable after creation. Errors out if no patchable field is supplied.
• cloudsmith metadata remove / rm to delete metadata, guarded by the standard destructive-action confirmation flow and -y/--yes.

All subcommands honour -F json / -F pretty_json and route through maybe_print_as_json so JSON output is consistent with the rest of the CLI.

Example: list metadata for a package

cloudsmith metadata list your-org/awesome-repo/better-pkg

Listing metadata for the 'better-pkg' package ... OK

Slug    | Content type                  | Classification | Source kind | Source identity
abc123  | application/json              | generic        | customer    | cloudsmith-cli@1.16.0
sbom456 | application/vnd.cyclonedx+json| sbom           | customer    | ci:sbom

Results: 2 metadata entries visible

Example: list with filters

cloudsmith metadata list your-org/awesome-repo/better-pkg --classification provenance
cloudsmith metadata list your-org/awesome-repo/better-pkg --source-kind customer

Both filters accept an integer or the enum name (case-insensitive, hyphens treated as underscores), so --source-kind third-party, --source-kind THIRD_PARTY, and --source-kind 4 are equivalent. Invalid values fail fast with a usage error before the API is called.

Example: retrieve a single metadata entry

cloudsmith metadata list your-org/awesome-repo/better-pkg abc123

Fetching metadata entry abc123 for the 'better-pkg' package ... OK

Slug   | Content type     | Classification | Source kind | Source identity
abc123 | application/json | generic        | customer    | cloudsmith-cli@1.16.0

Content:
{
  "commit": "abc123",
  "release": "2026.05"
}

Example: add inline metadata

cloudsmith metadata add your-org/awesome-repo/better-pkg \
  --content-type application/json \
  --source-identity ci:release-42 \
  --content '{"release":"2026.05","commit":"abc123"}'

Attaching metadata to the 'better-pkg' package ... OK

Slug    | Content type     | Classification | Source kind | Source identity
meta789 | application/json | generic        | customer    | ci:release-42

Content:
{
  "commit": "abc123",
  "release": "2026.05"
}

Example: add build-info or SBOM metadata from a file or stdin

cloudsmith metadata add your-org/awesome-repo/better-pkg \
  --content-type application/vnd.jfrog.buildinfo+json \
  --source-identity ci:build-info \
  --file buildinfo.json

cloudsmith metadata add your-org/awesome-repo/better-pkg \
  --content-type application/vnd.cyclonedx+json \
  --source-identity ci:sbom \
  --file sbom.json

cat payload.json | cloudsmith metadata add your-org/awesome-repo/better-pkg \
  --content-type application/json \
  --file -

Example: update an existing metadata entry

cloudsmith metadata update your-org/awesome-repo/better-pkg meta789 \
  --content '{"release":"2026.05","commit":"def456"}'

Updating metadata entry meta789 on the 'better-pkg' package ... OK

Slug    | Content type     | Classification | Source kind | Source identity
meta789 | application/json | generic        | customer    | ci:release-42

Content:
{
  "commit": "def456",
  "release": "2026.05"
}

Updating only --source-identity is also supported. Calling update with no patchable fields fails fast:

Error: Nothing to update. Provide --file, --content, or --source-identity.

Example: remove a metadata entry

cloudsmith metadata remove your-org/awesome-repo/better-pkg meta789

Are you sure you want to remove the meta789 metadata entry from the better-pkg package? [y/N]: y
Removing metadata entry meta789 from the 'better-pkg' package ... OK

Removed metadata entry meta789.

Use -y/--yes to skip confirmation in scripts.

Example: invalid JSON returns a usage error before calling the API

cloudsmith metadata add your-org/awesome-repo/better-pkg \
  --content-type application/json \
  --content '{not json'

Error: Invalid JSON in --content: Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

--file and --content are mutually exclusive; passing both also errors out before the API call.

Example: JSON output

cloudsmith metadata list your-org/awesome-repo/better-pkg -F json
cloudsmith metadata remove your-org/awesome-repo/better-pkg meta789 -y -F json

JSON mode emits the API payload (or, for remove, {"deleted": true, "slug_perm": "..."}) so the commands compose cleanly with jq and other tooling.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Additional Notes

CLI tests cover help text, list pagination and filters, JSON output, single-entry retrieval, inline/file/stdin content loading, invalid JSON handling, update argument validation, and remove confirmation behavior. The underlying v2 metadata API client has its own httpretty-backed test suite covering URL shape, auth header precedence, query-param normalisation, and 404/422 error surfacing.

Local checks and testing completed.

[Copilot]

Pull request overview

Adds a new cloudsmith metadata CLI command group to manage v2 package metadata entries (list/get/add/update/remove), including slug resolution via the existing packages API.

Changes:

• Introduces cloudsmith metadata command group with CRUD subcommands, JSON/table output, pagination support, and destructive-action confirmation for removals.
• Adds core.api.packages.get_package_slug_perm() helper to resolve a package’s permanent slug for metadata endpoints.
• Adds CLI test coverage for help text, list pagination/filters, JSON output, content loading (inline/file/stdin), validation, update behavior, and remove confirmation.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
cloudsmith_cli/core/api/packages.py	Adds get_package_slug_perm() to resolve a package slug_perm for downstream calls.
cloudsmith_cli/cli/commands/metadata.py	Implements the new metadata command group and its subcommands (CRUD + formatting/content loading).
cloudsmith_cli/cli/commands/__init__.py	Registers the new metadata command module so Click loads the group.
cloudsmith_cli/cli/tests/commands/test_metadata.py	Adds a comprehensive test suite for the new command group.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[BartoszBlizniak]

Pausing merge - working on scoping a validation endpoint, which may require some additional changes here.