Developer tools

Command-line interface

The Cloudsmith Command Line Interface (CLI) is a 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. Install the CLI as a standalone binary for Linux, macOS, or Windows, or as a Python package from PyPI.

Migrating from our .pyz (Python ZipApp)? Use the cloudsmith-cli install script in your workflows, or see the other installation options in the Cloudsmith CLI repository.

Installation

You can install or deploy the latest CLI application from:

• Cloudsmith - the cloudsmith/cli repository hosts standalone binaries and Python packages
• PyPI
• Install script releases
• Homebrew Tap
• DockerHub

In CI/CD pipelines, use the official integrations for GitHub Actions, Azure DevOps, and CircleCI, which install the standalone CLI and configure authentication for you.

Installing with pip

The Python package remains available for Python environments and requires Python 3.10 or later:

python3 -m pip install --upgrade cloudsmith-cli

Install the aws extra to enable automatic credential discovery in AWS environments:

python3 -m pip install --upgrade 'cloudsmith-cli[aws]'

Installing with the install script

With one command, the install scripts detect your platform, download the matching standalone binary from the cloudsmith/cli repository, verify its SHA-256 checksum, and install it into a versioned directory.

On Linux or macOS:

curl -fsSL https://install.cloudsmith.com/raw/versions/latest/cli.sh | sh

On Windows:

irm https://install.cloudsmith.com/raw/versions/latest/cli.ps1 | iex

To verify the installer before running it, or to pin the installer and CLI versions (recommended for CI), download the installer and SHA256SUMS from the same tagged installer release.

On Linux or macOS:

set -eu

installer_version=v0.1.2
installer_url="https://github.com/cloudsmith-io/cloudsmith-cli-install-script/releases/download/$installer_version"
curl -fsSLO "$installer_url/install.sh"
curl -fsSLO "$installer_url/SHA256SUMS"

expected_checksum="$(awk '$2 == "install.sh" {print $1}' SHA256SUMS)"
if command -v sha256sum >/dev/null 2>&1; then
  actual_checksum="$(sha256sum install.sh | awk '{print $1}')"
elif command -v shasum >/dev/null 2>&1; then
  actual_checksum="$(shasum -a 256 install.sh | awk '{print $1}')"
elif command -v openssl >/dev/null 2>&1; then
  actual_checksum="$(openssl dgst -sha256 install.sh | awk '{print $NF}')"
else
  echo "sha256sum, shasum, or openssl is required" >&2
  exit 1
fi
test -n "$expected_checksum"
test "$actual_checksum" = "$expected_checksum"

sh ./install.sh --version 1.20.1

On Windows:

$installerVersion = "v0.1.2"
$installerUrl = "https://github.com/cloudsmith-io/cloudsmith-cli-install-script/releases/download/$installerVersion"
Invoke-WebRequest "$installerUrl/install.ps1" -OutFile install.ps1
Invoke-WebRequest "$installerUrl/SHA256SUMS" -OutFile SHA256SUMS

$checksumLine = Get-Content SHA256SUMS | Where-Object { $_ -match '\sinstall\.ps1$' }
if (-not $checksumLine) { throw "SHA256SUMS does not contain install.ps1" }
$expectedChecksum = ($checksumLine -split '\s+')[0].ToLowerInvariant()
$actualChecksum = (Get-FileHash install.ps1 -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actualChecksum -ne $expectedChecksum) { throw "install.ps1 checksum mismatch" }

./install.ps1 -Version 1.20.1

On success, the script prints four key=value lines. Add the reported bin_dir to PATH, or invoke the reported executable directly:

version=1.20.1
target=linux-x86_64-gnu
bin_dir=/home/user/.local/share/cloudsmith-cli/1.20.1/linux-x86_64-gnu/cloudsmith
executable=/home/user/.local/share/cloudsmith-cli/1.20.1/linux-x86_64-gnu/cloudsmith/cloudsmith

Pass latest as the version value (--version latest or -Version latest) to install the newest release. For reproducible CI builds, pin a specific CLI version instead of latest.

The installer does not modify PATH. Add the reported bin_dir to your PATH (or invoke the reported executable directly), and you are ready to use the Cloudsmith CLI:

