Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- `--version` (`-Version` in PowerShell) accepts a major version, such as
`1`. The installer then installs the latest release of that major version,
from the `cloudsmith-cli-v<MAJOR>-manifest-<target>` manifest.

## [0.1.2] - 2026-07-30

### Fixed
Expand Down
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,14 @@ where `<file>` is `cli.sh`, `cli.ps1`, or `SHA256SUMS`, then run it with
`--version X.Y.Z` (`-Version X.Y.Z` in PowerShell). Use pinned, verified
downloads in CI.

Download the script and `SHA256SUMS` from the same `<version>` path. The
`latest` path resolves each file separately, so for a short time after a
release the two files can come from different releases.

To stay on one major version, set `--version` to that major version, for
example `--version 1` (`-Version 1` in PowerShell). The installer then
installs the latest 1.x release, and never a 2.x release.

## How installation works

```mermaid
Expand Down Expand Up @@ -111,7 +119,7 @@ Command-line options take precedence over environment variables.

| Shell option | PowerShell parameter | Environment variable | Default |
| --- | --- | --- | --- |
| `--version` | `-Version` | `CLOUDSMITH_CLI_VERSION` | `latest` |
| `--version` | `-Version` | `CLOUDSMITH_CLI_VERSION` | `latest`. Also accepts `X.Y.Z` or a major version such as `1` |
| `--install-root` | `-InstallRoot` | `CLOUDSMITH_CLI_INSTALL_ROOT` | Shell: `$XDG_DATA_HOME/cloudsmith-cli` or `~/.local/share/cloudsmith-cli`<br>PowerShell: `%LOCALAPPDATA%\Cloudsmith\CLI` |
| `--target` | `-Target` | `CLOUDSMITH_CLI_TARGET` | Automatically detected |
| `--output-file` | `-OutputFile` | `CLOUDSMITH_CLI_OUTPUT_FILE` | Standard output |
Expand Down
21 changes: 19 additions & 2 deletions install.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,18 @@ function Invoke-HttpsDownload {
}
}

function Get-DefaultManifestUrl {
param(
[Parameter(Mandatory = $true)][string]$RequestedVersion,
[Parameter(Mandatory = $true)][string]$Target
)

if ($RequestedVersion -match '^[0-9]+\z') {
return "$DownloadBaseUrl/$Repository/raw/names/cloudsmith-cli-v$RequestedVersion-manifest-$Target/versions/latest/manifest.txt"
}
return "$DownloadBaseUrl/$Repository/raw/names/$ManifestNamePrefix-$Target/versions/$RequestedVersion/manifest.txt"
}

function Invoke-Download {
param(
[Parameter(Mandatory = $true)][string]$Uri,
Expand Down Expand Up @@ -389,8 +401,9 @@ try {
[void][System.IO.Directory]::CreateDirectory($script:WorkDir)

$manifestFile = Join-Path $script:WorkDir "manifest.txt"
$isMajorVersion = $Version -match '^[0-9]+\z'
if (-not $ManifestUrl) {
$ManifestUrl = "$DownloadBaseUrl/$Repository/raw/names/$ManifestNamePrefix-$resolvedTarget/versions/$Version/manifest.txt"
$ManifestUrl = Get-DefaultManifestUrl -RequestedVersion $Version -Target $resolvedTarget
}

Write-InstallerLog "fetching release manifest"
Expand All @@ -412,7 +425,11 @@ try {
if ($manifestTarget -ne $resolvedTarget) {
throw "install.ps1: manifest target '$manifestTarget' does not match '$resolvedTarget'"
}
if ($Version -ne 'latest' -and $Version -ne $resolvedVersion) {
if ($isMajorVersion) {
if (-not $resolvedVersion.StartsWith("$Version.")) {
throw "install.ps1: manifest resolved '$resolvedVersion', expected a $Version.x release"
}
} elseif ($Version -ne 'latest' -and $Version -ne $resolvedVersion) {
throw "install.ps1: manifest resolved '$resolvedVersion', expected '$Version'"
}
if (-not $archiveName -or $archiveName -match '[/\\]') {
Expand Down
27 changes: 24 additions & 3 deletions install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ usage() {
cat <<'USAGE'
Usage: install.sh [options]

--version VERSION CLI version, or "latest"
--version VERSION CLI version, major version such as "1", or "latest"
--install-root DIR Versioned installation root
--target TARGET Override target detection
--output-file FILE Write key=value installation results
Expand Down Expand Up @@ -218,10 +218,31 @@ detect_target() {
esac
}

is_major_version() {
case "$1" in ''|*[!0-9]*) return 1 ;; esac
}

check_resolved_version() {
if [ "$REQUESTED_VERSION" = latest ]; then
return 0
fi
if is_major_version "$REQUESTED_VERSION"; then
case "$RESOLVED_VERSION" in
"$REQUESTED_VERSION".*) return 0 ;;
esac
die "manifest resolved '$RESOLVED_VERSION', expected a $REQUESTED_VERSION.x release"
fi
[ "$REQUESTED_VERSION" = "$RESOLVED_VERSION" ] || die "manifest resolved '$RESOLVED_VERSION', expected '$REQUESTED_VERSION'"
}

fetch_manifest() {
MANIFEST_FILE="$WORK_DIR/manifest.txt"
if [ -z "$MANIFEST_URL" ]; then
MANIFEST_URL="$DOWNLOAD_BASE_URL/$REPOSITORY/raw/names/$MANIFEST_NAME_PREFIX-$TARGET/versions/$REQUESTED_VERSION/manifest.txt"
if is_major_version "$REQUESTED_VERSION"; then
MANIFEST_URL="$DOWNLOAD_BASE_URL/$REPOSITORY/raw/names/cloudsmith-cli-v$REQUESTED_VERSION-manifest-$TARGET/versions/latest/manifest.txt"
Comment thread
cloudsmith-iduffy marked this conversation as resolved.
Resolved
else
MANIFEST_URL="$DOWNLOAD_BASE_URL/$REPOSITORY/raw/names/$MANIFEST_NAME_PREFIX-$TARGET/versions/$REQUESTED_VERSION/manifest.txt"
fi
fi
require_https "$MANIFEST_URL" "manifest URL"
log "fetching release manifest"
Expand All @@ -239,7 +260,7 @@ validate_manifest() {
[ "$SCHEMA" = 1 ] || die "unsupported manifest schema: ${SCHEMA:-missing}"
case "$RESOLVED_VERSION" in ''|.|..|*[!A-Za-z0-9._+-]*) die "manifest contains an invalid version" ;; esac
[ "$MANIFEST_TARGET" = "$TARGET" ] || die "manifest target '$MANIFEST_TARGET' does not match '$TARGET'"
[ "$REQUESTED_VERSION" = latest ] || [ "$REQUESTED_VERSION" = "$RESOLVED_VERSION" ] || die "manifest resolved '$RESOLVED_VERSION', expected '$REQUESTED_VERSION'"
check_resolved_version
case "$ARCHIVE_NAME" in ''|*/*|*\\*) die "manifest contains an invalid archive name" ;; esac
[ -n "$ARCHIVE_URL" ] || die "manifest is missing url"
case "$EXPECTED_SHA256" in ''|*[!0-9a-f]*) die "manifest contains an invalid SHA-256" ;; esac
Expand Down
71 changes: 71 additions & 0 deletions tests/Install.Tests.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,47 @@ Describe 'Cloudsmith CLI installer request metadata' {
}
}

Describe 'Cloudsmith CLI installer manifest URL' {

BeforeAll {
$installScriptPath = (Resolve-Path (Join-Path (Join-Path $PSScriptRoot '..') 'install.ps1')).ProviderPath
$tokens = $null
$errors = $null
$ast = [System.Management.Automation.Language.Parser]::ParseFile(
$installScriptPath,
[ref]$tokens,
[ref]$errors
)
if ($errors.Count -gt 0) {
throw 'install.ps1 has parse errors'
}

$urlFunction = $ast.Find({
param($node)
$node -is [System.Management.Automation.Language.FunctionDefinitionAst] -and
$node.Name -eq 'Get-DefaultManifestUrl'
}, $true)
if (-not $urlFunction) {
throw 'unable to find Get-DefaultManifestUrl'
}

$script:DownloadBaseUrl = 'https://dl.cloudsmith.io/public'
$script:ManifestNamePrefix = 'cloudsmith-cli-manifest'
$script:Repository = 'cloudsmith/cli'
. ([scriptblock]::Create($urlFunction.Extent.Text))
}

It 'uses the manifest of the major version channel for a major version' {
Get-DefaultManifestUrl -RequestedVersion '1' -Target 'windows-x86_64' |
Should -Be 'https://dl.cloudsmith.io/public/cloudsmith/cli/raw/names/cloudsmith-cli-v1-manifest-windows-x86_64/versions/latest/manifest.txt'
}

It 'uses the version path of the latest channel for an exact version' {
Get-DefaultManifestUrl -RequestedVersion '1.2.3' -Target 'windows-x86_64' |
Should -Be 'https://dl.cloudsmith.io/public/cloudsmith/cli/raw/names/cloudsmith-cli-manifest-windows-x86_64/versions/1.2.3/manifest.txt'
}
}

Describe 'Cloudsmith CLI installer activation retry' {

BeforeAll {
Expand Down Expand Up @@ -339,6 +380,36 @@ Describe 'Cloudsmith CLI installer (install.ps1)' -Tag 'Windows' -Skip:(-not $sc
$result.StdOut[0] | Should -Be 'version=2.4.6'
}

It 'installs the release of the requested major version' {
$installRoot = Join-Path $TestDrive ("root-" + [Guid]::NewGuid().ToString('N'))
$fixture = New-CloudsmithFixture -Directory $script:FixtureDir -Version '1.19.0' -Target $script:DefaultTarget -BaseUrl $script:Server.Url

$result = Invoke-Installer -HostExe $currentHostExe -ScriptArguments @(
'-Version', '1',
'-InstallRoot', $installRoot,
'-Target', $script:DefaultTarget,
'-ManifestUrl', $fixture.ManifestUrl
)

$result.ExitCode | Should -Be 0 -Because "stderr: $($result.StdErr)"
$result.StdOut[0] | Should -Be 'version=1.19.0'
}

It 'fails when the manifest is outside the requested major version' {
$installRoot = Join-Path $TestDrive ("root-" + [Guid]::NewGuid().ToString('N'))
$fixture = New-CloudsmithFixture -Directory $script:FixtureDir -Version '10.0.0' -Target $script:DefaultTarget -BaseUrl $script:Server.Url

$result = Invoke-Installer -HostExe $currentHostExe -ScriptArguments @(
'-Version', '1',
'-InstallRoot', $installRoot,
'-Target', $script:DefaultTarget,
'-ManifestUrl', $fixture.ManifestUrl
)

$result.ExitCode | Should -Not -Be 0
$result.StdErr | Should -Match 'expected a 1\.x release'
}

It 'writes exactly four lines to -OutputFile (UTF-8, no BOM) and leaves stdout empty' {
$installRoot = Join-Path $TestDrive ("root-" + [Guid]::NewGuid().ToString('N'))
$outputFile = Join-Path $TestDrive ("out-" + [Guid]::NewGuid().ToString('N') + '.txt')
Expand Down
46 changes: 46 additions & 0 deletions tests/install.bats
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,52 @@ executable=$bin_dir/cloudsmith"
[ -x "$bin_dir/cloudsmith" ]
}

@test "major channel: --version 1 installs the 1.x release in the manifest" {
build_fixture "$FIXTURE_DIR" "1.19.0" "$TEST_TARGET"

run --separate-stderr "$INSTALL_SH" \
--version 1 \
--target "$TEST_TARGET" \
--install-root "$INSTALL_ROOT" \
--manifest-url "$FIXTURE_URL/manifest.txt"

[ "$status" -eq 0 ]
[ "${lines[0]}" = "version=1.19.0" ]
}

@test "major channel: a manifest outside the requested major version fails" {
build_fixture "$FIXTURE_DIR" "10.0.0" "$TEST_TARGET"

run --separate-stderr "$INSTALL_SH" \
--version 1 \
--target "$TEST_TARGET" \
--install-root "$INSTALL_ROOT" \
--manifest-url "$FIXTURE_URL/manifest.txt"

[ "$status" -ne 0 ]
[[ "$stderr" == *"manifest resolved '10.0.0', expected a 1.x release"* ]]
}

@test "major channel: --version 1 requests the manifest of the 1.x channel" {
local stub_bin="$BATS_TEST_TMPDIR/bin"
mkdir -p "$stub_bin"
cat > "$stub_bin/curl" <<'STUB'
#!/usr/bin/env bash
for arg; do :; done
printf '%s\n' "$arg" > "$BATS_TEST_TMPDIR/requested-url"
exit 22
STUB
chmod +x "$stub_bin/curl"

run --separate-stderr env PATH="$stub_bin:$PATH" BATS_TEST_TMPDIR="$BATS_TEST_TMPDIR" "$INSTALL_SH" \
--version 1 \
--target "$TEST_TARGET" \
--install-root "$INSTALL_ROOT"

[ "$status" -ne 0 ]
[ "$(cat "$BATS_TEST_TMPDIR/requested-url")" = "https://dl.cloudsmith.io/public/cloudsmith/cli/raw/names/cloudsmith-cli-v1-manifest-$TEST_TARGET/versions/latest/manifest.txt" ]
}

@test "--output-file writes the four result lines to a file and stdout stays empty" {
build_fixture "$FIXTURE_DIR" "1.19.0" "$TEST_TARGET"
local out_file="$BATS_TEST_TMPDIR/result.txt"
Expand Down
Loading