{"id":8900,"library":"cloudsmith-cli","title":"Cloudsmith CLI","description":"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.","status":"active","version":"1.16.0","language":"en","source_language":"en","source_url":"https://github.com/cloudsmith-io/cloudsmith-cli","tags":["cli","package-management","cloudsmith","devops","artifacts","ci-cd"],"install":[{"cmd":"pip install --upgrade cloudsmith-cli","lang":"bash","label":"Install or upgrade via pip"}],"dependencies":[{"reason":"Command-line interface toolkit","package":"click","optional":false},{"reason":"HTTP client for making API calls","package":"requests","optional":false},{"reason":"Python 2 and 3 compatibility utilities","package":"six","optional":false},{"reason":"YAML parsing and emitting","package":"pyyaml","optional":false},{"reason":"Utility belt for the Requests library","package":"requests-toolbelt","optional":false},{"reason":"Project setup and distribution","package":"setuptools","optional":false},{"reason":"TOML configuration file parser","package":"toml","optional":false},{"reason":"HTTP client library, often a dependency of requests","package":"urllib3","optional":false},{"reason":"Mozilla's CA Bundle for SSL verification","package":"certifi","optional":false},{"reason":"Internationalized Domain Names in Applications","package":"idna","optional":false},{"reason":"Universal character encoding detector","package":"charset-normalizer","optional":false}],"imports":[],"quickstart":{"code":"# Install the CLI (if not already installed)\npip install --upgrade cloudsmith-cli\n\n# Authenticate with Cloudsmith using an API Key (recommended for CI/CD)\n# Set CLOUDSMITH_API_KEY environment variable\nexport CLOUDSMITH_API_KEY=\"$CLOUDSMITH_API_KEY\"\n\n# Or for interactive login (SAML/SSO supported from v1.3.1+)\n# cloudsmith auth\n\n# Verify authentication\ncloudsmith whoami\n\n# Example: List repositories in your organization\ncloudsmith list repos OWNER\n\n# Example: Push a Python package\n# cloudsmith push python OWNER/REPOSITORY path/to/your/package.whl","lang":"bash","description":"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."},"warnings":[{"fix":"Upgrade to `cloudsmith-cli>=1.11.1`.","message":"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.","severity":"breaking","affected_versions":"1.11.0"},{"fix":"For SAML/SSO, use `cloudsmith auth`. For automation, set `CLOUDSMITH_API_KEY` or use a `credentials.ini` file.","message":"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.","severity":"gotcha","affected_versions":"<1.3.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Check package metadata for correctness. If a package is corrupt, fix and re-upload. For temporary issues, try `cloudsmith resync OWNER/REPOSITORY/PACKAGE`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Usage: cloudsmith login [OPTIONS] COMMAND [ARGS]... Try \"cloudsmith login -h\" for help. Error: Missing command."},{"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.","cause":"The `--credentials-file` argument was passed a directory path instead of a specific file path (e.g., `./credentials.ini`).","error":"Error: Invalid value for \"--credentials-file\": Path \".\" is a directory."},{"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.","cause":"This usually indicates that the GPG key required to verify packages from the Cloudsmith repository has not been installed on your system.","error":"Error: Could not import the GPG key for this repository"},{"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.","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.","error":"Why am I encountering a 404 ERROR even though my package was uploaded and synchronized successfully?"}]}