Documentation
Open Cloudsmith

NuGet Feed

Cloudsmith provides public & private feeds for NuGet

NuGet is an open-source package manager designed for the Microsoft development technologies.

The NuGet repository support at Cloudsmith is compatible with Chocolatey, so if you're looking to manage packages on Windows, that's our recommended approach.

For more information on NuGet, please see:

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/rsa-key pre-configured).

In the following examples:

IdentifierDescription
OWNERYour Cloudsmith account name or organization name (namespace)
REPOSITORYYour Cloudsmith Repository name (also called "slug")
TOKENYour Cloudsmith Entitlement Token (see Entitlements for more details)
USERNAMEYour Cloudsmith username
PASSWORDYour Cloudsmith password
API-KEYYour Cloudsmith API Key
PACKAGE_NAMEThe name of your package
PACKAGE_VERSIONThe version number of your package

Upload a Package

Before you can upload, you need to create your NuGet package using the NuGet CLI or the .NET Core CLI:

Note

This assumes that you've created a compatible project.csproj file for your project.

text
nuget pack
text
dotnet pack

This generates a nupkg (.nupkg) file like your-package-1.2.3.nupkg that you can upload.

Upload via native NuGet Tooling

The endpoint for the native NuGet API is:

https://nuget.cloudsmith.io/OWNER/REPOSITORY/

You can upload your package using the NuGet CLI or the .NET Core CLI.

NuGet CLI
You can publish a nupkg file that you've generated from your project, using nuget.
As a shortcut, you can set up the source (upstream) ahead of time, using nuget source:

shell
nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Then you can publish your package using:

shell
nuget push PACKAGE_NAME-PACKAGE_VERSION.nupkg -Source example-repo -ApiKey API-KEY

.NET Core CLI
You can publish a nupkg file that you've generated from your project, using dotnet:

shell
dotnet nuget push PACKAGE_NAME-VERSION.nupkg -k API-KEY -s https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Upload via the Cloudsmith CLI

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

The command to upload a NuGet package via the Cloudsmith CLI is:

shell
cloudsmith push nuget OWNER/REPOSITORY PACKAGE_NAME-PACKAGE_VERSION.nupkg

Example:

shell
cloudsmith push nuget your-account/your-repo your-package-1.0.0.nupkg

Upload via Cloudsmith web app

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

Example Project

For examples of what your project should look like for packaging and publishing/uploading, please have a look at our examples repository (on GitHub). We'll supplement these with more detailed guidance later, but otherwise just ask, we're here to help!

Download / Install a Package

Setup

To consume packages in NuGet from a Cloudsmith NuGet Feed , you'll need to configure it as a source:

Public Repositories

NuGet CLI

shell
nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

.NET Core CLI
When specifying the source in commands via -s, use the following URL:

https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Paket CLI
You can add the source to your paket.dependencies file:

source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

If you don't want to check your username into source control, you can use environment variables instead

VS Package Manager (PM)
When specifying the source in commands via -Source, use the following URL:

https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Private Repositories

Private Repositories

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use.

Warning

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code, or expose them in any logs.

NuGet CLI

shell
nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json -Username token -Password TOKEN -StorePasswordInClearText
shell
nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json -Username USERNAME -Password PASSWORD -StorePasswordInClearText
shell
nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json -Username USERNAME -Password API-KEY -StorePasswordInClearText
shell
nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json -Username token -Password TOKEN -StorePasswordInClearText

.NET Core CLI
When specifying the source in commands via -s, use the following URL:

shell
https://token:TOKEN@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json
shell
https://USERNAME:PASSWORD@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json
shell
https://USERNAME:API-KEY@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json
shell
https://token:TOKEN@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Paket CLI
You can add the source to your paket.dependencies file:

shell
source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json username: "token" password: "TOKEN" authtype: "basic"
shell
source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json username: "USERNAME" password: "PASSWORD" authtype: "basic"
shell
source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json username: "USERNAME" password: "API-KEY" authtype: "basic"
shell
source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json username: "token" password: "TOKEN" authtype: "basic"

If you don't want to check your username into source control, you can use environment variables instead.

VS Package Manager (PM)
When specifying the source in commands via -Source, use the following URL:

shell
https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json
shell
https://USERNAME:PASSWORD@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json
shell
https://USERNAME:API-KEY@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json
shell
https://token:TOKEN@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Install a Package

To install the latest version of a package you would use:

NuGet CLI

shell
nuget install PACKAGE_NAME -Source example-repo -DependencyVersion Highest

.NET Core CLI

dotnet add package PACKAGE_NAME -s https://nuget.cloudsmith.io/OWNER/REPOSITOY/v3/index.json

Paket CLI

paket add nuget PACKAGE_NAME

VS Package Manager (PM)

Install-Package PACKAGE_NAME -Source example-repo

Current Limitations

The Cloudsmith NuGet feed implementation has the following limitations:

  • The maximum size per-package file is limited to 200MiB (~210 megabytes), but only when utilising the native nuget-cli for publishing. If uploading using the cloudsmith-cli, then the absolute maximum size per-package file limit will be the standard 5GiB.

Security Scanning

Supported
Please see our Security Scanning documentation for further information.

Upstream Proxying / Caching

Configurable Proxying Caching
You can configure upstream NuGet feeds that you wish to use for packages that are not available in your Cloudsmith repository. In addition, you can also choose to cache any requested packages for future use.

Please see our Upstream Proxying documentation for further instructions.

Troubleshooting

Q. I'm unable to authenticate using HTTP Basic Authentication with a password or with an entitlement token. I'm using dotnet core SDK 2.2

This is the error:

text
Unable to get repository signature information for source
https://nuget.cloudsmith.io/YOUR-ACCOUNT/YOUR-REPO/v3-index/repository-signatures/X.X.X/index.json
error : Response status code does not indicate success: 401 (Unauthorized)

It looks like this (not being able to use username/password directly on a source) might be an accepted bug in dotnet 2.2, possibly fixed later, as referenced in the following GitHub issues:

SOLUTION
Add the source using nuget sources as follows first::

nuget sources add -Name NAME -source https://nuget.cloudsmith.io/YOUR-ACCOUNT/YOUR-REPO/v3/index.json -Username YOUR-USERNAME -Password YOUR-API-KEY-OR-PASSWORD -StorePasswordInClearText

Then do dotnet restore like:

dotnet restore -s https://nuget.cloudsmith.io/YOUR-ACCOUNT/YOUR-REPO/v3/index.json --configfile ~/config/NuGet/NuGet.Config

If you want to use an Entitlement Token instead of a username and password/API-Key, use "token" for the username and an Entitlement Token as the password.

Still Need Help?

Contact us here. We're always happy to help!