Install the standalone Cloudsmith CLI, add it to PATH, and configure authentication for the rest of a CircleCI job. The orb does not require Python, pip, or jq on the executor image.

Quick start · Configuration · Migration guide · Contributing

OIDC is the recommended option for CI/CD because it uses short-lived credentials instead of a stored API key. Configure a Cloudsmith service account and an OIDC provider by following the Cloudsmith OIDC documentation before using this example.

version: 2.1

orbs:
  cloudsmith: cloudsmith/cloudsmith@3.0.0

workflows:
  verify:
    jobs:
      - verify:
          context: my-context

jobs:
  verify:
    executor: cloudsmith/default
    steps:
      - cloudsmith/install-cli
      - cloudsmith/configure-oidc:
          organization: YOUR-NAMESPACE
          service-account: YOUR-SERVICE-ACCOUNT
      - run: cloudsmith whoami

Provide the API key through the CLOUDSMITH_API_KEY environment variable, typically from a CircleCI context. For automated pipelines, use a Cloudsmith service account rather than a personal API key.

version: 2.1

orbs:
  cloudsmith: cloudsmith/cloudsmith@3.0.0

workflows:
  verify:
    jobs:
      - verify:
          context: my-context

jobs:
  verify:
    executor: cloudsmith/default
    steps:
      - cloudsmith/ensure-api-key
      - cloudsmith/install-cli
      - run: cloudsmith whoami

Personal API keys are available from Cloudsmith API settings.

Choose one of the following authentication methods:

With OIDC, configure-oidc exports the service account context needed by the CLI. The Cloudsmith access token is requested only when the CLI first needs to authenticate and is not exposed by the orb.

flowchart LR
    A[configure-oidc command] -->|Exports OIDC settings| B[Cloudsmith CLI command]
    B -->|Requests identity token| C[CircleCI OIDC]
    C -->|Exchanges identity| D[Cloudsmith]

Set verify-auth: true on configure-oidc to run cloudsmith whoami during setup and fail early if authentication is not configured correctly.

Installs the standalone Cloudsmith CLI on a Linux or macOS executor and adds its binary directory to PATH for later steps through $BASH_ENV.

When supplied, these values are written to ~/.cloudsmith/config.ini.

Configures the CLI for CircleCI-native OIDC. The job must use at least one context so CircleCI issues an OIDC token.

Run install-cli before using verify-auth.

Validates that CLOUDSMITH_API_KEY is present and fails the job immediately when it is missing.

The default executor uses the cimg/base convenience image with the current tag. You can also use the orb commands with another Linux or macOS executor that provides bash and either curl or wget.

The orb persists configuration for later steps through CircleCI’s $BASH_ENV file. Only bash steps source $BASH_ENV, and CircleCI selects the default step shell when the container starts — on minimal images where bash is installed during the job (for example alpine), give any step that runs the CLI an explicit shell: /bin/bash.

The following workflow installs the CLI with OIDC authentication and publishes a raw package:

version: 2.1

orbs:
  cloudsmith: cloudsmith/cloudsmith@3.0.0

workflows:
  publish:
    jobs:
      - publish:
          context: my-context

jobs:
  publish:
    executor: cloudsmith/default
    steps:
      - checkout
      - cloudsmith/install-cli
      - cloudsmith/configure-oidc:
          organization: YOUR-NAMESPACE
          service-account: YOUR-SERVICE-ACCOUNT
      - run:
          name: Publish package
          command: cloudsmith push raw YOUR-NAMESPACE/YOUR-REPOSITORY dist/app.tar.gz

See Supported Formats for the upload command and options for each package format.

Version 3 installs the standalone CLI instead of the Python package and uses CLI-native OIDC authentication.

The orb source is stored as individual YAML and shell files under src/. The CircleCI CLI packs these files into orb.yml for validation and publishing.

circleci orb pack src/ > orb.yml
circleci orb validate orb.yml
shellcheck src/scripts/*.sh

For help, open a GitHub issue or contact Cloudsmith Support.