cloudsmith -h

Installing with Homebrew

Homebrew is available on macOS and Linux. To install the Cloudsmith CLI with Homebrew:

brew install cloudsmith-io/cloudsmith-cli/cloudsmith-cli

And you should be able to start using it. If you need to upgrade:

brew upgrade cloudsmith-io/cloudsmith-cli/cloudsmith-cli

For issues with the tap, please open a GitHub issue or contact support@cloudsmith.com.

Deploying the CLI containerized

Cloudsmith maintains a Docker image for the Cloudsmith CLI⁠ built for use in CI/CD pipelines and automation environments.

To deploy it, replace the API_TOKEN with the API Token associated to the service account you want to use, specifying the Cloudsmith CLI command you want to use. For example, you can run cloudsmith whoami:

docker run --rm \
-e CLOUDSMITH_API_KEY=API_TOKEN \
cloudsmith/cloudsmith-cli:1.20.1 \
whoami

Successful execution of the command above will return the member or service account associated to the API Token used:

Retrieving your authentication status from the API ... OK
You are authenticated as:
User: M. Bolton (slug: mbolton, email: mbolton@initech.com)

For example, you can use the Cloudsmith CLI container to push a python package to your workspace/repository WORKSPACE/REPOSITORY. In this example, the python package PACKAGE.whl is located in /path_to_package/, and the package is being mounted in the container filesystem in /tmp/ as my_package.whl:

docker run --rm \
-e CLOUDSMITH_API_KEY=API_TOKEN \
-v "/path_to_package/PACKAGE.whl:/tmp/my_package.whl" \
cloudsmith/cloudsmith-cli:1.20.1 \
push python WORKSPACE/REPOSITORY /tmp/my_package.whl 

Successful execution of the command will return:

Checking python package upload parameters ... OK
Checking PACKAGE.whl file upload parameters ... OK
Requesting file upload for PACKAGE.whl ... OK
Uploading PACKAGE.whl:
Creating a new python package ... OK
Created: WORKSPACE/REPOSITORY/PACKAGEwhl (package_slug)

Synchronising PACKAGEwhl:

Package synchronised successfully in 6.001236 second(s)!

Authenticating in CI/CD with OIDC

In CI/CD environments, OpenID Connect (OIDC) is the recommended authentication method because it uses short-lived credentials instead of a stored API key. The GitHub Actions, Azure DevOps, and CircleCI integrations set the required environment variables from their inputs automatically.

To configure OIDC manually, or for other CI/CD platforms, see Automatically discover OIDC credentials. See also OpenID Connect to configure an OIDC provider for your workspace.

Getting your API key

You'll need to authenticate Cloudsmith for any CLI actions that result in accessing private data or changing resources (such as pushing a new package to a repository). There are two ways to retrieve your API Key:

1. Via the Cloudsmith web app

Go to the API Key page in your user settings to view the API Key.

2. via the Cloudsmith CLI

You can retrieve your API key using the cloudsmith login command:

cloudsmith login
Login: you@example.com
Password: PASSWORD
Repeat for confirmation: PASSWORD

Use email for login

Please ensure you use your email for the 'Login' prompt and not your user slug/identifier.

The resulting output is:

Retrieving API token for 'you@example.com' ... OK
Your API token is: 1234567890abcdef1234567890abcdef

Once you have your API key, you can put it in your credentials.ini file, use it as an environment variable export CLOUDSMITH_API_KEY=<YOUR_API_KEY>, or pass it to the CLI using the -k <YOUR_API_KEY> 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. Enter y or yes to create the configuration files.

If the configuration files already exist, you'll have to put the API key into the configuration files manually, but the CLI will print out their locations.

SAML single sign-on users

SSO users do not have a Cloudsmith password and cannot use the cloudsmith login command to retrieve their API key.

SSO users should instead use the cloudsmith auth command and pass their workspace identifier: cloudsmith auth --workspace my-workspace

You will then be prompted to complete the SSO login process via your web browser (if not already signed in), and 2FA if applicable. Once authentication is complete, the CLI is issued an access token for your account.

Authenticate without opening a browser automatically

Use --no-browser when the CLI should not try to launch a browser:

