Thanks for the detailed report — you're not doing anything wrong, these were genuine bugs. Both mise upgrade tool@version and mise lock tool@version should have updated the lockfile with the specified version but weren't.

This is now fixed in #8983. After that lands:

• mise upgrade [email protected] will install 2.34.14, update the lockfile, and leave mise.toml as "latest"
• mise lock [email protected] will update the lockfile to 2.34.14 without reinstalling (you'd still need the version installed)
• To go back to an older version: mise lock [email protected] (or mise upgrade [email protected])

If your config uses a version prefix like awscli = "2" and you upgrade across major versions (e.g., mise upgrade [email protected]), the config prefix will be bumped automatically (e.g., "2" → "3") while preserving the same precision level.

We've also added a command behavior matrix to the docs showing exactly how use/install/upgrade/lock interact with mise.toml and mise.lock.

This comment was generated by Claude Code.

@jdx Thanks for helping out with my confusion!

There's one small thing that I'm pretty sure is a bug:

1

starting lockfile:

[[tools.cmake]]
version = "4.1.6"
backend = "aqua:Kitware/CMake"

# checksums

2

mise lock cmake@latest

lockfile weird:

[[tools.cmake]]
version = "latest" # not a specific version
backend = "aqua:Kitware/CMake"

# no checksums

3

mise lock cmake

lockfile weird differently:

# double entry:
[[tools.cmake]]
version = "latest"
backend = "aqua:Kitware/CMake"

[[tools.cmake]]
version = "4.1.6"
backend = "aqua:Kitware/CMake"

# checksums reappeared

4

mise lock cmake # second time

lockfile finaly correct again:

[[tools.cmake]]
version = "4.1.6"
backend = "aqua:Kitware/CMake"

# checksums

Thanks @igor-makarov — these are two separate bugs in mise lock, both confirmed. Fix is up in #9321:

1. mise lock cmake@latest wrote the literal string "latest" into the lockfile. Fixed: the @latest override now resolves to the newest installed concrete version, so the lockfile gets e.g. version = "4.3.2" and not version = "latest".
2. mise lock cmake (or mise lock) produced a duplicate [[tools.cmake]] entry whenever the config said cmake = "latest" and a newer version was installed than the locked one — and it required a second mise lock run to clean up a lockfile already poisoned with version = "latest". Fixed: the pass-2 "latest" fallback no longer double-adds when pass 1 already produced a match, and any poisoned "latest" pass-1 entry is skipped so it's replaced in a single run.

After that lands, your workflow becomes just:

• Bump: mise lock [email protected] (specific) or mise lock cmake@latest (newest installed). Lockfile updates; mise.toml = "latest" is preserved.
• Downgrade: mise lock [email protected] (must be installed).
• Refresh checksums/URLs: mise lock or mise lock cmake. Current locked version is preserved, not silently upgraded.

This comment was generated by Claude Code.