Supported Formats

Generic Repository

Cloudsmith provides public & private repositories for Generic files.

Cloudsmith supports Generic files, a flexible format for managing any file or binary that relies on specific file paths rather than semantic versioning.

HTML-based upstreams

Generic upstreams support simple HTML-based sources alongside dedicated source types (Node.js, HashiCorp, Fluent Bit, GitHub Releases). HTML-based upstreams must consist of simple, unstyled HTML pages with no JavaScript, where each page contains only links to package files or subdirectories. Examples include Apache releases and Gradle distributions.

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy and paste snippets (with your namespace/repo pre-configured).

In the following examples:

Substitute placeholder values

Where you see uppercase values such as OWNER, REPOSITORY, TOKEN, API-KEY, or UPSTREAM_PREFIX, substitute these with your own Cloudsmith namespace, repository, token, API key, and upstream prefix as appropriate.

Why Generic Format?

Use Generic when your artifacts are identified by file path rather than by name and version — installers, scripts, build outputs, binaries, and other files that don't fit a native package format. The filepath you upload to becomes the package's permanent identifier and its download URL, so internal URLs mirror their upstream sources exactly. Generic also supports proxying and caching from simple HTML-based upstreams and a few dedicated source types (Node.js, HashiCorp, Fluent Bit, GitHub Releases).

Generic vs Raw Format

The Generic format is optimized for path-based file distribution and upstream proxying. It relies strictly on the filepath as the unique identifier and does not support:

• Package naming (separate from filepath)
• Package versioning (semantic versions)
• End User License Agreements (EULA)

If you need package naming, semantic versioning, or EULA support, use the Raw format instead. The Raw format provides traditional package management features including distinct package names, version tracking, and license acceptance workflows.

File-Based Storage

Generic packages are treated as files and binaries. Unlike native package formats (Python, npm, Maven), Generic packages do not have metadata, version information, or vulnerability scanning capabilities. They are stored and served as-is without package-specific processing.

Upload a File

Upload via the Cloudsmith CLI

For full details of how to install and set up the Cloudsmith CLI, see Command Line Interface

The command to upload via the Cloudsmith CLI is:

cloudsmith push generic OWNER/REPOSITORY ~/downloads/file.tar.gz --filepath path/to/file.tar.gz

Example:

cloudsmith push generic OWNER/REPOSITORY ~/downloads/file.tar.gz --filepath distributions/latest/file.tar.gz

Filepath parameter

The --filepath parameter is required and specifies where the file will be stored in the repository. This path becomes the unique identifier for the package and determines its download URL. If omitted, the upload will fail.

Optional upload fields

The cloudsmith push generic command also accepts these optional fields:

Example:

cloudsmith push generic OWNER/REPOSITORY ~/downloads/file.tar.gz \
  --filepath distributions/latest/file.tar.gz \
  --version 1.2.3 \
  --tags stable,linux \
  --republish

Upload via Cloudsmith web app

Please see upload a package for details of how to upload via the Cloudsmith web app.

Download a Package

Download via Cloudsmith web app

Public Repositories

When logged into Cloudsmith via a Web Browser, use the Download button located on the package details page to download a generic package.

Private Repositories

To download from a private repository via the Cloudsmith web app, use the Use Package button to download a generic package using the default Entitlement Token for the repository. Use the dropdown arrow within the pop-up window to select a different authentication method.

Download via Command Line

To download a Generic package, request it via a URL whose path matches the filepath used when uploading, or the upstream prefix followed by the filepath for upstream-backed files. The recommended endpoint is generic.cloudsmith.io/OWNER/REPOSITORY/<path>. It serves files uploaded to your repository, files already cached from a configured upstream, and triggers an upstream fetch when a file is not yet cached.

Public Repositories

Example curl commands to download a generic package from a public repository.

For files uploaded directly to your repository, the path matches the --filepath used at upload:

curl -sLf -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/path/to/file.tar.gz"

For files served through a configured upstream, the path is prefixed with the upstream prefix:

curl -sLf -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

Private Repositories

Private Repositories