cloudsmith auth --workspace WORKSPACE --no-browser

Replace WORKSPACE with your workspace slug.

The CLI prints the SAML identity provider URL. Open that URL manually and complete authentication. If an automatic browser launch fails without --no-browser, the CLI also prints the URL instead of stopping.

Local callback required

The SAML flow still returns to the CLI's callback server on 127.0.0.1:12400. When the CLI runs on a remote host, forward local port 12400 to the remote host before opening the URL, for example with ssh -L 12400:127.0.0.1:12400 USER@HOST.

Configuration / setup

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)

config.ini

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.
• workspace: The workspace slug used for authentication, OIDC, and custom-domain discovery.

The default config is:

# Default configuration
[default]
# The API host to connect to (default: api.cloudsmith.io).
api_host=

# The API proxy to connect through (default: None).
api_proxy=

# Whether to verify SSL connection to the API (default: True)
api_ssl_verify=true

# The user agent to use for requests (default: calculated).
api_user_agent=

# The Cloudsmith workspace slug (default: None).
workspace=

# Profile-based configuration
# You can set as many additional profiles as you need to provide
# for different configuration environments (e.g. prod vs staging).
# Add your overrides in the sections and then specify one of:
#  * -P your-profile-name (as an argument)
#  * --profile your-profile-name (an an argument)
#  * CLOUDSMITH_PROFILE=your-profile-name (as an env variable)
[profile:your-profile-name]

credentials.ini

You can specify the following configuration options:

api_key: The API key for authenticating with the API.

# Default configuration
[default]
# The API key for authenticating with the API.
api_key=<YOUR_API_KEY>


# Profile-based configuration
# You can set as many additional profiles as you need to provide
# for different configuration environments (e.g. prod vs staging).
# Add your overrides in the sections and then specify one of:
#  * -P your-profile-name (as an argument)
#  * --profile your-profile-name (an an argument)
#  * CLOUDSMITH_PROFILE=your-profile-name (as an env variable)
[profile:your-profile-name]

Store tokens in headless environments

The Cloudsmith CLI uses the Python keyring library to store SSO and OIDC tokens. A keyring backend is the storage implementation used by that library.

On a workstation, keyring normally selects an operating-system backend automatically, such as macOS Keychain, Windows Credential Locker, or Linux Secret Service. No keyring environment variables are required when that backend is available.

Configure a file-based backend when both of the following apply:

• The host has no usable operating-system keyring, such as a headless Linux container.
• An SSO or OIDC token must persist between CLI commands or container restarts.

A file backend is usually unnecessary for an ephemeral CI job that supplies CLOUDSMITH_API_KEY or exchanges an OIDC token on each run.

Choose a backend

CLOUDSMITH_KEYRING_BACKEND selects the Python class that stores and retrieves tokens. Its value is a fully qualified Python class name in the form package.module.ClassName.

The Cloudsmith CLI includes the following encrypted file backends:

For example, keyrings.cryptfile.cryptfile.CryptFileKeyring means:

• Import the keyrings.cryptfile.cryptfile Python module.
• Use its CryptFileKeyring class as the active backend.

Python keyring supports other third-party backends, but the backend package must be available to the CLI.

Set the encryption password

CLOUDSMITH_KEYRING_KEY is the password that encrypts and unlocks the file-based keyring. It is not a Cloudsmith API key or access token.

Set it to a non-empty string. Use a strong, randomly generated value from a secret manager, and supply the same value every time the keyring is opened. Without it, an encrypted backend prompts interactively by using getpass(). If the value is lost, the tokens in that keyring file cannot be recovered.

The keyrings.cryptfile documentation describes the backend's keyring_key property and non-interactive unlock behavior.

Choose the file location

Set one of the following Cloudsmith variables:

With CryptFileKeyring, setting CLOUDSMITH_KEYRING_DIR=/var/lib/cloudsmith-keyring stores tokens in /var/lib/cloudsmith-keyring/cryptfile_pass.cfg.

The Cloudsmith path variables expand ~ and environment variables. Persist the chosen path on a protected volume if tokens must survive container replacement.

Configure the complete headless flow

This example selects the recommended encrypted backend, reads its password from a secret injected by the platform, and stores the encrypted file on a persistent volume:

