feat: add --before flag for date-based version filtering

docs/cli/install.md

@@ -42,6 +42,12 @@ Show installation output
 
 This argument will print plugin output such as download, configuration, and compilation output.
 
+### `--before <BEFORE>`
+
+Only install versions released before this date
+
+Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y".
+
 ### `--raw`
 
 Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1

docs/cli/upgrade.md

@@ -46,6 +46,16 @@ would change your config to `node = "22"`.
 
 Just print what would be done, don't actually do it
 
+### `--before <BEFORE>`
+
+Only upgrade to versions released before this date
+
+Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y".
+This can be useful for reproducibility or security purposes.
+
+This only affects fuzzy version matches like "20" or "latest".
+Explicitly pinned versions like "22.5.0" are not filtered.
+
 ### `--raw`
 
 Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1

docs/cli/use.md

@@ -64,6 +64,12 @@ Specify a path to a config file or directory
 
 If a directory is specified, it will look for a config file in that directory following the rules above.
 
+### `--before <BEFORE>`
+
+Only install versions released before this date
+
+Supports absolute dates like "2024-06-01" and relative durations like "90d" or "1y".
+
 ### `--fuzzy`
 
 Save fuzzy version to config file

e2e/cli/test_install_before

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Test --before flag for date-based version filtering
+
+set -euo pipefail
+
+# Clean up any existing installations
+mise uninstall tiny --all 2>/dev/null || true
+rm -f mise.toml .tool-versions
+
+# Test: install --before with dry-run should show the tool
+output=$(mise install tiny@latest --before 2020-01-01 --dry-run 2>&1)
+assert_contains "echo '$output'" "tiny"
+
+# Test: install --before should install a version
+mise install tiny@latest --before 2025-01-01
+assert_contains "mise ls --installed tiny" "3.1.0"
+
+# Test: use --before with dry-run
+mise uninstall tiny --all 2>/dev/null || true
+output=$(mise use tiny@latest --before 2025-01-01 --dry-run 2>&1)
+assert_contains "echo '$output'" "tiny"
+rm -f mise.toml
+
+# Test: MISE_INSTALL_BEFORE environment variable works
+mise uninstall tiny --all 2>/dev/null || true
+export MISE_INSTALL_BEFORE="2025-01-01"
+mise install tiny@latest
+assert_contains "mise ls --installed tiny" "3.1.0"
+unset MISE_INSTALL_BEFORE
+
+# Test: upgrade --before with dry-run
+cat <<EOF >mise.toml
+[tools]
+tiny = "1"
+EOF
+mise uninstall tiny --all 2>/dev/null || true
+mise install tiny@1.0.0
+output=$(mise upgrade --before 2025-01-01 --dry-run 2>&1)
+assert_contains "echo '$output'" "tiny"
+
+# Clean up
+mise uninstall tiny --all 2>/dev/null || true
+rm -f mise.toml .tool-versions

e2e/cli/test_ls_cache

@@ -4,6 +4,6 @@ export MISE_USE_VERSIONS_HOST=1
 # verify that cache is reused for `mise ls`
 # see https://github.com/jdx/mise/discussions/6736
 
-assert_contains "mise -v use bat 2>&1" "GET https://mise-versions.jdx.dev/bat 200 OK"
+assert_contains "mise -v use bat 2>&1" "GET https://mise-versions.jdx.dev/bat.toml 200 OK"
 touch -t 202001010000 "$MISE_CACHE_DIR/bat/"*
-assert_not_contains "mise -v ls bat 2>&1" "GET https://mise-versions.jdx.dev/bat 200 OK"
+assert_not_contains "mise -v ls bat 2>&1" "GET https://mise-versions.jdx.dev/bat.toml 200 OK"

man/man1/mise.1

@@ -1204,6 +1204,11 @@ Show installation output
 
 This argument will print plugin output such as download, configuration, and compilation output.
 .TP
+\fB\-\-before\fR \fI<BEFORE>\fR
+Only install versions released before this date
+
+Supports absolute dates like "2024\-06\-01" and relative durations like "90d" or "1y".
+.TP
 \fB\-\-raw\fR
 Directly pipe stdin/stdout/stderr from plugin to user Sets \-\-jobs=1
 \fBArguments:\fR
@@ -2695,6 +2700,15 @@ would change your config to `node = "22"`.
 \fB\-n, \-\-dry\-run\fR
 Just print what would be done, don't actually do it
 .TP
+\fB\-\-before\fR \fI<BEFORE>\fR
+Only upgrade to versions released before this date
+
+Supports absolute dates like "2024\-06\-01" and relative durations like "90d" or "1y".
+This can be useful for reproducibility or security purposes.
+
+This only affects fuzzy version matches like "20" or "latest".
+Explicitly pinned versions like "22.5.0" are not filtered.
+.TP
 \fB\-\-raw\fR
 Directly pipe stdin/stdout/stderr from plugin to user Sets \-\-jobs=1
 \fBArguments:\fR
