Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

CLI: load command modules other than studio only when a command is dispatched (#15689)

Daniel Han83f76e248d3d
diff --git a/unsloth_cli/__init__.py b/unsloth_cli/__init__.py
index 554d0463bcc..fb4514bf6eb 100644
--- a/unsloth_cli/__init__.py
+++ b/unsloth_cli/__init__.py
@@ -85,12 +85,46 @@ if _is_entry_point:
_drop_unwritable_ssl_keylog_file()
import typer
+from collections.abc import MutableMapping as _MutableMapping
from importlib.metadata import version as package_version, PackageNotFoundError
-if _windows_studio_mutation_entry:
- from unsloth_cli.commands.studio import studio_app, _expand_attached_np_short
-else:
+from unsloth_cli._argv import _expand_attached_np_short
+
+# typer lists commands before sub-apps, each in registration order.
+_COMMAND_ORDER = (
+ "train",
+ "inference",
+ "chat",
+ "export",
+ "eval",
+ "list-checkpoints",
+ "doctor",
+ "run",
+ "install-kernels",
+ "studio",
+ "start",
+ "mcp",
+ "connect",
+)
+
+# Only a real dispatch loads command modules on first use; help, version, completion and library
+# imports stay eager so Desktop's `unsloth -h` probe still fails when any command module is broken.
+_EAGER_TOKENS = frozenset(
+ ("-h", "--help", "-V", "--version", "--install-completion", "--show-completion")
+)
+_cli_args = (
+ _sys.argv[1:] if (_is_entry_point or (_entry_base == "-m" and _runs_unsloth_cli)) else None
+)
+_load_every_command = not _windows_studio_mutation_entry and (
+ not _cli_args
+ or _cli_args[0] not in _COMMAND_ORDER
+ or any(_arg in _EAGER_TOKENS for _arg in _cli_args)
+ or "_UNSLOTH_COMPLETE" in _os.environ
+)
+del _cli_args
+
+if _load_every_command:
from unsloth_cli.commands.train import train
from unsloth_cli.commands.inference import inference
from unsloth_cli.commands.chat import chat
@@ -99,12 +133,10 @@ else:
from unsloth_cli.commands.eval import evaluate as eval_command
from unsloth_cli.commands.doctor import doctor
from unsloth_cli.commands.mcp import mcp_app
- from unsloth_cli.commands.studio import (
- run as studio_run,
- studio_app,
- _expand_attached_np_short,
- _LlamaPassthroughCommand,
- )
+ from unsloth_cli.commands.studio import run as studio_run, _LlamaPassthroughCommand
+
+# Always eager: `unsloth studio run` is the command Desktop starts the backend with.
+from unsloth_cli.commands.studio import studio_app
_entry_point_prepared = False
@@ -165,6 +197,14 @@ if _TyperGroup is not None:
arguments rather than by the host's argv.
"""
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+ self.commands = _LazyCommands(self.commands, _ACTIVE_LAZY_COMMANDS)
+ if _load_every_command:
+ # A command typer cannot build must still fail `unsloth -h` and `--version`.
+ for _name in list(self.commands):
+ self.commands[_name]
+
def parse_args(self, ctx, args):
ctx.meta.setdefault(_ARGV_META_KEY, list(args))
return super().parse_args(ctx, args)
@@ -227,42 +267,162 @@ def main(
raise typer.Exit(code = 1)
+_LAZY_COMMANDS = (
+ "train",
+ "inference",
+ "chat",
+ "export",
+ "eval",
+ "list-checkpoints",
+ "doctor",
+ "run",
+ "start",
+ "mcp",
+ "connect",
+)
+_ACTIVE_LAZY_COMMANDS = () if _windows_studio_mutation_entry else _LAZY_COMMANDS
+
+
+def _register_command(app, name):
+ if name == "train":
+ from unsloth_cli.commands.train import train
+ app.command()(train)
+ elif name == "inference":
+ from unsloth_cli.commands.inference import inference
+ app.command()(inference)
+ elif name == "chat":
+ from unsloth_cli.commands.chat import chat
+ app.command()(chat)
+ elif name == "export":
+ from unsloth_cli.commands.export import export
+ app.command()(export)
+ elif name == "eval":
+ from unsloth_cli.commands.eval import evaluate as eval_command
+ app.command("eval")(eval_command)
+ elif name == "list-checkpoints":
+ from unsloth_cli.commands.export import list_checkpoints
+ app.command("list-checkpoints")(list_checkpoints)
+ elif name == "doctor":
+ from unsloth_cli.commands.doctor import doctor
+ app.command("doctor")(doctor)
+ elif name == "start":
+ from unsloth_cli.commands.start import start_app
+ app.add_typer(
+ start_app,
+ name = "start",
+ help = "Start a coding agent (Claude, Codex, OpenClaw, OpenCode, Hermes, Pi, dsh, Vibe, "
+ "VS Code) against Unsloth.",
+ )
+ elif name == "mcp":
+ from unsloth_cli.commands.mcp import mcp_app
+ app.add_typer(
+ mcp_app, name = "mcp", help = "Connect coding agents to the Unsloth Studio MCP server."
+ )
+ elif name == "connect":
+ from unsloth_cli.commands.start import start_app
+
+ # backwards-compatible hidden alias: `unsloth connect` routes to `unsloth start`.
+ app.add_typer(
+ start_app,
+ name = "connect",
+ hidden = True,
+ help = "Deprecated alias for `unsloth start`.",
+ )
+ elif name == "run":
+ from unsloth_cli.commands.studio import run as studio_run, _LlamaPassthroughCommand
+
+ # top-level `unsloth run` aliases `unsloth studio run`; same context so unknown flags pass through to llama-server.
+ app.command(
+ "run",
+ cls = _LlamaPassthroughCommand,
+ context_settings = {
+ "allow_extra_args": True,
+ "ignore_unknown_options": True,
+ },
+ help = "Alias for `unsloth studio run`.",
+ )(studio_run)
+ else:
+ raise KeyError(name)
+
+
+def _load_command(name):
+ scratch = typer.Typer(add_completion = False)
+ _register_command(scratch, name)
+ return typer.main.get_group(scratch).commands[name]
+
+
+_PENDING = object()
+
+
+class _LazyCommands(_MutableMapping):
+ """`group.commands` whose pending entries build on first lookup."""
+
+ def __init__(self, eager, lazy_names):
+ self._commands = {}
+ for name in _COMMAND_ORDER:
+ if name in eager:
+ self._commands[name] = eager[name]
+ elif name in lazy_names:
+ self._commands[name] = _PENDING
+ for name, command in eager.items():
+ self._commands.setdefault(name, command)
+
+ def pending(self, name):
+ return self._commands.get(name) is _PENDING
+
+ def __getitem__(self, name):
+ command = self._commands[name]
+ if command is _PENDING:
+ command = self._commands[name] = _load_command(name)
+ return command
+
+ def __setitem__(self, name, command):
+ self._commands[name] = command
+
+ def __delitem__(self, name):
+ del self._commands[name]
+
+ def __contains__(self, name):
+ return name in self._commands
+
+ def __iter__(self):
+ return iter(self._commands)
+
+ def __len__(self):
+ return len(self._commands)
+
+
app.add_typer(studio_app, name = "studio", help = "Unsloth Studio commands.")
-if not _windows_studio_mutation_entry:
- app.command()(train)
- app.command()(inference)
- app.command()(chat)
- app.command()(export)
- app.command("eval")(eval_command)
- app.command("list-checkpoints")(list_checkpoints)
- app.command("doctor")(doctor)
- app.add_typer(
- start_app,
- name = "start",
- help = "Start a coding agent (Claude, Codex, OpenClaw, OpenCode, Hermes, Pi, dsh, Vibe, "
- "VS Code) against Unsloth.",
- )
- app.add_typer(
- mcp_app, name = "mcp", help = "Connect coding agents to the Unsloth Studio MCP server."
- )
- # backwards-compatible hidden alias: `unsloth connect` routes to `unsloth start`.
- app.add_typer(
- start_app,
- name = "connect",
- hidden = True,
- help = "Deprecated alias for `unsloth start`.",
- )
-
- # top-level `unsloth run` aliases `unsloth studio run`; same context so unknown flags pass through to llama-server.
- app.command(
- "run",
- cls = _LlamaPassthroughCommand,
- context_settings = {
- "allow_extra_args": True,
- "ignore_unknown_options": True,
- },
- help = "Alias for `unsloth studio run`.",
- )(studio_run)
+if _ArgvCapturingGroup is None: # pragma: no cover - no group class to defer through
+ for _name in _COMMAND_ORDER:
+ if _name in _ACTIVE_LAZY_COMMANDS:
+ _register_command(app, _name)
+
+
+# Names this module used to import eagerly, for callers that still read them here.
+_LAZY_ATTRIBUTES = {
+ "train": ("unsloth_cli.commands.train", "train"),
+ "inference": ("unsloth_cli.commands.inference", "inference"),
+ "chat": ("unsloth_cli.commands.chat", "chat"),
+ "start_app": ("unsloth_cli.commands.start", "start_app"),
+ "export": ("unsloth_cli.commands.export", "export"),
+ "list_checkpoints": ("unsloth_cli.commands.export", "list_checkpoints"),
+ "eval_command": ("unsloth_cli.commands.eval", "evaluate"),
+ "doctor": ("unsloth_cli.commands.doctor", "doctor"),
+ "mcp_app": ("unsloth_cli.commands.mcp", "mcp_app"),
+ "studio_run": ("unsloth_cli.commands.studio", "run"),
+ "studio_app": ("unsloth_cli.commands.studio", "studio_app"),
+ "_LlamaPassthroughCommand": ("unsloth_cli.commands.studio", "_LlamaPassthroughCommand"),
+}
+
+
+def __getattr__(name):
+ try:
+ module_name, attribute = _LAZY_ATTRIBUTES[name]
+ except KeyError:
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+ import importlib
+ return getattr(importlib.import_module(module_name), attribute)
@app.command(
diff --git a/unsloth_cli/_argv.py b/unsloth_cli/_argv.py
new file mode 100644
index 00000000000..fcc944a757c
--- /dev/null
+++ b/unsloth_cli/_argv.py
@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Console-script argv rewrites. Stdlib only: the entry point runs this before any command module loads."""
+
+import sys
+
+
+def _expand_attached_np_short() -> None:
+ # Click clusters `-np8` as `-n -p 8`, dropping the value. Lockstep with the backend `_flag_name`.
+ i = 0
+ while i < len(sys.argv):
+ tok = sys.argv[i]
+ if tok == "--":
+ break
+ if len(tok) > 3 and tok.startswith("-np") and tok[3] != "=":
+ suffix = tok[3:]
+ first_numeric = suffix[0].isdigit() or (
+ len(suffix) > 1 and suffix[0] in {"-", "+"} and suffix[1].isdigit()
+ )
+ if first_numeric:
+ sys.argv[i : i + 1] = ["-np", suffix]
+ i += 2
+ continue
+ i += 1
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index 7e7f69d6da2..7797a4ba2ab 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -30,6 +30,7 @@ import typer
from typer.core import TyperCommand
from unsloth_cli import _studio_deps, _studio_runtime_gate, _studio_stage
+from unsloth_cli._argv import _expand_attached_np_short as _expand_attached_np_short
from unsloth_cli._inference import SpeculativeType
from unsloth_cli.commands import _password_prompt
from studio.backend.utils.pid_records import (
@@ -2281,25 +2282,6 @@ def _split_repo_variant(model_arg: str) -> tuple[str, Optional[str]]:
return repo, variant
-def _expand_attached_np_short() -> None:
- # Click clusters `-np8` as `-n -p 8`, dropping the value. Lockstep with the backend `_flag_name`.
- i = 0
- while i < len(sys.argv):
- tok = sys.argv[i]
- if tok == "--":
- break
- if len(tok) > 3 and tok.startswith("-np") and tok[3] != "=":
- suffix = tok[3:]
- first_numeric = suffix[0].isdigit() or (
- len(suffix) > 1 and suffix[0] in {"-", "+"} and suffix[1].isdigit()
- )
- if first_numeric:
- sys.argv[i : i + 1] = ["-np", suffix]
- i += 2
- continue
- i += 1
-
-
def _consume_legacy_short_aliases(
args: List[str], aliases: tuple[str, ...], current: Optional[str], canonical: str
) -> tuple[Optional[str], List[str]]:
diff --git a/unsloth_cli/tests/test_cli_import_cost.py b/unsloth_cli/tests/test_cli_import_cost.py
index c27a7934d68..0cfaf96a01e 100644
--- a/unsloth_cli/tests/test_cli_import_cost.py
+++ b/unsloth_cli/tests/test_cli_import_cost.py
@@ -25,6 +25,9 @@ def _child_json(code: str):
[sys.executable, "-c", probe],
capture_output = True,
text = True,
+ # The CLI writes UTF-8 on Windows (rich box drawing in help); the locale codec is cp1252 there.
+ encoding = "utf-8",
+ errors = "replace",
cwd = str(_REPO_ROOT),
timeout = 300,
)
diff --git a/unsloth_cli/tests/test_cli_lazy_commands.py b/unsloth_cli/tests/test_cli_lazy_commands.py
new file mode 100644
index 00000000000..7c5820b92e3
--- /dev/null
+++ b/unsloth_cli/tests/test_cli_lazy_commands.py
@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Only a real dispatch loads command modules lazily; help, version (Desktop's probe) and library imports stay eager."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+import typer
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+ sys.path.insert(0, str(_REPO_ROOT))
+
+import unsloth_cli # noqa: E402
+
+LAZY_MODULES = (
+ "unsloth_cli.commands.train",
+ "unsloth_cli.commands.inference",
+ "unsloth_cli.commands.chat",
+ "unsloth_cli.commands.export",
+ "unsloth_cli.commands.eval",
+ "unsloth_cli.commands.doctor",
+ "unsloth_cli.commands.mcp",
+ "unsloth_cli.commands.start",
+ "unsloth_cli.config",
+)
+
+
+def _run_console_script(
+ args: list[str],
+ *,
+ stop_studio_run: bool = False,
+ broken: str = "",
+):
+ stop = ""
+ breaker = ""
+ if broken:
+ breaker = (
+ "import importlib.abc\n"
+ "class _Broken(importlib.abc.MetaPathFinder):\n"
+ " def find_spec(self, name, path = None, target = None):\n"
+ f" if name == {broken!r}:\n"
+ " raise ImportError('deliberately broken: ' + name)\n"
+ "sys.meta_path.insert(0, _Broken())\n"
+ )
+ if stop_studio_run:
+ # Stop `studio run` at the first statement of its body, before any server work.
+ stop = (
+ "import unsloth_cli.commands.studio as _s\n"
+ "def _stop(*a, **k):\n"
+ " raise SystemExit(0)\n"
+ "_s._consume_start_api_key_marker_env = _stop\n"
+ )
+ probe = (
+ "import json, sys\n"
+ f"{breaker}"
+ f"sys.argv = ['unsloth', *{args!r}]\n"
+ "import unsloth_cli\n"
+ f"{stop}"
+ "try:\n"
+ " unsloth_cli.app()\n"
+ "except SystemExit:\n"
+ " pass\n"
+ f"watched = {(*LAZY_MODULES, 'pydantic')!r}\n"
+ "print(json.dumps(sorted(m for m in watched if m in sys.modules)))\n"
+ )
+ return subprocess.run(
+ [sys.executable, "-c", probe],
+ capture_output = True,
+ text = True,
+ # The CLI writes UTF-8 on Windows (rich box drawing in help); the locale codec is cp1252 there.
+ encoding = "utf-8",
+ errors = "replace",
+ cwd = str(_REPO_ROOT),
+ env = {**__import__("os").environ, "NO_COLOR": "1", "COLUMNS": "80"},
+ )
+
+
+def _modules_after(args: list[str], *, stop_studio_run: bool = False) -> set[str]:
+ result = _run_console_script(args, stop_studio_run = stop_studio_run)
+ assert result.returncode == 0, result.stderr
+ return set(json.loads(result.stdout.strip().splitlines()[-1]))
+
+
+def _pydantic_preloaded() -> bool:
+ result = subprocess.run(
+ [sys.executable, "-c", "import sys, typer, rich; print('pydantic' in sys.modules)"],
+ capture_output = True,
+ text = True,
+ encoding = "utf-8",
+ errors = "replace",
+ )
+ return result.stdout.strip() == "True"
+
+
+HELP_AND_VERSION = [
+ [],
+ ["-h"],
+ ["--help"],
+ ["--version"],
+ ["-V"],
+ ["studio", "-h"],
+ ["studio", "run", "--help"],
+ ["studio", "provision-desktop-auth", "--help"],
+ ["train", "--help"],
+ ["not-a-command"],
+]
+
+
[email protected]("args", HELP_AND_VERSION)
+def test_help_and_version_still_import_every_command_module(args):
+ result = _run_console_script(args)
+ loaded = set(json.loads(result.stdout.strip().splitlines()[-1]))
+ assert loaded == {*LAZY_MODULES, "pydantic"}
+
+
[email protected]("args", HELP_AND_VERSION)
[email protected]("broken", ["unsloth_cli.commands.train", "unsloth_cli.commands.mcp"])
+def test_a_broken_command_module_still_fails_help_and_version(args, broken):
+ """Desktop's `unsloth -h` health probe relies on this to start its repair flow."""
+ result = _run_console_script(args, broken = broken)
+ assert result.returncode == 1
+ assert f"ImportError: deliberately broken: {broken}" in result.stderr
+
+
+def test_a_broken_unrelated_module_does_not_block_studio_run():
+ result = _run_console_script(
+ ["studio", "run", "--model", "x"],
+ stop_studio_run = True,
+ broken = "unsloth_cli.commands.train",
+ )
+ assert result.returncode == 0, result.stderr
+
+
+def lazy_group(monkeypatch):
+ monkeypatch.setattr(unsloth_cli, "_load_every_command", False)
+ return typer.main.get_command(unsloth_cli.app)
+
+
+def test_a_library_import_builds_every_command():
+ group = typer.main.get_command(unsloth_cli.app)
+ assert not any(group.commands.pending(name) for name in group.commands)
+
+
[email protected]("args", [["studio", "run", "--model", "x"], ["run", "--model", "x"]])
+def test_studio_run_body_starts_without_other_command_modules(args):
+ loaded = _modules_after(args, stop_studio_run = True)
+ if _pydantic_preloaded():
+ loaded.discard("pydantic")
+ assert loaded == set()
+
+
+def test_a_named_command_loads_only_its_module():
+ loaded = _modules_after(["list-checkpoints", "--no-such-option"])
+ assert "unsloth_cli.commands.export" in loaded
+ assert "unsloth_cli.commands.train" not in loaded
+ assert "unsloth_cli.commands.start" not in loaded
+
+
+# What `unsloth -h` listed when every command module was imported up front.
+EAGER_ORDER = [
+ "train",
+ "inference",
+ "chat",
+ "export",
+ "eval",
+ "list-checkpoints",
+ "doctor",
+ "run",
+ "install-kernels",
+ "studio",
+ "start",
+ "mcp",
+ "connect",
+]
+
+
+def test_every_registered_command_has_a_fixed_position(lazy_group):
+ """typer lists commands before sub-apps; a new one must be placed in _COMMAND_ORDER."""
+ group = lazy_group
+ names = list(group.commands)
+ assert names == EAGER_ORDER
+ assert set(names) <= set(unsloth_cli._COMMAND_ORDER)
+ assert names == [n for n in unsloth_cli._COMMAND_ORDER if n in names]
+ kinds = [isinstance(group.commands[n], typer.core.TyperGroup) for n in names]
+ assert kinds == sorted(kinds), "commands must precede sub-apps, as typer orders them"
+
+
+def test_former_module_attributes_still_resolve():
+ from unsloth_cli.commands import eval as eval_mod, export, start, studio, train
+
+ assert unsloth_cli.train is train.train
+ assert unsloth_cli.eval_command is eval_mod.evaluate
+ assert unsloth_cli.list_checkpoints is export.list_checkpoints
+ assert unsloth_cli.start_app is start.start_app
+ assert unsloth_cli.studio_run is studio.run
+ assert unsloth_cli.studio_app is studio.studio_app
+ assert unsloth_cli._expand_attached_np_short is studio._expand_attached_np_short
+ with pytest.raises(AttributeError):
+ unsloth_cli.not_a_command
diff --git a/unsloth_cli/tests/test_inference_chat.py b/unsloth_cli/tests/test_inference_chat.py
index ab8a628136c..96500b2294c 100644
--- a/unsloth_cli/tests/test_inference_chat.py
+++ b/unsloth_cli/tests/test_inference_chat.py
@@ -636,8 +636,12 @@ def test_you_prompt_matches_readline_backend(monkeypatch):
def test_chat_registered_on_app():
from unsloth_cli import app
- names = {(cmd.name or cmd.callback.__name__) for cmd in app.registered_commands}
- assert "chat" in names
+ from unsloth_cli.commands.chat import chat
+
+ # Registered lazily on the click group, not in app.registered_commands.
+ command = typer.main.get_command(app).commands["chat"]
+ assert command.name == "chat"
+ assert command.callback.__wrapped__ is chat
def test_chat_exits_cleanly_on_slash_exit(monkeypatch):