Private repositories require authentication. The methods below cover programmatic access; for browser access to the HTML index, use HTTP Basic Authentication when prompted—enter token as the username and your entitlement token or API key as the password.

HTTP Basic Authentication (generic.cloudsmith.io):

Use an entitlement token with HTTP Basic Auth to download files:

curl -sLf -u "token:TOKEN" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

Alternatively, embed HTTP Basic Auth credentials in the URL as user information:

curl -sLf -O "https://token:TOKEN@generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

API Key Authentication (generic.cloudsmith.io):

Use an API Key with the X-Api-Key header to download files. The X-Api-Key header only accepts API keys; an Entitlement Token cannot be sent in this header. Both credential types are accepted via HTTP Basic Auth (-u token:CREDENTIAL).

curl -sLf -H "X-Api-Key: API-KEY" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

Alternatively, send the API key via HTTP Basic Auth (username token, password is the API key):

curl -sLf -u "token:API-KEY" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/UPSTREAM_PREFIX/path/to/file.tar.gz"

Authentication when using the Download domain (dl.cloudsmith.io):

The dl.cloudsmith.io domain most commonly uses path-based authentication with entitlement tokens embedded in the URL path. There are some exceptions:

HTTP Basic Auth with credentials in the userinfo portion of the URL (e.g., token:TOKEN@dl.cloudsmith.io) is only supported for the /basic/... download route on this domain and is not supported for the default /TOKEN/... path-based URLs.

This domain exposes two distinct routes for Generic packages, with different behavior:

• generic/download/<path> serves files that are already cached in your Cloudsmith repository (uploaded, or fetched and stored from an upstream on a previous request). It does not trigger an upstream fetch.
• generic/upstream/download/<UPSTREAM_PREFIX>/<path> triggers a proxy fetch from the configured upstream. When the upstream is configured as Cache and Proxy, the fetched file is also stored in your Cloudsmith repository.

Cached-only route returns 404 instead of fetching

A request to generic/download/... on dl.cloudsmith.io returns 404 if the file is not already cached in your Cloudsmith repository. To trigger a fetch from a configured upstream, request the same file via generic/upstream/download/<UPSTREAM_PREFIX>/..., or use generic.cloudsmith.io, which resolves cached files and on-demand upstream fetches under a single URL.

Caching after an upstream fetch is asynchronous: when an upstream is in Cache and Proxy mode, a successful fetch via generic/upstream/download/... is recorded and the file is copied into your repository in the background. Until that background work completes, the same file requested via generic/download/... may still return 404. There is no fixed delay; for time-sensitive workflows, use generic/upstream/download/... (or generic.cloudsmith.io) so the response does not depend on cache state.

Cached files (already in your repository):

curl -sLf -O "https://token:TOKEN@dl.cloudsmith.io/basic/OWNER/REPOSITORY/generic/download/UPSTREAM_PREFIX/path/to/file.tar.gz"

curl -sLf -O "https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/generic/download/UPSTREAM_PREFIX/path/to/file.tar.gz"

Upstream fetch (proxy, and store when the upstream is Cache and Proxy):

curl -sLf -O "https://token:TOKEN@dl.cloudsmith.io/basic/OWNER/REPOSITORY/generic/upstream/download/UPSTREAM_PREFIX/path/to/file.tar.gz"

curl -sLf -O "https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/generic/upstream/download/UPSTREAM_PREFIX/path/to/file.tar.gz"

Embedded-token URLs do not auto-fall back to the upstream route

The two dl.cloudsmith.io routes shown above (generic/download/... and generic/upstream/download/...) are not interchangeable, and the embedded-token URL pattern (/{TOKEN}/...) has no built-in fallback when a file is not yet cached. Workflows that rely on embedded-token URLs to consume upstream-backed files therefore need one of two strategies:

• Use two URLs in sequence. Send the first request to generic/upstream/download/<UPSTREAM_PREFIX>/... to trigger the upstream fetch (and to store the file when the upstream is configured as Cache and Proxy). Once the file is cached, subsequent requests can use the shorter generic/download/<UPSTREAM_PREFIX>/... URL.
• Pre-check before each request. Query the repository ahead of time to determine whether the file is already cached, and pick generic/download/... or generic/upstream/download/... accordingly.

