Cloudsmith Command Line Interface (CLI)

The Cloudsmith Command Line Interface (CLI) is a Python 3 text-based interface to the API. This allows users, machines and other services to access and integrate smoothly with Cloudsmith without requiring explicit plugins or tools. Be awesome. Automate Everything.

The following asciinema video demonstrates some of the CLI commands:

We also have a demo video on YouTube:

You can also read our blog article that introduced the first version of the CLI and the Cloudsmith RESTful API.

Changelog

Please see the changelog 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: [DEPRECATED] Retrieve your API authentication token/key via login.
• logout: Clear stored authentication credentials and SAML 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.

Installation

You can install the latest CLI application from:

• Official CLI Repository @ PyPi
• Official CLI Repository @ Cloudsmith

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 (or the Cloudsmith CLI repository), verify it against the accompanying .sha256 file, extract it, and add the extracted cloudsmith directory to your PATH:

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.

GCP OIDC Support

For Google Cloud environments (GCE, Cloud Run, GKE, Cloud Functions, App Engine, Cloud Build), install with the gcp extra to enable automatic credential discovery:

pip install cloudsmith-cli[gcp]

This installs google-auth for Application Default Credentials (ADC) resolution and OIDC ID token generation. It works with an attached Google Cloud service account, a service-account key supplied through GOOGLE_APPLICATION_CREDENTIALS, or service-account impersonation configured locally:

gcloud auth application-default login --impersonate-service-account=SERVICE_ACCOUNT_EMAIL
cloudsmith whoami --workspace=YOUR_WORKSPACE --oidc-service-slug=YOUR_SERVICE --oidc-detector-order=gcp

Configure a Cloudsmith OIDC provider to trust https://accounts.google.com, the service account's numeric unique ID as the subject, and audience cloudsmith (override with --oidc-audience or CLOUDSMITH_OIDC_AUDIENCE). Local impersonation requires the Service Account Token Creator role on the target service account and the IAM Service Account Credentials API enabled.

On workloads with a metadata identity endpoint, the CLI requests an ID token directly. If that endpoint returns HTTP 404 (as on some Cloud Build environments), it uses IAM generateIdToken for the same attached service account. This fallback requires the IAM Service Account Credentials API and iam.serviceAccounts.getOpenIdToken on that account; the Service Account OpenID Connect Identity Token Creator role grants this permission. Permission and transport failures are reported, not treated as a missing endpoint.

A plain gcloud auth application-default login user session cannot mint an ID token for an arbitrary audience. To use it, set --oidc-audience to the session's OAuth client ID and configure Cloudsmith to trust that audience and user subject; otherwise use service-account impersonation. gcloud auth login alone does not configure ADC. Other ADC types, including direct external-account federation, are skipped rather than incorrectly treated as ID-token-capable credentials.

See Google's Authenticate with auth libraries guide for credential discovery.

All Optional Features

To install all optional dependencies:

pip install cloudsmith-cli[all]

Note: If you don't install the AWS or GCP extra, the corresponding 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>):

pipelines:
  default:
    - step:
        oidc: true
        script:
          - cloudsmith push ...

See the Bitbucket Pipelines OIDC documentation.

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.

Buildkite OIDC Support

In Buildkite, OIDC credential discovery works out of the box with no extra dependencies — the CLI requests a token for the current job through buildkite-agent oidc request-token. By default it requests the cloudsmith audience; use --oidc-audience or CLOUDSMITH_OIDC_AUDIENCE if your Cloudsmith OIDC provider expects a different audience. See the Buildkite OIDC documentation.

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.

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.

GitLab CI OIDC Support

In GitLab CI/CD, OIDC credential discovery works out of the box with no extra dependencies. Configure an id_tokens 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:

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.

Generic OIDC Support (Jenkins, custom CI/CD)

As a fallback for environments without a dedicated detector (for example Jenkins with the credentials binding plugin, 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.

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, buildkite, circleci, gcp, generic, github, gitlab.

Both controls can also be set in config.ini, under [default] or a profile section:

[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 SAML access and refresh tokens in the system keyring using the keyring library.

Non-Credentials (config.ini)

See the default config in GitHub:

You can specify the following configuration options:

• api_host: The API host to connect to.
• proxy: The proxy to connect through for all HTTP requests, including API, SAML, upload, download, MCP, update, credential helper, OIDC, and error report connections. Use --proxy or CLOUDSMITH_PROXY to set it for one command. The config key api_proxy, flag --api-proxy, and environment variable CLOUDSMITH_API_PROXY remain supported for compatibility. In config and environment variables, the new name takes precedence over the alias. Without proxy, the CLI uses the HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables. When proxy is set, it takes precedence over them.
• ssl_verify: Whether or not to verify SSL certificates for HTTPS requests, including API, SAML, uploads, downloads, and MCP (default: true). Use CLOUDSMITH_SSL_VERIFY=1 to enable verification or CLOUDSMITH_SSL_VERIFY=0 / --without-ssl-verify to disable it. Disabling verification is dangerous; prefer disabling only strict checks where possible. The config key api_ssl_verify, flag --without-api-ssl-verify / -S, and environment variable CLOUDSMITH_WITHOUT_API_SSL_VERIFY remain supported for compatibility. Command-line settings override environment variables, which override config; within the same source, the new spelling takes precedence.
• ssl_verify_strict: Whether or not to apply strict X.509 certificate verification (VERIFY_X509_STRICT, enabled by default on Python 3.13+). Set to false (or use --without-ssl-verify-strict / CLOUDSMITH_SSL_VERIFY_STRICT=0) if a TLS-intercepting proxy issues certificates that fail these checks. CLOUDSMITH_SSL_VERIFY_STRICT=1 keeps strict verification enabled (the default). Certificates are still verified.
• api_user_agent: The user agent to use for requests.

Credentials (credentials.ini)

See the default config 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 ...
Your organization's SAML IDP URL is: https://example.com/some-saml-idp

Waiting for the authentication callback on port 12400 ...

Authentication complete

The CLI opens the IDP URL in your browser automatically. If it can't (for example in Cygwin or a headless shell), it tells you to open the URL above manually and carries on waiting for the callback. Use --no-browser to skip the automatic launch entirely:

cloudsmith auth --owner example --no-browser

Note: The authentication callback is served on 127.0.0.1, on the first free port between 12400 and 12404. The browser you open the URL in must run on the same machine as the CLI.

Getting Your API Key

Get your API key from the Cloudsmith web app: click your user icon in the top right corner, then click Personal API Keys. See API Key for more information. If you authenticated with cloudsmith auth, you can also use cloudsmith tokens create to create an API key.

Give your API key to the CLI in one of these ways:

• Set the CLOUDSMITH_API_KEY environment variable: export CLOUDSMITH_API_KEY=your_key_here.
• Put the key into your credentials.ini file.
• Pass the key to the CLI with the -k your_key_here flag.

Note: The cloudsmith login command and its cloudsmith token alias are deprecated. They retrieve your API key with your email address and password, and they will stop working on November 20, 2026, when Cloudsmith disables username and password login. See the Cloudsmith changelog. After that, both commands fail with a message that explains how to get an API key instead.

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

To upload a Debian source package, give it the .dsc. The source and Debian packaging archives listed in the .dsc are found and uploaded with it:

cloudsmith push deb your-org/your-repo/ubuntu/xenial hello_2.10-3.dsc

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) 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):

   [default]
   metadata_failure_mode = warn
   

Contributing

Yes! Please do contribute, this is why we love open source. Please see CONTRIBUTING 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 and the fine folks who have contributed.