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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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__.pyindex 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 _MutableMappingfrom 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 trainfrom unsloth_cli.commands.inference import inferencefrom unsloth_cli.commands.chat import chat@@ -99,12 +133,10 @@ else:from unsloth_cli.commands.eval import evaluate as eval_commandfrom unsloth_cli.commands.doctor import doctorfrom 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.pynew file mode 100644index 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 += 1diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.pyindex 7e7f69d6da2..7797a4ba2ab 100644--- a/unsloth_cli/commands/studio.py+++ b/unsloth_cli/commands/studio.py@@ -30,6 +30,7 @@ import typerfrom typer.core import TyperCommandfrom unsloth_cli import _studio_deps, _studio_runtime_gate, _studio_stage+from unsloth_cli._argv import _expand_attached_np_short as _expand_attached_np_shortfrom unsloth_cli._inference import SpeculativeTypefrom unsloth_cli.commands import _password_promptfrom 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.pyindex 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.pynew file mode 100644index 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_commanddiff --git a/unsloth_cli/tests/test_inference_chat.py b/unsloth_cli/tests/test_inference_chat.pyindex 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 chatdef test_chat_exits_cleanly_on_slash_exit(monkeypatch):