export CLOUDSMITH_KEYRING_BACKEND=keyrings.cryptfile.cryptfile.CryptFileKeyring
export CLOUDSMITH_KEYRING_KEY="$KEYRING_PASSWORD"
export CLOUDSMITH_KEYRING_DIR=/var/lib/cloudsmith-keyring

cloudsmith auth --workspace WORKSPACE --no-browser
cloudsmith whoami

--no-browser controls only whether cloudsmith auth launches a browser. The keyring settings control how the resulting tokens are stored.

Use the Python keyring variable names

The Cloudsmith variables are aliases for Python keyring configuration. Use the Cloudsmith names when the setting should apply only to the Cloudsmith CLI. Use the Python names when other applications in the same environment must share the same keyring configuration.

Python keyring uses KEYRING_PROPERTY_<NAME> variables to set a backend property named <name>. For example, KEYRING_PROPERTY_FILE_PATH sets the backend's file_path property, and KEYRING_PROPERTY_KEYRING_KEY sets its keyring_key property.

Protect keyring secrets

Anyone who can read both the encrypted keyring file and its encryption password can recover the stored tokens. Restrict access to the keyring path, inject the password through a secret manager, and do not store either value in an image or source control.

CLI scripting

The CLI provides a powerful interface for interacting with your packages and repositories in Cloudsmith. However, some operations require additional scripting to achieve the required result. Please see the examples below:

Copying/moving multiple packages

The CLI supports moving one package at a time. However, it is easy to script a solution for moving multiple packages.

The following command will list all the packages returned by YOUR-QUERY. Extract the relevant metadata and run the copy command for each.

cloudsmith ls pkg YOUR-ACCOUNT/YOUR-REPO -q 'YOUR-QUERY' -F json \
  | jq '.data[] | .namespace + "/" + .repository + "/" + .slug' -r \
  | xargs -Ipackage cloudsmith copy package YOUR-DEST-REPO

Error message

The destination is not qualified by a namespace (YOUR-ACCOUNT). This is because you can only copy/move packages from repositories within the same namespace.

Note

📘 You can remove the query (YOUR-QUERY) to target all packages. The only downside to this approach is that it might require multiple invocations if you have more packages than the page size limit.

It's possible to navigate pages using -p and increase the page size limit to 500 using -l 500

Example

The following moves all Maven packages named cloudsmith-api with version 0.21.* from lskillen/test2 to lskillen/test3 (Permissions permitting obviously).

cloudsmith ls pkg lskillen/test2 -q 'format:maven AND name:cloudsmith-api AND version:^0.21' -F json 
  | jq '.data[] | .namespace + "/" + .repository + "/" + .slug' -r 
  | xargs -Ipackage cloudsmith copy package test3

Waiting for a package to complete synchronizing

The wait_for_package_sync function below will wait for a package matching the provided query to either complete syncing or fail.

For example wait_for_package_sync "name:^foo$ AND version:0.0.1" would wait for a package named foo with version 0.0.1 to either successfully complete synchronization, fail or time out after 180 seconds.

The full list of available search parameters can be found in our documentation on searching and filtering.

get_package_identifier() {
    local query=${1:-""}
    cloudsmith list packages --output-format json --query "$query" "$ORG/$REPOSITORY" 2> /dev/null | jq '.data[0].slug' | sed -e 's/^"//' -e 's/"$//'
}

get_package_status() {
    local identifier=${1:-""}
    cloudsmith status "$ORG/$REPOSITORY/$identifier" 2> /dev/null
}

