Accept a pinned version with or without the leading v

CHANGELOG.md

@@ -104,6 +104,18 @@ that may never merge. They are not releases and are not listed here.
   parameter the request never carried, and anyone pasting it sent something
   different from what was being debugged.
 
+- `MAPBOX_CLI_VERSION` now accepts a version with or without the leading `v`.
+  The channel's directories are named `v0.2.1`, but every place a person reads
+  a version from shows it without one — `mapbox --version`, this file,
+  `Cargo.toml` — so the spelling somebody would copy was the one that failed,
+  and it failed as a bare `403` from S3 on a path that does not exist. That
+  reads as "you are not allowed" rather than "no such version". `latest` and
+  any other non-numeric channel name are untouched. Both installers, both
+  covered by their suites.
+
+- `MAPBOX_CLI_VERSION` and `MAPBOX_INSTALL_DIR` are documented in the README,
+  which never mentioned either of them.
+
 ## 0.2.2 - 2026-09-15
 
 ### Changed

README.md

@@ -55,6 +55,21 @@ curl -fsSL https://cli.mapbox.com/install.sh | sh
 irm https://cli.mapbox.com/install.ps1 | iex
 ```
 
+`MAPBOX_CLI_VERSION` pins a version instead of taking the newest:
+
+```sh
+curl -fsSL https://cli.mapbox.com/install.sh | MAPBOX_CLI_VERSION=0.2.1 sh
+```
+
+```powershell
+$env:MAPBOX_CLI_VERSION = '0.2.1'; irm https://cli.mapbox.com/install.ps1 | iex
+```
+
+With or without the leading `v`: `0.2.1` and `v0.2.1` both work, so the
+version `mapbox --version` prints can be pasted straight in.
+`MAPBOX_INSTALL_DIR` chooses where the binary lands, and defaults to
+`~/.local/bin`.
+
 `scripts/install.sh` and `scripts/install.ps1` here are those installers'
 sources; `scripts/test-install.sh` and `scripts/test-install.ps1` exercise
 them end to end without touching the network.

scripts/install.ps1

@@ -56,6 +56,13 @@
     $Version = 'latest'
     if ($env:MAPBOX_CLI_VERSION) { $Version = $env:MAPBOX_CLI_VERSION }
 
+    # Accepted with or without the leading `v`, same as install.sh. The
+    # channel names its directories `v0.2.1`, but `mapbox --version`,
+    # CHANGELOG.md and Cargo.toml all show the version without one, so the
+    # spelling a person copies is the one that used to 403. `latest` and any
+    # other non-numeric channel name is left alone.
+    if ($Version -match '^[0-9]') { $Version = "v$Version" }
+
     $InstallDir = $env:MAPBOX_INSTALL_DIR
 
     # Only set if you need a non-production channel. Set MAPBOX_CLI_AUTH to

scripts/install.sh

@@ -21,6 +21,20 @@ set -eu
 
 BASE_URL="${MAPBOX_CLI_BASE_URL:-__MAPBOX_CLI_BASE_URL__}"
 VERSION="${MAPBOX_CLI_VERSION:-latest}"
+
+# A pinned version is accepted with or without the leading `v`.
+#
+# The channel's directories are named `v0.2.1`, but every place a person reads
+# a version from shows it without one: `mapbox --version`, CHANGELOG.md,
+# Cargo.toml. So the spelling somebody copies is the spelling that used to
+# fail, and it failed as `403` from S3 on a path that does not exist — which
+# reads as "you are not allowed" rather than "no such version".
+#
+# `latest` and anything else non-numeric is left alone: only a leading digit
+# means a version number is being named.
+case "$VERSION" in
+    [0-9]*) VERSION="v${VERSION}" ;;
+esac
 INSTALL_DIR="${MAPBOX_INSTALL_DIR:-$HOME/.local/bin}"
 
 # Where a reader is sent to build from source or report a bad artifact. One

scripts/test-install.ps1

@@ -598,6 +598,31 @@ try {
     Expect-Out 'Installed mapbox 0.1.0-dev.abc1234' 'installs that exact version'
     Expect-Out "channel  $PinnedVersion" 'names the channel it resolved'
 
+    # The channel's directories carry a leading `v`. Every place a person
+    # reads a version from (`mapbox --version`, CHANGELOG.md, Cargo.toml)
+    # shows it without one, so the spelling somebody copies has to work. It
+    # used to 403, which reads as "not allowed" rather than "no such version".
+    #
+    # ASCII only, deliberately: PSScriptAnalyzer's
+    # PSUseBOMForUnicodeEncodedFile fails a non-ASCII .ps1 that has no BOM,
+    # and an em-dash in this comment is what turned CI red the first time.
+    Start-Case 'MAPBOX_CLI_VERSION accepts a version without the leading v'
+    New-CaseEnv 'pinned-bare'
+    $env:MAPBOX_CLI_VERSION = $PinnedVersion -replace '^v', ''
+    Invoke-Installer
+    Expect-Status 0 'exits 0'
+    Expect-Out 'Installed mapbox 0.1.0-dev.abc1234' 'installs that exact version'
+    Expect-Out "channel  $PinnedVersion" 'and resolved the v-prefixed directory'
+
+    # `latest` starts with a letter, so nothing is prepended. Getting this
+    # wrong would break the default install rather than an edge case.
+    Start-Case 'a channel name that is not a version is left alone'
+    New-CaseEnv 'pinned-latest'
+    $env:MAPBOX_CLI_VERSION = 'latest'
+    Invoke-Installer
+    Expect-Status 0 'exits 0'
+    Expect-Out 'channel  latest' 'asked for latest, not vlatest'
+
     Start-Case 'reinstalling reports the version it replaced'
     New-CaseEnv 'upgrade'
     New-FakeBinary (Join-Path $script:BinDir 'mapbox.exe') 'mapbox 0.0.1'

scripts/test-install.sh

@@ -756,6 +756,29 @@ expect_status 0 "$status" 'exits 0'
 expect_out 'Installed mapbox 0.1.0-dev.abc1234' 'installs that exact version'
 expect_out 'channel  v0.1.0-dev.abc1234' 'names the channel it resolved'
 
+# The channel's directories carry a leading `v`. Every place a person reads a
+# version from — `mapbox --version`, CHANGELOG.md, Cargo.toml — shows it
+# without one, so the spelling somebody copies is the one that has to work.
+# It used to 403, which reads as "not allowed" rather than "no such version".
+start 'MAPBOX_CLI_VERSION accepts a version without the leading v'
+new_case_env pinned-bare
+export MAPBOX_CLI_VERSION=0.1.0-dev.abc1234
+export MAPBOX_INSTALL_TILESETS=no
+run_piped && status=0 || status=$?
+expect_status 0 "$status" 'exits 0'
+expect_out 'Installed mapbox 0.1.0-dev.abc1234' 'installs that exact version'
+expect_out 'channel  v0.1.0-dev.abc1234' 'and resolved the v-prefixed directory'
+
+# `latest` starts with a letter, so nothing is prepended to it. Pinning this
+# wrong would break the default install rather than an edge case.
+start 'a channel name that is not a version is left alone'
+new_case_env pinned-latest
+export MAPBOX_CLI_VERSION=latest
+export MAPBOX_INSTALL_TILESETS=no
+run_piped && status=0 || status=$?
+expect_status 0 "$status" 'exits 0'
+expect_out 'channel  latest' 'asked for latest, not vlatest'
+
 start 'an unsupported platform stops before downloading'
 new_case_env unsupported
 shim uname-unsupported uname