@@ -2746,6 +2760,11 @@ Specify a path to a config file or directory
 
 If a directory is specified, it will look for a config file in that directory following the rules above.
 .TP
+\fB\-\-before\fR \fI<BEFORE>\fR
+Only install versions released before this date
+
+Supports absolute dates like "2024\-06\-01" and relative durations like "90d" or "1y".
+.TP
 \fB\-\-fuzzy\fR
 Save fuzzy version to config file
 

mise.usage.kdl

@@ -469,6 +469,10 @@ cmd install help="Install a tool version" {
     flag "-v --verbose" help="Show installation output" var=#true count=#true {
         long_help "Show installation output\n\nThis argument will print plugin output such as download, configuration, and compilation output."
     }
+    flag --before help="Only install versions released before this date" {
+        long_help "Only install versions released before this date\n\nSupports absolute dates like \"2024-06-01\" and relative durations like \"90d\" or \"1y\"."
+        arg <BEFORE>
+    }
     flag --raw help="Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1"
     arg "[TOOL@VERSION]…" help="Tool(s) to install e.g.: node@20" required=#false var=#true
 }
@@ -1070,6 +1074,10 @@ cmd upgrade help="Upgrades outdated tools" {
         long_help "Upgrades to the latest version available, bumping the version in mise.toml\n\nFor example, if you have `node = \"20.0.0\"` in your mise.toml but 22.1.0 is the latest available,\nthis will install 22.1.0 and set `node = \"22.1.0\"` in your config.\n\nIt keeps the same precision as what was there before, so if you instead had `node = \"20\"`, it\nwould change your config to `node = \"22\"`."
     }
     flag "-n --dry-run" help="Just print what would be done, don't actually do it"
+    flag --before help="Only upgrade to versions released before this date" {
+        long_help "Only upgrade to versions released before this date\n\nSupports absolute dates like \"2024-06-01\" and relative durations like \"90d\" or \"1y\".\nThis can be useful for reproducibility or security purposes.\n\nThis only affects fuzzy version matches like \"20\" or \"latest\".\nExplicitly pinned versions like \"22.5.0\" are not filtered."
+        arg <BEFORE>
+    }
     flag --raw help="Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1"
     arg "[TOOL@VERSION]…" help="Tool(s) to upgrade\ne.g.: node@20 python@3.10\nIf not specified, all current tools will be upgraded" required=#false var=#true
 }
@@ -1093,6 +1101,10 @@ cmd use help="Installs a tool and adds the version to mise.toml." {
         long_help "Specify a path to a config file or directory\n\nIf a directory is specified, it will look for a config file in that directory following the rules above."
         arg <PATH>
     }
+    flag --before help="Only install versions released before this date" {
+        long_help "Only install versions released before this date\n\nSupports absolute dates like \"2024-06-01\" and relative durations like \"90d\" or \"1y\"."
+        arg <BEFORE>
+    }
     flag --fuzzy help="Save fuzzy version to config file" {
         long_help "Save fuzzy version to config file\n\ne.g.: `mise use --fuzzy node@20` will save 20 as the version\nthis is the default behavior unless `MISE_PIN=1`"
     }

schema/mise.json

@@ -710,6 +710,10 @@
             "type": "string"
           }
         },
+        "install_before": {
+          "description": "Only install versions released before this date",
+          "type": "string"
+        },
         "jobs": {
           "default": 8,
           "description": "How many jobs to run concurrently such as tool installs.",

settings.toml

@@ -581,6 +581,30 @@ parse_env = "list_by_colon"
 rust_type = "BTreeSet<PathBuf>"
 type = "ListPath"
 
+[install_before]
+description = "Only install versions released before this date"
+docs = """
+Filter tool versions by release date. Supports:
+
+- Absolute dates: `2024-06-01`, `2024-06-01T12:00:00Z`
+- Relative durations: `90d` (90 days ago), `1y` (1 year ago), `6m` (6 months ago)
+
+This is useful for reproducible builds or security purposes where you want to ensure
+you're only installing versions that existed before a certain point in time.
+
+Only affects backends that provide release timestamps (aqua, cargo, npm, pipx, and some core plugins).
+Versions without timestamps are included by default.
+
+**Behavior**: This filter only applies when resolving fuzzy version requests like `node@20` or `latest`.
+Explicitly pinned versions like `node@22.5.0` are not filtered, allowing you to selectively
+use newer versions for specific tools while keeping others behind the cutoff date.
+
+Can be overridden with the `--before` CLI flag.
+"""
+env = "MISE_INSTALL_BEFORE"
+optional = true
+type = "String"
+
 [jobs]
 default = 8
 description = "How many jobs to run concurrently such as tool installs."