wait_for_package_sync() {
    local query=${1:-""}
    local total_time_limit=${2:-180}
    local identifier=""
    local package_status=""
    local total_time=0
    local identifier=""
    local package_sync_complete=1
    local package_sync_failed=0
    local sleep_time=10

    while [[ $total_time -lt $total_time_limit ]]; do
        if [[ -z "$identifier" ]] || [[ "$identifier" == "null" ]]; then
            identifier=$(get_package_identifier "$query")
            if [[ -z "$identifier" ]] || [[ "$identifier" == "null" ]]; then
              echo "Waiting for package .. (query: $query)" > /dev/stderr
              total_time=$((total_time+$sleep_time))
              sleep $sleep_time
              continue
            fi
        fi

        package_status=$(get_package_status "$identifier")

        echo "$package_status" | grep --quiet 'Completed'
        package_sync_complete=$?

        echo "$package_status" | grep --quiet 'Failed'
        package_sync_failed=$?

        if [[ $package_sync_complete -eq 0 ]] || [[ $package_sync_failed -eq 0 ]]; then
            break
        fi

        echo "Waiting for package status ... (identifier: $identifier)" > /dev/stderr
        total_time=$((total_time+$sleep_time))
        sleep $sleep_time
    done

    if [[ $total_time -gt $total_time_limit ]]; then
        echo "Timed out after waiting $total_time seconds for package to sync" > /dev/stderr
        exit 1
    fi

    if [[ $package_sync_complete -ne 0 ]]; then
      echo "Package failed to sync after $total_time seconds" > /dev/stderr
      exit 1
    fi

    echo "Package synced successfully after $total_time seconds" > /dev/stderr
}

Automatically discover credentials

Automatically discover OIDC credentials

To enable automatic discovery of OpenID Connect (OIDC) credentials, set the CLOUDSMITH_WORKSPACE and CLOUDSMITH_SERVICE_SLUG environment variables. The CLI then discovers the CI provider's OIDC token and exchanges it on its first authenticated command:

export CLOUDSMITH_WORKSPACE=your-workspace
export CLOUDSMITH_SERVICE_SLUG=your-service-account
cloudsmith whoami

cloudsmith whoami exits with code 0 when authenticated and 1 when anonymous, so you can use it to verify authentication in scripts.

Important

Automatic discovery is skipped unless both CLOUDSMITH_WORKSPACE and CLOUDSMITH_SERVICE_SLUG are configured.

The CLI can automatically detect OIDC credentials for the following CI/CD platforms:

Note

Generic automatic discovery is supported for custom CI/CD systems. For example, Jenkins with the credentials binding plugin.

The CLI evaluates each detector in a fixed order (circleci, azure_devops, github, bitbucket, gitlab, aws, generic) and uses the first that matches.

To override the default evaluation order, you can disable a detector or customize the evaluation order.

Disable a detector

To disable a detector:

• By using an environment variable:

  Set the CLOUDSMITH_OIDC_<DETECTOR>_DISABLED environment variable to true. For example, to skip the AWS detector: CLOUDSMITH_OIDC_AWS_DISABLED=true.

• By using config.ini:

  Under [default] or a [profile:<name>] section, add the detector ID to oidc_disabled_detectors. For example, to disable the AWS detector: oidc_disabled_detectors = aws

  To disable multiple detectors, provide a comma-separated list of the detectors you want to disable. For example, to disable the AWS and GitLab CI detectors: oidc_disabled_detectors = aws, gitlab.

Customize the detector evaluation order

You can customize the detector evaluation order by providing a comma-separated list of detector IDs to the CLOUDSMITH_OIDC_DETECTOR_ORDER environment variable, the --oidc-detector-order CLI option, or oidc_detector_order in config.ini.

IDs that aren't listed are skipped, and unrecognized IDs are ignored with a warning.

For example, to evaluate only the AWS and generic detectors, evaluating the generic detector first:

• By using the --oidc-detector-order CLI option:

  --oidc-detector-order=generic,aws

• By using an environment variable:

  Set CLOUDSMITH_OIDC_DETECTOR_ORDER=generic,aws.

• By using config.ini:

  Under [default] or a profile section, add oidc_detector_order=generic,aws.

AWS

For AWS environments (ECS, EKS, EC2), install the aws extra to enable automatic credential discovery when using the pip-installed package:

python3 -m pip install --upgrade 'cloudsmith-cli[aws]'

This installs boto3[crt] for AWS credential chain support, STS token generation, and AWS SSO compatibility. The standalone binaries already bundle boto3[crt], so they do not require this extra.

Bitbucket Pipelines

To enable automatic discovery, set oidc: true on the pipeline step. 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>):

Example:

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

For more information about using OIDC credentials with Bitbucket Pipelines, see the Bitbucket Integrate Pipelines with resource servers using OIDC documentation.

