jdx/mise v2026.10.14

v2026.10.14: Global override config, mise config explain, and stricter tool option checks

on GitHub

A global config.override.toml can now take precedence over project config, and mise config explain describes each key in a config file. Paranoid mode can be turned on per category, and in that mode dotenv files need their own content-bound trust. Installs now fail when a tool has an option its backend doesn't read, which affects existing configs (see Changed).

Added

• Global override files. ~/.config/mise/config.override.toml, and config.<env>.override.toml for each MISE_ENV, rank above every project file, including mise.local.toml and mise.<env>.toml. This covers [env], [tools], [settings], [tasks], hooks and the other sections. Anything the override file doesn't set still comes from the project. mise never writes to these files by default. To write to one, pass --override to use, unuse, set, unset, settings set|add|unset or config get|set. A tool declared in an override file resolves from the global mise.lock and is exempt from the project's --locked check. If MISE_GLOBAL_CONFIG_FILE is set, override files are not loaded. mise config ls shows a Tier column and mise doctor labels the files. #14610 (@jdx)

  # ~/.config/mise/config.override.toml
  [env]
  AWS_PROFILE = "personal"
  
  [tools]
  node = "24"

• mise config explain [KEY] lists each key a config file sets, with its line number and its description from the schema. It flags unknown keys with a "did you mean" suggestion and marks deprecated keys. It reads the file as plain TOML, so it also works on a config mise refuses to load. Pass a key such as tasks to show only that section, --json for machine-readable output, and --file, --global, --system or --override to pick a file. #14642 (@jdx)

• Paranoid mode can be turned on per category. paranoid now accepts a list of config, env_files, plugins and provenance in addition to true/false. MISE_PARANOID=config,env_files also works. true still turns on all four categories. An unknown category name is an error. #14609 (@jdx, @thernstig)

  [settings]
  paranoid = ["env_files"]

• env_file takes several filenames, for example env_file = [".env", ".env.local"] or MISE_ENV_FILE=.env:.env.local. The file nearest the current directory wins. Within one directory, a name later in the list wins. A single string still works. #14606 (@jdx, @thernstig)

• A find_up entry in env._.file can search several names together. Give one entry a path list, and mise searches directory by directory. The closest directory wins, then the later name within a directory. With two separate entries, a .env.local in a parent directory still overrides the project's .env. The docs now explain this difference and how env_file differs from _.file. #14620, #14602 (@jdx)

  [env]
  _.file = { path = [".env", ".env.local"], find_up = true }

• #MISE headers in file tasks accept the same keys as [tasks.<name>], including timeout, vars and the deny_*/allow_* sandbox keys. Before, these keys were ignored with a warning. If one header value is invalid, mise warns and skips that key, and every other task still loads. An invalid confirm or deny_* value is still an error, so a typo can't remove a confirmation prompt or a sandbox restriction. Before, a template named with extends overrode a header's silent. Now the header's value wins. #14637 (@jdx)

• Interactive mise.toml reference in the docs at configuration/reference. It lists every key with its type, choices and default, and you can filter keys and link to them directly. Plain Markdown copies are also published for agents. #14641 (@jdx)

Changed

• Installs fail on tool options the backend doesn't read. Before, such options were silently ignored. A typo or a key meant for another backend now stops the install, and the error names the option: cargo:eza: option 'asset_pattern' is not used by the cargo backend. Keys under platforms are checked too. So far this applies to the cargo, conda, gem, github, gitlab, forgejo, go, http, npm, packslip, pipx, s3, spinel, spm and ubi backends. aqua, plugin and core-language tools are not checked. The npm backend accepts the checksum option that comes from a packageManager field in package.json. #14629, #14655 (@jdx)
• Paranoid mode needs content-bound trust for env files. In paranoid mode, files loaded through _.file, found by the env_file setting, or run by _.source each need their own trust. Editing one of these files revokes its trust. Before, trusting mise.toml also approved these files, and later edits went unchecked. Running mise trust with no path trusts the project's config and every env file it loads. The error names the file but prints none of its values. To exempt a file by path, add it to trusted_config_paths in your global config. With a category list, this check belongs to env_files. #14604 (@jdx, @thernstig)
• More specific config error messages.
  • A warning about an unknown mise.toml key now gives the line and column, and suggests a close match, for example mise.toml:5:1: settings.experimantal (did you mean experimental?). #14639 (@jdx)
  • A wrong value for a hook, a task run/depends entry or an [env] variable now says which forms are accepted, or names the unknown key. Before, the error was data did not match any variant of untagged enum. An unknown key in a run or depends table now gets a warning. Before, it was silently ignored. #14640 (@jdx)
• [bootstrap.linux.firewall] is validated on every OS. macOS and Windows still skip the section at bootstrap time, but an invalid value such as backend = "iptables" is now an error there too. #14615 (@jdx)
• Editor schema updates. Editors now flag unknown keys in most [bootstrap] tables and in [dotfiles] entries. The schema now documents launchd keep_alive_on_failure and nice, and dotfile autosave and enabled. It also accepts valid configs it used to reject: templated login_shell, queue_directories and umask, nested macOS defaults values, and tools on [vars] entries. On Windows, [bootstrap.brew].adopt no longer causes an unknown-field warning. #14616, #14644, #14613 (@jdx)
• mise dot status and mise dot sync are faster with many tracked files. They start one git process per tracked file instead of three, which took about 10s down to 4s for 860 files. #14607 (@waynehoover)

Fixed

• With an external rustup that keeps its proxies in a shared directory, such as pacman's /usr/bin, mise no longer puts that directory ahead of its own tools. Before, mise exec -- node could run the system Node. Only the Rust proxies are now exposed, through a directory that mise owns. #14597 (@jdx)
• The cargo backend now honors rename_exe. Before, it ignored the option and installed the executable under its original name. #14626 (@jdx)
• Locked pypi: installs through uv now pass the configured mise Python to uv sync. Before, mise passed an empty path, so uv could pick another interpreter and fail on --no-build tools such as yamllint. #14593 (@jdx, @hollow)
• When the TLS root store or a CA file can't be loaded, the npm backend now reports an error instead of crashing mise with a core dump. #14595 (@jdx)
• On fish, mise no longer recurses until fish hits its call stack limit after mise implode. #14594 (@jdx, @thernstig)
• mise bootstrap now finds Nix in /nix/var/nix/profiles/default/bin when a pre-packages hook installed it earlier in the same run, so nix: packages install. #14596 (@jdx)
• MISE_WATCH_FILES_GIT_REWRITTEN is no longer set when HEAD stayed on the same commit, for example after git checkout -b, git reset or git branch -m. Before, format-on-edit hooks skipped files you had just edited. #14585 (@JamBalaya56562)
• Command wrapper templates can now use config_root and config_source. Relative paths in template functions resolve from the wrapper's config file instead of the current directory. #14628 (@JamBalaya56562)

Upgrading

• Unsupported tool options: if an install now fails with option '...' is not used by the ... backend, remove the option or fix its spelling. mise config explain tools shows which keys mise doesn't recognize.
• Paranoid mode: after upgrading, run mise trust in each project to approve its env files. Run it again after editing them. If you only want the env-file check, set paranoid = ["env_files"].
• Firewall config on macOS and Windows: if a shared config has an invalid [bootstrap.linux.firewall] value, it now fails to load on macOS and Windows too. Correct the value.

Full Changelog: v2026.10.13...v2026.10.14

💚 Sponsor mise

mise is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If mise saves you or your team time, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep mise fast, free, and independent.