tools.json for discovering nuget.exe versions

Today, there are a few ways to get the latest version of nuget.exe on your machine in a scriptable fashion. For example, you can download and extract the NuGet.CommandLine package from nuget.org. This has some complexity since it either requires that you already have nuget.exe (for nuget.exe install) or you have to unzip the .nupkg using a basic unzip tool and find the binary inside.

If you already have nuget.exe, you can also use nuget.exe update -self, however this also requires having an existing copy of nuget.exe. This approach also updates you to the latest version. It does not allow the use of a specific version.

The tools.json endpoint is available to both solve the bootstrapping problem and to give control of the version of nuget.exe that you download. This can be used in CI/CD environments or in custom scripts to discover and download any released version of nuget.exe.

The tools.json endpoint can be fetched using an unauthenticated HTTP request (e.g. Invoke-WebRequest in PowerShell or wget). It can be parsed using a JSON deserializer and subsequent nuget.exe download URLs can also be fetched using unauthenticated HTTP requests.

The endpoint can be fetched using the GET method:

GET https://dist.nuget.org/tools.json

The JSON schema for the endpoint is available here:

GET https://dist.nuget.org/tools.schema.json

Response

The response is a JSON document containing all of the available versions of nuget.exe.

The root JSON object has the following property:

Name	Type	Required
nuget.exe	array of objects	yes

Each object in the nuget.exe array has the following properties:

Name	Type	Required	Notes
version	string	yes	A SemVer 2.0.0 string
url	string	yes	An absolute URL for downloading this version of nuget.exe
stage	string	yes	An enum string
uploaded	string	yes	An approximate ISO 8601 timestamp of when the version was made available

The items in the array will be sorted in descending, SemVer 2.0.0 order. This guarantee is meant to reduce the burden of a client that is interested in highest version number. However this does mean that the list is not sorted in chronological order. For example, if a lower major version is serviced at a date later than a higher major version, this serviced version will not appear at the top of the list. If you want the latest version released by timestamp, simply sort the array by the uploaded string. This works because the uploaded timestamp is in the ISO 8601 format which can be sorted chronologically by using a lexicographical sort (i.e. a simple string sort).

The stage property indicates how vetted this version of the tool is.

Stage	Meaning
EarlyAccessPreview	Not yet visible on the download web page and should be validated by partners
Released	Available on the download site but is not yet recommended for wide-spread consumption
ReleasedAndBlessed	Available on the download site and is recommended for consumption

One simple approach for having the latest, recommended version is to take the first version in the list that has the stage value of ReleasedAndBlessed. This works because the versions are sorted in SemVer 2.0.0 order.

The NuGet.CommandLine package on nuget.org is typically only updated with ReleasedAndBlessed versions.

Sample request

GET https://dist.nuget.org/tools.json

Sample response

{
    "nuget.exe": [
        {
            "version": "4.8.0-preview3",
            "url": "https://dist.nuget.org/win-x86-commandline/v4.8.0-preview3/nuget.exe",
            "stage": "EarlyAccessPreview",
            "uploaded": "2018-07-06T23:00:00.0000000Z"
        },
        {
            "version": "4.7.1",
            "url": "https://dist.nuget.org/win-x86-commandline/v4.7.1/nuget.exe",
            "stage": "ReleasedAndBlessed",
            "uploaded": "2018-08-10T23:00:00.0000000Z"
        },
        {
            "version": "4.6.1",
            "url": "https://dist.nuget.org/win-x86-commandline/v4.6.1/nuget.exe",
            "stage": "Released",
            "uploaded": "2018-03-22T23:00:00.0000000Z"
        },
        {
            "version": "3.5.0",
            "url": "https://dist.nuget.org/win-x86-commandline/v3.5.0/nuget.exe",
            "stage": "ReleasedAndBlessed",
            "uploaded": "2016-12-19T15:30:00.0000000-08:00"
        },
        {
            "version": "2.8.6",
            "url": "https://dist.nuget.org/win-x86-commandline/v2.8.6/nuget.exe",
            "stage": "ReleasedAndBlessed",
            "uploaded": "2015-09-01T12:30:00.0000000-07:00"
        }
    ]
}