CircleCI

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 that CircleCI mints, which is your CircleCI organization UUID. For more information about OIDC authentication with CircleCI, see Integrating with CircleCI.

Azure DevOps

The CLI fetches an OIDC token from the SYSTEM_OIDCREQUESTURI endpoint by using the pipeline's SYSTEM_ACCESSTOKEN. Make sure SYSTEM_ACCESSTOKEN is mapped into the step's environment.

The Cloudsmith OIDC provider must expect the api://AzureADTokenExchange audience that Azure DevOps mints (any requested audience is ignored). For more information, see the Cloudsmith Azure DevOps integration guide.

GitHub Actions

The CLI fetches an OIDC token from the Actions runtime when the workflow requests id-token: write permission. See Setup GitHub Actions to authenticate to Cloudsmith using OIDC.

GitLab CI

Configure an id_tokens entry in your .gitlab-ci.yml with an aud of https://api.cloudsmith.io/openid/<your-workspace> and expose it as CLOUDSMITH_OIDC_TOKEN:

job:
  id_tokens:
    CLOUDSMITH_OIDC_TOKEN:
      aud: https://api.cloudsmith.io/openid/<your-workspace>
  script:
    - cloudsmith push ...

The Cloudsmith CLI will pick it up automatically.

For more information about using GitLab CI/CD with Cloudsmith, see the Cloudsmith GitLab CI/CD integration guide.

Generic

Generic automatic discovery is supported as a fallback for environments without a dedicated detector (for example, Jenkins with the credentials binding plugin, or any custom CI/CD system). This detector runs last by default, so a dedicated environment is always preferred when present.

Set the CLOUDSMITH_OIDC_TOKEN environment variable to an OIDC JSON Web Token (JWT) and the CLI will exchange it for a Cloudsmith access token.

For more information about using OIDC with Jenkins, see Setup Jenkins to Authenticate to Cloudsmith using OIDC.

Resolve a credential for external tools

Use cloudsmith credential-helper generic to supply existing CLI credentials to a tool that can run an external command and parse JSON:

cloudsmith credential-helper generic

The command takes no host argument because the destination host does not change which credential the CLI resolves.

The command uses the full CLI credential chain: an API key supplied directly or loaded from credentials.ini, an SSO token from the configured keyring, then OIDC automatic discovery. On success, it writes only a versioned JSON document to standard output:

{
  "version": 1,
  "username": "token",
  "password": "<token>"
}

The username value is always the literal package-client username token; it is not a Cloudsmith user or service account name. The password value contains the resolved Cloudsmith token.

Validate the version and extract the token with jq:

CLOUDSMITH_TOKEN="$(
  cloudsmith credential-helper generic |
    jq -er 'select(.version == 1 and .username == "token") | .password'
)"

Protect command output

The JSON document contains a live credential. Do not print it to logs or store it in an unprotected file. Mask the extracted value when a CI platform supports log masking.

If no credential can be resolved, the command exits non-zero, writes an error to standard error, and writes nothing to standard output. It never emits a partial credential document.

Automatically discover Docker credentials

v1.19.0 introduced a Docker credential helper which lets Docker discover credentials from the CLI automatically, including for custom registry domains.

Install the Docker credential helper

To install the Docker credential helper, run:

cloudsmith credential-helper install docker

This installs a docker-credential-cloudsmith binary and registers it in ~/.docker/config.json (default path) for Cloudsmith registry domains. By default, custom domains are discovered automatically via the Cloudsmith API and cached.

Useful options:

Note

For more information about the options available for the installation command, run cloudsmith credential-helper install docker --help.

Important

If you're using custom domains, set CLOUDSMITH_WORKSPACE to your workspace slug.

After installing the helper, docker push and docker pull commands against Cloudsmith registries authenticate with the existing CLI credentials.

The helper implements Docker's credential helper protocol.

Uninstall the Docker credential helper

To uninstall the Docker credential helper, run:

cloudsmith credential-helper uninstall docker

Troubleshooting

If using a proxy with self-signed / internal TLS Certificates, you may need to point to your custom certs with:

export REQUESTS_CA_BUNDLE=/path/to/converted/certificate.pem

Updated 1 hour ago