If you would prefer a single URL that resolves both cases transparently, use generic.cloudsmith.io instead — it serves cached files and triggers on-demand upstream fetches under one path.

API Key Authentication (dl.cloudsmith.io):

The /basic/... route also accepts API keys, sent via either HTTP Basic Auth (-u token:API-KEY) or the X-Api-Key header. API keys are not accepted on the default /{TOKEN}/... path-based URLs.

curl -sLf -u "token:API-KEY" -O "https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/generic/upstream/download/UPSTREAM_PREFIX/path/to/file.tar.gz"

curl -sLf -H "X-Api-Key: API-KEY" -O "https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/generic/upstream/download/UPSTREAM_PREFIX/path/to/file.tar.gz"

Supported Authentication by Domain:

A URL follows the structure: scheme://userinfo@host/path

• Userinfo (token:TOKEN@): Credentials placed before the host.
• Path (/TOKEN/...): Token embedded after the domain in the URL path. This only works on dl.cloudsmith.io.

Basic Auth credentials can be sent either via the standard Authorization: Basic … header (which curl -u sets automatically) or embedded in the URL as userinfo (token:TOKEN@…). Both transports are equivalent.

Basic Auth on dl.cloudsmith.io is only valid for URLs that begin with /basic/. Sending Basic Auth credentials (header or userinfo) alongside a /{TOKEN}/... URL on this domain is not supported.

When to use the download domain

Reach for dl.cloudsmith.io when path-based token URLs fit your tooling better than userinfo credentials — for example, when your HTTP client can't pass credentials in the userinfo portion of a URL, when your client doesn't follow redirects (generic.cloudsmith.io redirects to a signed dl.cloudsmith.io URL on every download), or when you want to share or embed a direct download URL without additional authentication configuration. Using dl.cloudsmith.io also keeps Generic consistent with the other Cloudsmith package formats.

Download via the HTML Index

Cloudsmith supports serving Apache-style HTML formatted indexes of generic package files in the repository.

Disabled by Default

HTML index generation is disabled by default. Enable it in Repository Settings under the Generic section.

When the HTML index is disabled (by default), the repository serves only direct file downloads. Requests for a specific file work normally: cached files are served from the repository, and uncached files trigger an upstream fetch when a matching upstream prefix is configured.

A directory request is a URL ending in / or pointing at a folder rather than a file (for example, …/dist/latest/ instead of …/dist/latest/file.tar.gz). When the HTML index is disabled, directory requests return 404. When enabled, directory requests return an HTML view of the available files and subdirectories.

When enabled, the HTML index is available at: https://generic.cloudsmith.io/OWNER/REPOSITORY/

Public Repositories

Browse the HTML index to view and download packages directly in your browser.

Private Repositories

When accessing the HTML index in a browser for private repositories, you will be prompted for authentication. Enter token as the username and your entitlement token or API key as the password to view the index.

After entering valid credentials, you should then be able to view the HTML index.

Upstream Proxying / Caching

The Generic format supports upstream proxying and caching for simple HTML-based sources and a few dedicated source types. When a file is requested, Cloudsmith checks for a copy already cached in your repository. If no copy is cached, Cloudsmith fetches the file from the upstream and serves it. When the upstream is configured as Cache and Proxy, the fetched file is also stored in your repository.

Supported Upstream Sources

The following upstream sources are supported:

• Gradle - Gradle distributions
• Node.js - Node.js distributions
• HashiCorp - HashiCorp releases
• Fluent Bit - Fluent Bit distributions
• GitHub - GitHub Releases
• HTML-based sources - Simple, unstyled HTML pages with no JavaScript, where each page contains only links to files or subdirectories (for example, Apache releases)

Enterprise Repository Support

Enterprise repository managers like Artifactory and Sonatype Nexus require additional configuration and are not supported by default. Contact support to discuss setup for these upstream sources.

Configure an Upstream

To configure an upstream for your Generic repository, browse to your repository overview page and click the Upstreams tab. Then, click + Add Upstream Proxy and choose the Generic format upstream.

