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.

unsloth run: pass llama-server short flags like -ctv, -dev, -ctxcp through whole (#14224)

Daniel Han37989cb4e586
diff --git a/unsloth_cli/__init__.py b/unsloth_cli/__init__.py
index 291a17956ce..4236e5d98b7 100644
--- a/unsloth_cli/__init__.py
+++ b/unsloth_cli/__init__.py
@@ -106,6 +106,7 @@ else:
run as studio_run,
studio_app,
_expand_attached_np_short,
+ _LlamaPassthroughCommand,
)
@@ -258,6 +259,7 @@ if not _windows_studio_mutation_entry:
# 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,
diff --git a/unsloth_cli/commands/studio.py b/unsloth_cli/commands/studio.py
index cf01008f9c1..9baf0f094d0 100644
--- a/unsloth_cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -27,6 +27,7 @@ from datetime import datetime, timezone
from pathlib import Path
from typing import List, Literal, Optional, Sequence, Tuple
import typer
+from typer.core import TyperCommand
from unsloth_cli import _studio_deps, _studio_runtime_gate, _studio_stage
from unsloth_cli._inference import SpeculativeType
@@ -2353,6 +2354,27 @@ def _consume_legacy_short_aliases(
return value, out
+class _LlamaPassthroughCommand(TyperCommand):
+ """Pass unknown short tokens to llama-server whole: Click split `-dev` into `-de` + our -v,
+ and `-ctxcp 8` into --port 8. Tokens starting with our own letter (`-p8888`) still cluster."""
+
+ def make_parser(self, ctx):
+ parser = super().make_parser(ctx)
+ match_short = getattr(parser, "_match_short_opt", None)
+ short_opts = getattr(parser, "_short_opt", None)
+ if match_short is None or short_opts is None or not ctx.ignore_unknown_options:
+ return parser
+
+ def _match_short_opt(arg, state):
+ if len(arg) > 2 and arg[:2] not in short_opts:
+ state.largs.append(arg)
+ return
+ match_short(arg, state)
+
+ parser._match_short_opt = _match_short_opt
+ return parser
+
+
_RUN_PANEL_MODEL = "Model"
_RUN_PANEL_SERVER = "Server & network"
_RUN_PANEL_TOOLS = "Tool calls"
@@ -2361,6 +2383,7 @@ _RUN_PANEL_ADVANCED = "Advanced"
@studio_app.command(
+ cls = _LlamaPassthroughCommand,
context_settings = {
"allow_extra_args": True,
"ignore_unknown_options": True,
diff --git a/unsloth_cli/tests/test_studio_run_llama_short_flags.py b/unsloth_cli/tests/test_studio_run_llama_short_flags.py
new file mode 100644
index 00000000000..ad1daa66b16
--- /dev/null
+++ b/unsloth_cli/tests/test_studio_run_llama_short_flags.py
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+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))
+
+
+def _studio_run():
+ from unsloth_cli.commands.studio import studio_app
+ return typer.main.get_command(studio_app).commands["run"]
+
+
+def _top_level_run():
+ from unsloth_cli import app
+ return typer.main.get_command(app).commands["run"]
+
+
+_COMMANDS = [pytest.param(_studio_run, id = "studio-run"), pytest.param(_top_level_run, id = "run")]
+
+
+def _parse(get_command, args):
+ command = get_command()
+ defaults = command.make_context("run", []).params
+ ctx = command.make_context("run", list(args))
+ changed = {k: v for k, v in ctx.params.items() if defaults.get(k) != v}
+ return list(ctx.args), changed
+
+
+_LLAMA_SHORT_FLAGS = [
+ ["-ctv", "q8_0"],
+ ["-ctvd", "q8_0"],
+ ["-dev", "CUDA0"],
+ ["-devd", "CUDA1"],
+ ["-mmdev", "CUDA0"],
+ ["-kvo"],
+ ["-nkvo"],
+ ["-kvu"],
+ ["-no-kvu"],
+ ["-lv", "3"],
+ ["-ctxcp", "8"],
+ ["-sp"],
+ ["-sps", "0.5"],
+]
+
+
[email protected]("get_command", _COMMANDS)
[email protected]("extras", _LLAMA_SHORT_FLAGS, ids = lambda e: e[0])
+def test_llama_short_flag_reaches_llama_server_whole(get_command, extras):
+ args, changed = _parse(get_command, ["--model", "X", *extras])
+ assert args == extras
+ assert changed == {"model": "X"}
+
+
[email protected]("get_command", _COMMANDS)
+def test_mixed_tail_keeps_its_order(get_command):
+ tail = ["-ctk", "q8_0", "-ctv", "q8_0", "-fa", "on", "-dev", "CUDA0", "--rope-scaling", "yarn"]
+ args, changed = _parse(get_command, ["--model", "X", *tail, "-p", "9001"])
+ assert args == tail
+ assert changed == {"model": "X", "port": 9001}
+
+
[email protected]("get_command", _COMMANDS)
+ "args,expected",
+ [
+ (["-p", "9001"], {"port": 9001}),
+ (["-p9001"], {"port": 9001}),
+ (["-v"], {"verbose": True}),
+ (["-q"], {"silent": True}),
+ (["-y"], {"yes": True}),
+ (["-H", "0.0.0.0"], {"host": "0.0.0.0"}),
+ (["-vq"], {"verbose": True, "silent": True}),
+ (["-hf", "org/repo-GGUF"], {"model": "org/repo-GGUF"}),
+ (["-np", "2"], {"parallel": 2}),
+ ],
+)
+def test_run_own_short_options_unchanged(get_command, args, expected):
+ rest, changed = _parse(get_command, args)
+ assert rest == []
+ assert changed == expected