fix(cli): align mlxcel-server drafter flags with mlxcel serve (--draft-model rejected) #464

Summary

mlxcel-server -m <model> --draft-model <path> --draft-kind mtp fails with error: unexpected argument '--draft-model' found. mlxcel serve accepts --draft-model. The README presents mlxcel-server as equivalent to mlxcel serve, but their speculative-decoding flag names diverge, so copy-pasted commands break. The error even suggests --draft, which is the max-draft-tokens count, not the drafter checkpoint path, so the hint is actively misleading.

Background

mlxcel serve (the mlxcel binary subcommand) exposes the drafter checkpoint as --draft-model (mlx-lm style). mlxcel-server (the standalone binary) exposes it as --model-draft (llama-server style), and separately uses --draft / --draft-max for the per-step draft-token budget. Each binary deliberately mirrors a different upstream naming, but that divergence contradicts the documented equivalence and surprises users.

Proposed Solution

Make both binaries accept both spellings so documented and copy-pasted commands work on either. Add --draft-model as a visible alias of mlxcel-server's --model-draft, and (symmetrically) accept --model-draft on mlxcel serve. Confirm --draft-kind and the draft-token-count flag (--num-draft-tokens vs --draft/--draft-max) are consistently aliased across both. Update the README so the flag table matches reality.

Implementation Notes

• mlxcel-server drafter path: src/bin/mlx_server.rs:249-255 (--model-draft, model_draft: Option<PathBuf>); draft-token count :257-264 (--draft, visible_alias --draft-max). Add visible_alias = "draft-model" to the --model-draft arg.
• mlxcel serve drafter path: src/main.rs:308-310 (--draft-model, draft_model: Option<PathBuf>); add a --model-draft alias for parity.
• Shared speculative flag group SpeculativeArgs (referenced around src/main.rs:1436 and by src/bin/mlx_server.rs) is the natural place to unify the names and aliases.
• README: correct the mlxcel-server vs mlxcel serve flag documentation.

Acceptance Criteria

• mlxcel-server -m <model> --draft-model <path> --draft-kind mtp parses and runs (no "unexpected argument").
• Both --draft-model and --model-draft are accepted by both mlxcel serve and mlxcel-server, resolving to the same drafter option.
• --help on both binaries lists the aliases, and the README equivalence claim is accurate.
• A CLI-parsing test asserts both spellings resolve identically on both binaries.

Original Suggestion

Title: fix: mlxcel-server does not understand --draft-model

Summary

mlxcel-server does not understand --draft-model when a drafter model is given. Only mlxcel serve works well. README says mlxcel-server is an equivalent of mlxcel serve, but in reality, they seem to be different.

Reproduction steps

mlxcel-server -m mlx-community/gemma-4-31B-it-qat-OptiQ-4bit --draft-model mlx-community/gemma-4-31B-it-assistant-bf16 --draft-kind mtp --port 12121
error: unexpected argument '--draft-model' found

  tip: a similar argument exists: '--draft'

Usage: mlxcel-server --model <PATH_OR_REPO_ID> --draft <DRAFT>

For more information, try '--help'.

Expected behavior

it should work

Actual behavior

it throws an error

mlxcel version

v0.3.2

Install method

Homebrew (lablup/tap)

Platform

macOS (Apple Silicon)

Model checkpoint

No response

Relevant logs

Additional context

No response

Pre-submission checks

• I searched existing issues and did not find a duplicate
• This is not a security vulnerability (those go to SECURITY.md instead)