Cloudsmith CLI

1.16.0 · active · verified Thu Apr 16

The Cloudsmith Command-Line Interface (CLI) is a Python 3 based tool that provides a text-based interface to the Cloudsmith API. It enables users, machines, and services to manage packages across various formats (e.g., Python, Maven, Docker, npm, Debian, RPM) directly from the command line, facilitating automation in CI/CD workflows. The library is actively maintained, with frequent releases, and is currently at version 1.16.0.

Common errors

```
Usage: cloudsmith login [OPTIONS] COMMAND [ARGS]... Try "cloudsmith login -h" for help. Error: Missing command.
```
cause Incorrect use of the `login` command, often by passing arguments directly after `login` instead of subcommands if applicable, or when an older version doesn't support a specific login argument structure.

fix For interactive login, simply run `cloudsmith login`. For SAML/SSO, use `cloudsmith auth`. For API key setup without prompts, set `CLOUDSMITH_API_KEY` environment variable.
```
Error: Invalid value for "--credentials-file": Path "." is a directory.
```
cause The `--credentials-file` argument was passed a directory path instead of a specific file path (e.g., `./credentials.ini`).

fix Specify the full path to the credentials file, e.g., `cloudsmith --credentials-file ./credentials.ini <command>`. Ensure the path points to a file, not a directory.
```
Error: Could not import the GPG key for this repository
```
cause This usually indicates that the GPG key required to verify packages from the Cloudsmith repository has not been installed on your system.

fix Download the repository's GPG key from your Cloudsmith repository settings and install it on your system. Consult Cloudsmith documentation for format-specific instructions.
```
Why am I encountering a 404 ERROR even though my package was uploaded and synchronized successfully?
```
cause While a package might appear synchronized, issues like incorrect package identifier in client configuration, repository permissions, or specific package format nuances can lead to 404s on download attempts.

fix Double-check the exact package name/version in your client configuration. Verify repository permissions and access tokens. Consult Cloudsmith documentation specific to your package format for any unique setup requirements. Ensure package visibility is correct.

Warnings

breaking Version 1.11.0 introduced Model Context Protocol (MCP) server support, but these changes were reverted in v1.11.1 due to cross-architecture compatibility issues on non-x86_64 systems. If you experienced issues with v1.11.0, upgrading to v1.11.1 or later resolved them.
Fix: Upgrade to `cloudsmith-cli>=1.11.1`.
gotcha Authentication methods have evolved. Users with SAML/SSO accounts should use `cloudsmith auth` (available from v1.3.1+) for browser-based authentication, as they typically do not have a password for `cloudsmith login`. Previously, SSO users had to retrieve API keys from the web app. API keys remain valid for programmatic use via environment variables (`CLOUDSMITH_API_KEY`) or configuration files.
Fix: For SAML/SSO, use `cloudsmith auth`. For automation, set `CLOUDSMITH_API_KEY` or use a `credentials.ini` file.
gotcha API Key management and secure storage is crucial. While the CLI can auto-configure `credentials.ini`, ensure API keys are not committed to source control. Options include environment variables (`CLOUDSMITH_API_KEY`), CLI flags (`-k`), or OIDC in CI/CD environments.
Fix: Use environment variables (e.g., `export CLOUDSMITH_API_KEY=YOUR_KEY`) or a securely managed `credentials.ini` file. For CI/CD, consider GitHub Actions or CircleCI orbs that support OIDC for ephemeral token generation.
gotcha Package synchronization can fail due to incomplete/maloformed metadata, corruption, or temporary backend issues. Resynchronizing might help for temporary problems, but corrupt packages require fixing and re-uploading.
Fix: Check package metadata for correctness. If a package is corrupt, fix and re-upload. For temporary issues, try `cloudsmith resync OWNER/REPOSITORY/PACKAGE`.

Install

pip install --upgrade cloudsmith-cli Install or upgrade via pip

Quickstart

This quickstart demonstrates installing the Cloudsmith CLI, authenticating using an API key via an environment variable, verifying the authentication, and listing repositories. For interactive use, `cloudsmith auth` is preferred for SAML/SSO users.

# Install the CLI (if not already installed)
pip install --upgrade cloudsmith-cli

# Authenticate with Cloudsmith using an API Key (recommended for CI/CD)
# Set CLOUDSMITH_API_KEY environment variable
export CLOUDSMITH_API_KEY="$CLOUDSMITH_API_KEY"

# Or for interactive login (SAML/SSO supported from v1.3.1+)
# cloudsmith auth

# Verify authentication
cloudsmith whoami

# Example: List repositories in your organization
cloudsmith list repos OWNER

# Example: Push a Python package
# cloudsmith push python OWNER/REPOSITORY path/to/your/package.whl

view raw JSON →