cloudsmith-cli 1.20.0__py3-none-any.whl

cloudsmith_cli-1.20.0.dist-info/METADATA

@@ -0,0 +1,610 @@
+Metadata-Version: 2.4
+Name: cloudsmith-cli
+Version: 1.20.0
+Summary: Cloudsmith Command-Line Interface (CLI)
+Author-email: Cloudsmith Ltd <support@cloudsmith.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/cloudsmith-io/cloudsmith-cli
+Keywords: cloudsmith,cli,devops
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click!=8.3.0,>=8.1.8
+Requires-Dist: click-configfile>=0.2.3
+Requires-Dist: click-didyoumean>=0.0.3
+Requires-Dist: click-spinner>=0.1.7
+Requires-Dist: json5>=0.9.0
+Requires-Dist: cloudsmith-api<3.0,>=2.0.29
+Requires-Dist: keyring>=25.4.1
+Requires-Dist: mcp==1.27.2
+Requires-Dist: PyJWT[crypto]>=2.0.0
+Requires-Dist: python-toon==0.1.2
+Requires-Dist: requests>=2.18.4
+Requires-Dist: requests_toolbelt>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: semver>=2.7.9
+Requires-Dist: urllib3>=2.5
+Provides-Extra: aws
+Requires-Dist: boto3[crt]>=1.26.0; extra == "aws"
+Provides-Extra: all
+Requires-Dist: boto3[crt]>=1.26.0; extra == "all"
+Dynamic: license-file
+
+# Cloudsmith Command Line Interface (CLI)
+
+[![Latest Version @ Cloudsmith](https://api-prd.cloudsmith.io/badges/version/cloudsmith/cli/python/cloudsmith-cli/latest/xf=bdist_wheel;xn=cloudsmith-cli;xv=py2.py3/?render=true)](https://cloudsmith.io/~cloudsmith/repos/cli/packages/detail/python/cloudsmith-cli/latest/xf=bdist_wheel;xn=cloudsmith-cli;xv=py2.py3/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/cloudsmith-cli.svg)](https://pypi.python.org/pypi/cloudsmith-cli)
+[![PyPI Version](https://img.shields.io/pypi/v/cloudsmith-cli.svg)](https://pypi.python.org/pypi/cloudsmith-cli)
+[![GitHub Actions](https://github.com/cloudsmith-io/cloudsmith-cli/actions/workflows/test.yml/badge.svg)](https://github.com/cloudsmith-io/cloudsmith-cli/actions/workflows/test.yml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+
+
+The [Cloudsmith](https://cloudsmith.io) Command Line Interface (CLI) is a Python 3 text-based interface to the [API](https://api.cloudsmith.io). This allows users, machines and other services to access and integrate smoothly with Cloudsmith without requiring explicit plugins or tools. [Be awesome. Automate Everything](https://cloudsmith.com/company/the-tao-of-cloudsmith/).
+
+The following asciinema video demonstrates some of the CLI commands:
+[![asciicast](https://asciinema.org/a/DkNXQWQGBjWkfGPAkDAPNz7xe.svg)](https://asciinema.org/a/DkNXQWQGBjWkfGPAkDAPNz7xe)
+
+We also have a [demo video on YouTube](https://youtu.be/R-g8ZhDwTKk):
+
+You can also read our [blog article](https://blog.cloudsmith.io/2017/11/25/automation-as-simple-as-a-b-cli/) that introduced the first version of the CLI and the Cloudsmith RESTful API.
+
+
+## Changelog
+
+Please see the [changelog](https://github.com/cloudsmith-io/cloudsmith-cli/blob/master/CHANGELOG.md) for the list of changes by version. The current version is displayed in the PyPi badge at the top.
+
+
+## Features
+
+The CLI currently supports the following commands (and sub-commands):
+
+- `authenticate`|`auth`:  Authenticate the CLI against an organization's SAML configuration.
+- `check`:                Check rate limits and service status.
+- `copy`|`cp`:            Copy a package to another repository.
+- `delete`|`rm`:          Delete a package from a repository.
+- `dependencies`|`deps`:  List direct (non-transitive) dependencies for a package.
+- `docs`:                 Launch the help website in your browser.
+- `download`:  Download a package from a repository.
+- `entitlements`|`ents`:  Manage the entitlements for a repository.
+  - `create`|`new`:         Create a new entitlement in a repository.
+  - `delete`|`rm`:          Delete an entitlement from a repository.
+  - `list`|`ls`:            List entitlements for a repository.
+  - `refresh`:              Refresh an entitlement in a repository.
+  - `sync`:                 Sync entitlements from another repository.
+  - `update`|`set`:         Update (patch) a entitlement in a repository.
+- `help`:                 Display the delightful help message and exit.
+- `list`|`ls`:            List distros, packages, repos and entitlements.
+  - `dependencies`|`deps`   List direct (non-transitive) dependencies for a package.
+  - `distros`:              List available distributions.
+  - `entitlements`|`ents`:  List entitlements for a repository.
+  - `packages`:             List packages for a repository. (Aliases `repos list`)
+  - `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.
+- `move`|`mv`|`promote`:  Move (promote) a package to another repo.
+- `policy`:               Manage policies for an organization.
+  - `deny`:                 Manage deny policies for an organization.
+  - `license`:              Manage license policies for an organization.
+  - `vulnerability`:        Manage vulnerability policies for an organization.
+- `push`|`upload`:        Push (upload) a new package to a repository.
+  - `alpine`:               Push (upload) a new Alpine package upstream.
+  - `cargo`:                Push (upload) a new Cargo package upstream.
+  - `composer`:             Push (upload) a new Composer package upstream.
+  - `cocoapods`:            Push (upload) a new CocoaPods package upstream.
+  - `conan`:                Push (upload) a new Conan (C++) package upstream.
+  - `cran`:                 Push (upload) a new R/CRAN package upstream.
+  - `deb`:                  Push (upload) a new Debian package upstream.
+  - `docker`:               Push (upload) a new Docker image upstream.
+  - `go`:                   Push (upload) a new Go module upstream.
+  - `helm`:                 Push (upload) a new Helm package upstream.
+  - `luarocks`:             Push (upload) a new Lua module upstream.
+  - `maven`:                Push (upload) a new Maven package upstream.
+  - `npm`:                  Push (upload) a new Npm package upstream.
+  - `nuget`:                Push (upload) a new NuGet package upstream.
+  - `python`:               Push (upload) a new Python package upstream.
+  - `raw`:                  Push (upload) a new Raw package upstream.
+  - `rpm`:                  Push (upload) a new RedHat package upstream.
+  - `ruby`:                 Push (upload) a new Ruby package upstream.
+  - `terraform`:            Push (upload) a new Terraform package upstream.
+  - `vagrant`:              Push (upload) a new Vagrant package upstream.
+- `quarantine`|`block`:   Manage quarantined packages in a repository.
+  - `add`:                  Add a package to quarantine.
+  - `remove`|`rm`|`restore`: Add a package to quarantine.
+- `quota`:                Quota limits and history for a organisation.
+  - `limits`:               Display the Quota (bandwidth & storage usage/limits) for a specific organisation.
+  - `history`:              Display the Quota History (upload, download, and storage usage/limits) for a specific organisation.
+- `repositories`|`repos`: Manage repositories.
+  - `create`|`new`:         Create a new repository in a namespace.
+  - `get`|`list`|`ls`:      List repositories for a user, in a namespace or get details for a specific repository.
+  - `update`:               Update a repository in a namespace.
+  - `delete`|`rm`:          Delete a repository from a namespace.
+- `resync`:               Resynchronise a package in a repository.
+- `status`:               Get the synchronisation status for a package.
+- `tags`|`tag`:           Manage the tags for a package in a repository.
+  - `add`:                  Add tags to a package in a repository.
+  - `clear`:                Clear all existing (non-immutable) tags from a package in a repository.
+  - `list`|`ls`:            List tags for a package in a repository.
+  - `remove`|`rm`:          Remove tags from a package in a repository.
+  - `replace`:              Replace all existing (non-immutable) tags on a package in a repository.
+- `tokens`:               Manage API tokens.
+  - `list`|`ls`:            List API tokens.
+  - `refresh`:              Refresh an API token.
+- `upstream`:             Manage upstreams for a repository.
+  - `cran`:                 Manage cran upstreams for a repository.
+  - `dart`:                 Manage dart upstreams for a repository.
+  - `deb`:                  Manage deb upstreams for a repository.
+  - `docker`:               Manage docker upstreams for a repository.
+  - `helm`:                 Manage helm upstreams for a repository.
+  - `hex`:                  Manage hex upstreams for a repository.
+  - `maven`:                Manage maven upstreams for a repository.
+  - `npm`:                  Manage npm upstreams for a repository.
+  - `nuget`:                Manage nuget upstreams for a repository.
+  - `python`:               Manage python upstreams for a repository.
+  - `rpm`:                  Manage rpm upstreams for a repository.
+  - `ruby`:                 Manage ruby upstreams for a repository.
+  - `swift`:                Manage swift upstreams for a repository.
+- `vulnerabilities`:      Retrieve vulnerability results for a package.
+- `whoami`:               Retrieve your current authentication status.
+
+## Installation
+
+You can install the latest CLI application from:
+
+- [Official CLI Repository @ PyPi](https://pypi.python.org/pypi/cloudsmith-cli)
+- [Official CLI Repository @ Cloudsmith](https://cloudsmith.io/~cloudsmith/repos/cli/packages/)
+
+The simplest way is to use `pip`, such as:
+
+```
+pip install --upgrade cloudsmith-cli
+```
+
+Or you can get the latest pre-release version from Cloudsmith:
+
+```
+pip install --upgrade cloudsmith-cli --extra-index-url=https://dl.cloudsmith.io/public/cloudsmith/cli/python/index/
+```
+
+### Standalone Binaries
+
+Each release also ships self-contained binaries that bundle Python and all dependencies — no Python installation required. Download the archive for your platform from the [GitHub releases page](https://github.com/cloudsmith-io/cloudsmith-cli/releases) (or the [Cloudsmith CLI repository](https://cloudsmith.io/~cloudsmith/repos/cli/packages/)), verify it against the accompanying `.sha256` file, extract it, and add the extracted `cloudsmith` directory to your `PATH`:
+
+```bash
+tar -xzf cloudsmith-<version>-<target>.tar.gz
+./cloudsmith/cloudsmith --version
+```
+
+Available targets: `linux-x86_64-gnu`, `linux-x86_64-musl`, `linux-aarch64-gnu`, `linux-aarch64-musl`, `macos-arm64`, `macos-x86_64`, and `windows-x86_64` (as a `.zip`).
+
+Standalone binaries include all optional features, including AWS OIDC support.
+
+#### Verifying Linux binaries
+
+The four Linux archives (`linux-x86_64-gnu`, `linux-x86_64-musl`, `linux-aarch64-gnu`, `linux-aarch64-musl`) are GPG-signed with a detached binary signature published alongside each archive as `<archive>.sig`. To verify, import the Cloudsmith CLI release public key (`cloudsmith-cli-release-key.asc`, attached to each GitHub release) and check the signature:
+
+```
+gpg --import cloudsmith-cli-release-key.asc
+gpg --verify cloudsmith-<version>-linux-x86_64-gnu.tar.gz.sig cloudsmith-<version>-linux-x86_64-gnu.tar.gz
+```
+
+A successful verification reports a good signature from the Cloudsmith CLI release key. (The macOS and Windows binaries are not GPG-signed; native signing for those platforms is tracked separately.)
+
+### Optional Dependencies
+
+The CLI supports optional extras for additional functionality:
+
+#### AWS OIDC Support
+
+For AWS environments (ECS, EKS, EC2), install with `aws` extra to enable automatic credential discovery:
+
+```
+pip install cloudsmith-cli[aws]
+```
+
+This installs `boto3[crt]` for AWS credential chain support, STS token generation, and AWS SSO compatibility.
+
+#### All Optional Features
+
+To install all optional dependencies:
+
+```
+pip install cloudsmith-cli[all]
+```
+
+**Note:** If you don't install the AWS extra, the AWS OIDC detector will gracefully skip itself with no errors.
+
+#### Bitbucket Pipelines OIDC Support
+
+In Bitbucket Pipelines, OIDC credential discovery works out of the box with no extra dependencies. Set `oidc: true` on the pipeline step and the CLI reads the token from the `BITBUCKET_STEP_OIDC_TOKEN` variable that Bitbucket populates. The Cloudsmith OIDC provider must expect the workspace audience that Bitbucket mints (`ari:cloud:bitbucket::workspace/<workspace-uuid>`):
+
+```yaml
+pipelines:
+  default:
+    - step:
+        oidc: true
+        script:
+          - cloudsmith push ...
+```
+
+See the [Bitbucket Pipelines OIDC documentation](https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/).
+
+#### CircleCI OIDC Support
+
+In CircleCI, OIDC credential discovery works out of the box with no extra dependencies — the CLI reads the token from the `CIRCLE_OIDC_TOKEN_V2` (preferred) or `CIRCLE_OIDC_TOKEN` environment variable that CircleCI injects into every job. The Cloudsmith OIDC provider must expect the audience CircleCI mints, which is your CircleCI organization UUID. See the [Cloudsmith CircleCI integration guide](https://docs.cloudsmith.com/integrations/integrating-with-circleci).
+
+#### Azure DevOps OIDC Support
+
+In Azure DevOps Pipelines, OIDC credential discovery works out of the box with no extra dependencies — the CLI fetches an OIDC token from the `SYSTEM_OIDCREQUESTURI` endpoint using the pipeline's `SYSTEM_ACCESSTOKEN`. Make sure `SYSTEM_ACCESSTOKEN` is mapped into the step's environment. The Cloudsmith OIDC provider must expect the audience `api://AzureADTokenExchange`, which Azure DevOps always mints (any requested audience is ignored). See the [Cloudsmith Azure DevOps integration guide](https://docs.cloudsmith.com/integrations/integrating-with-azure-devops).
+
+#### GitHub Actions OIDC Support
+
+In GitHub Actions, OIDC credential discovery works out of the box with no extra dependencies — the CLI fetches an OIDC token from the Actions runtime when the workflow requests `id-token: write` permission. See the [Cloudsmith GitHub Actions OIDC guide](https://docs.cloudsmith.com/authentication/setup-cloudsmith-to-authenticate-with-oidc-in-github-actions).
+
+#### GitLab CI OIDC Support
+
+In GitLab CI/CD, OIDC credential discovery works out of the box with no extra dependencies. Configure an [`id_tokens`](https://docs.gitlab.com/ci/cloud_services/) entry in your `.gitlab-ci.yml` with an `aud` of `https://api.cloudsmith.io/openid/<your-org>` and expose it as `CLOUDSMITH_OIDC_TOKEN`, and the CLI will pick it up automatically:
+
+```yaml
+job:
+  id_tokens:
+    CLOUDSMITH_OIDC_TOKEN:
+      aud: https://api.cloudsmith.io/openid/<your-org>
+  script:
+    - cloudsmith push ...
+```
+
+See the [Cloudsmith GitLab CI/CD integration guide](https://docs.cloudsmith.com/integrations/integrating-with-gitlab-cicd).
+
+#### Generic OIDC Support (Jenkins, custom CI/CD)
+
+As a fallback for environments without a dedicated detector (for example Jenkins with the [credentials binding plugin](https://plugins.jenkins.io/credentials-binding/), or any custom CI/CD system), set the `CLOUDSMITH_OIDC_TOKEN` environment variable to an OIDC JWT and the CLI will exchange it for a Cloudsmith access token. This detector runs last, so a dedicated environment is always preferred when present. See the [Cloudsmith Jenkins OIDC guide](https://docs.cloudsmith.com/authentication/setup-jenkins-to-authenticate-to-cloudsmith-using-oidc).
+
+#### Controlling OIDC Detector Selection
+
+By default the CLI tries each detector in a fixed priority order and uses the first that matches. Two controls let you override this when a detector matches an environment you don't want it to (for example, the AWS detector matching ambient instance credentials):
+
+- **Disable a detector** — set `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED=true` to skip it entirely. Only the literal value `true` (case-insensitive) disables; anything else leaves the detector enabled. For example, `CLOUDSMITH_OIDC_AWS_DISABLED=true` skips the AWS detector so an explicitly-set `CLOUDSMITH_OIDC_TOKEN` is picked up by the generic detector instead.
+- **Reorder evaluation** — use `--oidc-detector-order` (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) with a comma-separated list of detector ids to control both which detectors are considered and the order they are tried in (first match wins). Ids not listed are skipped; unrecognised ids are ignored with a warning. For example, `--oidc-detector-order=generic,aws` tries the generic detector first and considers only those two.
+
+When both are set, the order list defines the candidate set and sequence, then the `*_DISABLED` flags are applied on top — so a disabled detector is always skipped even if it appears in the order list. Detector ids are: `aws`, `azure_devops`, `bitbucket`, `circleci`, `generic`, `github`, `gitlab`.
+
+Both controls can also be set in `config.ini`, under `[default]` or a profile section:
+
+```ini
+[default]
+oidc_detector_order = github, aws
+oidc_disabled_detectors = aws, gitlab
+```
+
+The `--oidc-detector-order` flag (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) overrides the `oidc_detector_order` config value. The `oidc_disabled_detectors` config key is additive with the per-detector `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED` environment variables — a detector disabled by either is skipped.
+
+## Configuration
+
+There are two configuration files used by the CLI:
+
+- `config.ini`: For non-credentials configuration.
+- `credentials.ini`: For credentials (authentication) configuration.
+
+By default, the CLI will look for these in the following locations:
+
+- The current working directory.
+- A directory called `cloudsmith` in the OS-defined application directory. For example:
+  - Linux:
+    - `$HOME/.config/cloudsmith`
+    - `$HOME/.cloudsmith`
+  - Mac OS:
+    - `$HOME/Library/Application Support/cloudsmith`
+    - `$HOME/.cloudsmith`
+  - Windows:
+    - `C:\Users\<user>\AppData\Local\cloudsmith` (Win7+, not roaming)
+    - `C:\Users\<user>\AppData\Roaming\cloudsmith` (Win7+, roaming)
+    - `C:\Documents and Settings\<user>\Application Data\cloudsmith` (WinXP, not roaming)
+    - `C:\Documents and Settings\<user>\Local Settings\Application Data\cloudsmith` (WinXP, roaming)
+    - `C:\Documents and Settings\<user>\.cloudsmith`
+
+Both configuration files use the simple INI format, such as:
+
+```
+[default]
+api_key=1234567890abcdef1234567890abcdef
+```
+
+Additionally, the CLI will store SSO access and refresh tokens in the system keyring
+using the [`keyring`](https://github.com/jaraco/keyring) library.
+
+
+### Non-Credentials (config.ini)
+
+See the [default config](https://raw.githubusercontent.com/cloudsmith-io/cloudsmith-cli/master/cloudsmith_cli/data/config.ini) in GitHub:
+
+You can specify the following configuration options:
+
+- `api_host`: The API host to connect to.
+- `api_proxy`: The API proxy to connect through.
+- `api_ssl_verify`: Whether or not to use SSL verification for requests.
+- `api_user_agent`: The user agent to use for requests.
+
+### Credentials (credentials.ini)
+
+See the [default config](https://raw.githubusercontent.com/cloudsmith-io/cloudsmith-cli/master/cloudsmith_cli/data/credentials.ini) in GitHub:
+
+You can specify the following configuration options:
+
+- `api_key`: The API key for authenticating with the API.
+
+
+### Authenticating
+
+You'll need to provide authentication to Cloudsmith for any CLI actions that result in accessing private data or making changes to resources (such as pushing a new package to a repository)..
+
+#### SAML authentication
+
+You can authenticate using your organization's SAML provider, if configured, with the `cloudsmith auth` command:
+```
+cloudsmith auth --owner example
+Beginning authentication for the example org ...
+Opening your organization's SAML IDP URL in your browser: https://example.com/some-saml-idp
+
+Starting webserver to begin authentication ...
+
+Authentication complete
+```
+
+#### Getting Your API Key
+
+You can retrieve your API key using the `cloudsmith login` command:
+
+```
+cloudsmith login
+Login: you@example.com
+Password:
+Repeat for confirmation:
+```
+
+*Note:* Please ensure you use your email for the 'Login' prompt and not your user slug/identifier.
+
+The resulting output looks something like:
+
+```
+Retrieving API token for 'you@example.com' ... OK
+Your API token is: 1234567890abcdef1234567890abcdef
+```
+
+Once you have your API key you can then put this into your `credentials.ini`, use it as an environment variable `export CLOUDSMITH_API_KEY=your_key_here` or pass it to the CLI using the `-k your_key_here` flag.
+
+For convenience the CLI will ask you if you want to install the default configuration files, complete with your API key, if they don't already exist. Say 'y' or 'yes' to create the configuration files.
+
+If the configuration files already exist, you'll have to manually put the API key into the configuration files, but the CLI will print out their locations.
+
+
+## Uploading Packages
+
+Although native uploads, i.e. those supported by the native ecosystem of a package format, are often preferred; it's easy to publish with the Cloudsmith CLI too!
+
+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-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:
+
+```
+cloudsmith push rpm --help
+```
+
+
+## Downloading Packages
+
+You can download packages from repositories using the `cloudsmith download` command. The CLI supports various filtering options to help you find and download the exact package you need.
+
+For example, to download a specific package:
+
+```
+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-org/your-repo package-name --version 1.2.3
+
+# Filter by format and architecture
+cloudsmith download your-org/your-repo package-name --format deb --arch amd64
+
+# Filter by package tag (e.g., latest, stable, beta)
+cloudsmith download your-org/your-repo package-name --tag latest
+
+# Combine tag with metadata filters
+cloudsmith download your-org/your-repo package-name --tag stable --format deb --arch arm64
+
+# Filter by filename (exact or glob pattern)
+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-org/your-repo package-name --download-all
+
+# Combine --download-all with --filename to download a subset
+cloudsmith download your-org/your-repo package-name --download-all --filename '*.snupkg'
+
+# Download all associated files (POM, sources, javadoc, etc.)
+cloudsmith download your-org/your-repo package-name --all-files
+
+# Preview what would be downloaded without actually downloading
+cloudsmith download your-org/your-repo package-name --dry-run
+```
+
+For more advanced usage and all available options:
+
+```
+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).
+
+
+## License
+
+Copyright 2018 Cloudsmith Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+## EOF
+
+This quality product was brought to you by [Cloudsmith](https://cloudsmith.io) and the [fine folks who have contributed](https://github.com/cloudsmith-io/cloudsmith-cli/blob/master/CONTRIBUTORS.md).