fix(config): make MISE_OFFLINE work correctly by gracefully skipping network calls

[jdx]

Summary

• Fix MISE_OFFLINE=1 causing hangs/errors — Previously, offline mode blocked all HTTP requests with hard errors (ensure!(!*env::OFFLINE, ...)), but callers didn't handle these gracefully, causing version resolution to fail instead of falling back to local data.
• Add offline and prefer_offline as proper settings — Now configurable via mise.toml (settings.offline = true) and documented, not just env vars.
• Add Settings::offline() and Settings::prefer_offline() convenience methods — Combine settings + env vars + CLI flags in one place, simplifying all call sites.

Key behavior changes:

• versions_host::list_versions() returns Ok(None) when offline/prefer-offline (falls back to local cache)
• versions_host::track_install() skips when offline
• resolve_version() skips all remote fetching when offline, returns raw version string
• list_remote_versions_with_info() returns empty vec![] when offline instead of making HTTP calls
• http.rs ensure checks use Settings::get().offline() (covers both setting and env var)
• Aqua registry wrapper uses Settings::prefer_offline() instead of raw env var access

Closes #6916

Test plan

• mise run build — compiles successfully
• mise run lint-fix — all lints pass
• mise run test:unit — 469 tests pass
• MISE_OFFLINE=1 target/debug/mise ls — lists installed tools without errors/hangs
• MISE_OFFLINE=1 target/debug/mise env — outputs env vars without errors/hangs
• MISE_OFFLINE=1 target/debug/mise settings get offline — returns true
• target/debug/mise settings get prefer_offline — returns false

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches core version resolution and remote version listing paths to change behavior under offline/prefer_offline, which could affect installs and ls-remote results if the new gating is too aggressive or mis-detected.

Overview
Adds new offline and prefer_offline settings (schema + settings.toml docs/env bindings) and centralizes their evaluation via Settings::offline()/Settings::prefer_offline().

Updates multiple network/version codepaths to respect these settings: HTTP requests now block based on Settings::offline(), remote version listing returns empty when offline, versions-host queries/telemetry and aqua registry updates are skipped when (prefer-)offline, and tool version resolution avoids remote lookups in offline mode (with new unit tests covering defaults and implications).

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

[gemini-code-assist]

Summary of Changes

Hello @jdx, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the mise tool's offline capabilities by addressing previous issues where MISE_OFFLINE=1 led to application failures. It introduces robust configuration options for offline and prefer-offline modes, making the tool more resilient in environments with limited or no network access. The changes ensure that mise can operate reliably using locally cached data, preventing errors and improving user experience when network calls are not feasible or desired.

Highlights

• Improved Offline Mode Reliability: The previous MISE_OFFLINE=1 behavior, which caused hard errors and hangs due to unhandled HTTP request blocks, has been fixed. The system now gracefully skips network calls when offline, allowing version resolution to fall back to local data instead of failing.
• Configurable Offline Settings: Introduced offline and prefer_offline as proper settings configurable via mise.toml (e.g., settings.offline = true), in addition to existing environment variables and CLI flags. This provides more flexible control over network behavior.
• New Convenience Methods for Settings: Added Settings::offline() and Settings::prefer_offline() methods. These methods consolidate the logic for checking offline status, combining mise.toml settings, environment variables, and CLI flags into single, easy-to-use access points for all call sites.
• Granular Network Call Handling: Various core functions have been updated to respect the new offline settings. For instance, versions_host::list_versions() now returns Ok(None) when offline, versions_host::track_install() skips tracking, resolve_version() skips remote fetching, and list_remote_versions_with_info() returns an empty list when offline. HTTP requests are now guarded by Settings::get().offline().

Changelog

• schema/mise.json
  • Added offline boolean property to the schema with a description to disable all HTTP requests.
  • Added prefer_offline boolean property to the schema with a description to prefer locally cached data.
• settings.toml
  • Introduced a new offline setting with detailed documentation, mapping to MISE_OFFLINE environment variable and supporting CLI flag.
  • Introduced a new prefer_offline setting with detailed documentation, mapping to MISE_PREFER_OFFLINE environment variable.
• src/aqua/aqua_registry_wrapper.rs
  • Removed direct usage of env::PREFER_OFFLINE and updated to use settings.prefer_offline() for determining offline preference.
  • Updated fetch_latest_repo to use Settings::get().prefer_offline() for skipping aqua registry updates.
• src/backend/mod.rs
  • Added a conditional check within list_remote_versions_with_info to return an empty vector immediately if Settings::get().offline() is true, preventing remote calls.
• src/config/settings.rs
  • Modified fetch_remote_versions_cache to use self.prefer_offline() instead of env::PREFER_OFFLINE.
  • Implemented offline() method to return true if self.offline or *env::OFFLINE is true.
  • Implemented prefer_offline() method to return true if self.offline() or self.prefer_offline or env::PREFER_OFFLINE is true.
• src/http.rs
  • Updated get, head, and post methods to use !Settings::get().offline() in their ensure! checks, centralizing offline mode enforcement.
