feat(install): add --locked flag for strict lockfile mode

[jdx]

Summary

• Adds --locked global flag that requires lockfile URLs to be present during installation
• Adds MISE_LOCKED environment variable and settings.locked config option
• Centralizes the locked check in the base Backend::install_version() method
• When enabled, fails early with clear error if no lockfile URL exists for the current platform

Use Cases

• CI/CD pipelines that want reproducible builds without API calls
• Environments with rate-limited or no GitHub API access
• Users who want to ensure tools are installed from pre-resolved URLs

Changes

• settings.toml: Add locked setting with MISE_LOCKED env var support
• src/cli/mod.rs: Add --locked as a global CLI flag
• src/backend/mod.rs: Add centralized locked check in Backend::install_version()
• src/config/settings.rs: Sync CLI flag to settings
• src/toolset/mod.rs: Add locked field to InstallOptions
• src/install_context.rs: Add locked field to InstallContext
• Various backends: Use lockfile URLs when available (optimization)

Test plan

• Unit tests pass
• mise install --locked fails with clear error when no lockfile URL exists
• MISE_LOCKED=1 mise install works
• Flag appears in --help for all commands (global flag)

🤖 Generated with Claude Code

---

Note

Adds a global --locked flag (and settings.locked/MISE_LOCKED) that requires pre-resolved lockfile URLs for installs, with backends optimized to use lockfile URLs and fail fast when missing.

• CLI & Settings:
  • Flag/Config: Add global --locked flag; new settings.locked (env: MISE_LOCKED).
  • Plumbing: Thread locked through InstallOptions and InstallContext.
• Install Flow:
  • Fail-fast: In Backend::install_version, error if --locked and no lockfile URL for current platform.
• Backends:
  • GitHub/Aqua/UBI: Prefer existing lockfile URLs (skip API lookups); use lockfile URL when present; minor checksum/asset handling preserved.
• Docs & Tooling:
  • Update docs/cli, manpage, mise.usage.kdl, completions (xtasks/fig), settings docs, and JSON schema (schema/mise.json) for locked.

^{Written by Cursor Bugbot for commit 82c7e4e. This will update automatically on new commits. Configure here.}

[Copilot]

Pull request overview

This PR introduces a strict lockfile mode to enforce reproducible installations by requiring pre-resolved URLs from lockfiles, preventing runtime API calls to external services like GitHub or aqua registry.

Key changes:

• Adds --locked global flag, MISE_LOCKED environment variable, and settings.locked config option
• Implements centralized validation in Backend::install_version() to fail early when lockfile URLs are missing
• Optimizes backends (ubi, aqua, github) to prefer lockfile URLs when available

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/cli/mod.rs	Adds --locked as a global CLI flag with documentation
src/config/settings.rs	Syncs CLI flag value to settings configuration
src/toolset/mod.rs	Adds locked field to InstallOptions struct
src/install_context.rs	Adds locked field to InstallContext struct
src/backend/mod.rs	Implements centralized locked mode validation with early failure
src/backend/ubi.rs	Optimizes to use lockfile URLs when available
src/backend/aqua.rs	Refactors to skip API calls when lockfile URL exists
src/backend/github.rs	Adds null check for lockfile URL usage
src/cli/install.rs	Applies locked setting from configuration
src/cli/install_into.rs	Explicitly disables locked mode for install-into command
settings.toml	Documents the new locked setting with usage examples
schema/mise.json	Adds schema definition for locked setting

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

When a lockfile URL exists, setting tag to None may cause issues downstream. The code later uses tag.is_none() at line 108 to determine if version prefixing is needed, which could lead to incorrect version handling when using lockfile URLs. Consider extracting version information from the lockfile URL or maintaining the tag lookup even when a lockfile URL exists.

Suggested change

	let tag = if existing_platform.is_some() {
	None // We'll determine version from URL instead
	let tag = if let Some(ref url) = existing_platform {
	// Try to extract version from the URL using VERSION_REGEX
	VERSION_REGEX
	.captures(get_filename_from_url(url))
	.and_then(|caps| caps.get(1).map(|m| m.as_str().to_string()))

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.10 x -- echo	19.2 ± 0.2	18.7	21.6	1.00
mise x -- echo	19.6 ± 0.3	19.0	21.1	1.02 ± 0.02

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.10 env	18.8 ± 0.6	18.3	24.3	1.00
mise env	19.1 ± 0.4	18.5	23.2	1.02 ± 0.04

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.10 hook-env	18.9 ± 0.2	18.4	19.7	1.00
mise hook-env	19.3 ± 0.5	18.7	21.7	1.02 ± 0.03

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2025.11.10 ls	16.3 ± 0.2	15.8	17.8	1.00
mise ls	16.6 ± 0.3	16.1	18.1	1.02 ± 0.02

xtasks/test/perf

Command	mise-2025.11.10	mise	Variance
install (cached)	106ms	107ms	+0%
ls (cached)	64ms	64ms	+0%
bin-paths (cached)	70ms	71ms	-1%
task-ls (cached)	417ms	429ms	-2%