In the upstream creation menu, define a name for your upstream and enter the upstream URL. You must specify an Upstream Prefix to prevent file collisions when using multiple upstreams. The prefix becomes part of the file's permanent path in the repository, ensuring files from different upstreams never collide, even with identical filenames.

Cloudsmith automatically detects the upstream type for well-known hosts (for example, nodejs.org, releases.hashicorp.com, api.github.com) and indexes them correctly. URLs that don't match a known host are treated as Generic HTML upstreams; this works for simple static HTML index sites but not for repository managers like Artifactory or Sonatype Nexus, which require Cloudsmith support to enable.

Upstream Prefix format

The upstream prefix must contain only alphanumeric characters, dashes (-), underscores (_), and dots (.). It cannot start or end with a dot, contain .., or exceed 64 characters. Each prefix must be unique within the repository.

Please see our Upstream Proxying documentation for further instructions on configuring upstreams.

Examples

The path you request from Cloudsmith is always UPSTREAM_PREFIX/<file path on upstream>. The "file path on upstream" is the portion of the upstream URL that comes after the configured upstream URL's base path. The highlighted example below covers GitHub Releases; the reference table after it summarizes the rules for each supported source.

Worked example: GitHub Releases

Upstream configuration:

• Upstream URL: https://api.github.com/repos/cloudsmith-io/cloudsmith-cli/releases
• Upstream Prefix: github_releases

Accepted upstream URL formats

Both the GitHub web URL (https://github.com/cloudsmith-io/cloudsmith-cli) and the API URL (https://api.github.com/repos/cloudsmith-io/cloudsmith-cli/releases) are accepted. Cloudsmith normalizes either format automatically.

GitHub upstreams require authentication

When configuring a GitHub Releases upstream, you must supply a GitHub personal access token via the upstream's authentication settings. Unauthenticated GitHub API requests are limited to 60 requests per hour and will fail to index releases. Authenticated requests get 5,000 requests per hour.

How paths are resolved:

GitHub release assets are indexed as {tag_name}/{asset_name} via the GitHub API. To download the asset cloudsmith.pyz (the {asset_name}) from release v1.16.0 (the {tag_name}):

GitHub's 'download/' segment is not part of the file path

GitHub browser download URLs include a download/ segment for routing purposes, for example: https://github.com/allure-framework/allure2/releases/download/2.31.0/allure-2.31.0.tgz

This download/ is not a directory. Cloudsmith uses the GitHub API to enumerate release assets directly and indexes each file as {tag_name}/{asset_name}. The correct Cloudsmith path for this file is 2.31.0/allure-2.31.0.tgz, not download/2.31.0/allure-2.31.0.tgz.

Download commands:

Public repository:

curl -sLf -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/github_releases/v1.16.0/cloudsmith.pyz"

Private repository - entitlement token:

curl -sLf -u "token:TOKEN" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/github_releases/v1.16.0/cloudsmith.pyz"

Private repository - API key:

curl -sLf -H "X-Api-Key: API-KEY" -O "https://generic.cloudsmith.io/OWNER/REPOSITORY/github_releases/v1.16.0/cloudsmith.pyz"

Path mapping by source type

The table below shows how the file path on the upstream maps to the Cloudsmith URL for each supported source. In every case the request path is the upstream prefix followed by the file path on the upstream.

The upstream prefix is what guarantees files from different upstreams never collide, even if they share identical paths.

Upstream Priority

Each Generic upstream is isolated by its unique prefix, so upstream priority has no effect — every upstream is treated as priority 1, and changing the priority setting does not impact package blending.

Local packages (directly uploaded to the repository) always take precedence over upstream packages. When viewing the HTML index, cached packages display with a different icon than packages that will be proxied on demand.

Key Signing Support

Generic files are stored and served as-is without package signing. If you need GPG-signed packages for files you upload directly, use the Raw format; note that Raw does not support upstream proxying, so it is not a substitute for Generic when proxying or caching files from upstream sources.

Troubleshooting

Please see the Troubleshooting page for further help and information.

Updated 1 minute ago