• src/toolset/tool_version.rs
  • Imported Settings from crate::config.
  • Introduced an is_offline variable using Settings::get().offline().
  • Modified resolve_version to skip remote fetching for 'latest' versions if is_offline is true.
  • Added a new conditional block to resolve_version to immediately return the raw version string if is_offline is true, skipping all remote fetching.
  • Updated the prefer_offline check in resolve_version to use Settings::get().prefer_offline().
• src/versions_host.rs
  • Modified list_versions to return Ok(None) early if settings.prefer_offline() is true.
  • Added a check in track_install to return early if settings.offline() is true, preventing tracking calls when offline.

Activity

• The author compiled the project successfully using mise run build.
• All lints passed after running mise run lint-fix.
• All 469 unit tests passed with mise run test:unit.
• Verified that MISE_OFFLINE=1 target/debug/mise ls lists installed tools without errors or hangs.
• Confirmed that MISE_OFFLINE=1 target/debug/mise env outputs environment variables without errors or hangs.
• Checked that MISE_OFFLINE=1 target/debug/mise settings get offline returns true.
• Verified that target/debug/mise settings get prefer_offline returns false by default.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Copilot]

Pull request overview

Fixes offline-mode behavior so MISE_OFFLINE=1 (and new settings.offline) avoids network calls without breaking version resolution, by centralizing offline/prefer-offline checks in Settings.

Changes:

• Add Settings::offline() / Settings::prefer_offline() helpers and migrate call sites away from raw env checks.
• Skip/short-circuit remote version fetching and tracking when offline/prefer-offline.
• Document and expose offline / prefer_offline in settings.toml and JSON schema.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/versions_host.rs	Skip versions-host listing and tracking when offline/prefer-offline.
src/toolset/tool_version.rs	Avoid remote version resolution in offline and use Settings helpers.
src/http.rs	Gate HTTP requests via Settings::get().offline() rather than raw env flag.
src/config/settings.rs	Introduce offline() / prefer_offline() helpers and use them in caching logic.
src/backend/mod.rs	Return empty remote versions when offline to avoid network calls.
src/aqua/aqua_registry_wrapper.rs	Use Settings::prefer_offline() instead of direct env access.
settings.toml	Add documentation and env bindings for offline and prefer_offline.
schema/mise.json	Add schema entries for offline / prefer_offline.

---

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

[Copilot]

Settings::get() is called multiple times in the same function, which makes the logic harder to read and could lead to inconsistent behavior if Settings are ever reloaded/mutated. Consider storing let settings = Settings::get(); once and reusing settings.offline() / settings.prefer_offline().

Suggested change

	let is_offline = Settings::get().offline();
	let settings = Settings::get();
	let is_offline = settings.offline();

[Copilot]

Settings::get() is called multiple times in the same function, which makes the logic harder to read and could lead to inconsistent behavior if Settings are ever reloaded/mutated. Consider storing let settings = Settings::get(); once and reusing settings.offline() / settings.prefer_offline().

[Copilot]

The trace message still references PREFER_OFFLINE, but the check is now Settings::get().prefer_offline() (which also includes offline). Update the message to reflect the new behavior (e.g., “due to prefer-offline mode”).

Suggested change

	trace!("skipping aqua registry update due to PREFER_OFFLINE");
	trace!("skipping aqua registry update due to prefer-offline mode");

[Copilot]

These new precedence/implication rules (offline implies prefer_offline, plus env/setting interactions) are core behavior. Add unit tests covering key combinations (setting-only, env-only, both set, and ensuring offline() forces prefer_offline()), since regressions here will silently change network behavior across many call sites.

[gemini-code-assist]

Code Review

This pull request effectively addresses issues with offline mode by introducing offline and prefer_offline settings. The changes are well-implemented, centralizing the offline-checking logic into new methods on the Settings struct. These methods are then used throughout the codebase to gracefully skip network requests, preventing hangs and errors when MISE_OFFLINE is enabled. The addition of schema definitions and documentation for the new settings is also a great improvement. Overall, the changes are solid and I have no concerns.

[jdx]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is ON, but a Cloud Agent failed to start.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON, but a Cloud Agent failed to start.}

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.2.9 x -- echo	23.4 ± 0.3	22.5	25.7	1.00
mise x -- echo	24.1 ± 0.4	22.6	27.0	1.03 ± 0.02

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.2.9 env	22.5 ± 0.6	21.1	27.5	1.00
mise env	22.8 ± 0.7	21.4	25.2	1.01 ± 0.04

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.2.9 hook-env	22.8 ± 0.5	21.8	24.0	1.00
mise hook-env	24.3 ± 0.9	22.8	39.2	1.07 ± 0.05

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.2.9 ls	20.8 ± 0.5	19.7	24.0	1.00
mise ls	21.4 ± 0.7	20.0	25.3	1.03 ± 0.04

xtasks/test/perf

Command	mise-2026.2.9	mise	Variance
install (cached)	123ms	124ms	+0%
ls (cached)	76ms	77ms	-1%
bin-paths (cached)	81ms	81ms	+0%
task-ls (cached)	554ms	547ms	+1%