CLI reference

Every subcommand shipped in rapid-mlx 0.10.3, grouped by role. Captured verbatim from rapid-mlx <subcmd> --help on a fresh pip install rapid-mlx==0.10.3 venv — so what is on this page is exactly what the binary reports.

Every subcommand accepts -h / --help. The top-level command also honours --version and a global --no-telemetry escape hatch (equivalent to RAPID_MLX_TELEMETRY=0 for the current run).

Server

serve

Start the OpenAI-compatible HTTP server. This is the workhorse — every chat / responses / embeddings / audio route lives behind it.

$ rapid-mlx serve qwen3.5-4b-4bit
$ rapid-mlx serve qwen3.6-35b-8bit --port 9000 --host 0.0.0.0
$ rapid-mlx serve gpt-oss-20b-mxfp4-q8 --enable-auto-tool-choice \
    --tool-call-parser harmony

serve has a large surface (~80 flags across host binding, KV cache, speculative decode, tool / reasoning parsing, sampler defaults, cloud fallback, PFlash long-prompt compression, and MCP wiring). Highlights below; the complete flag list is one rapid-mlx serve --help away.

share

Start rapid-mlx serve and open a public Cloudflare-fronted URL on rapidmlx.com so a friend on a different device can hit the model. Uses the built-in websockets reverse tunnel — no port-forwarding.

$ rapid-mlx share qwen3.5-4b-4bit
# prints URL + share key + one-click chat link, Ctrl-C stops

Flags: --port (default 8765), --thinking / --no-thinking (default off, so chat UIs see content immediately), --cors-origins (defaults to the rapidmlx.com chat-frontend allowlist), --rate-limit RPM (default 120), --chat-frontend URL (default https://rapid-pro.quicksilverpro.io; pass empty to suppress).

launch

One-shot bootstrap: patch a detected IDE / agent client (Cline, Claude Code, Continue, Cursor) so it routes at the local rapid-mlx server. rapid-mlx launch list prints the detection matrix.

$ rapid-mlx launch cursor
$ rapid-mlx launch claude-code --model qwen3.6-35b-8bit
$ rapid-mlx launch --all --start-server --port 8000

Flags: client (or list), --all, --model (default $RAPID_MLX_DEFAULT_MODEL or qwen3.5-4b-4bit), --server-url (default http://127.0.0.1:8000), --port, --start-server, --dry-run.

Chat

chat  alias: run

Interactive REPL against a spawned or already-running server. Defaults to qwen3.5-4b-4bit when the model arg is omitted. The run alias is Ollama-parity.

$ rapid-mlx chat
$ rapid-mlx chat qwen3.5-9b-4bit --think
$ rapid-mlx chat --port 8000     # connect to existing server
$ rapid-mlx run gemma-4-12b-4bit # Ollama-style alias

Flags: --system, --think / --no-think (default off in the REPL to avoid reasoning-model CoT leak), --max-tokens (default 2048; 4096 with --think), --temperature (default 0.7), --port, --base-url, --ready-timeout / --response-timeout (default 600 s each).

Model management

models

List every alias registered in vllm_mlx/aliases.json (158 in 0.10.3) with per-alias tool/reasoning parser, spec-decode eligibility, suffix-decoding tier, and DFlash / DDTree readiness.

$ rapid-mlx models              # all aliases
$ rapid-mlx models --cached     # same as `rapid-mlx ls`

ls

List every model in the local HuggingFace cache — alias (or (unmapped)), HF repo, on-disk size, last modified. Equivalent to rapid-mlx models --cached.

pull

Download a model into the HuggingFace cache — no server.

$ rapid-mlx pull qwen3.5-9b-4bit
$ rapid-mlx pull mlx-community/gemma-4-12b-it-4bit

rm

Delete a cached model. Confirms first; -y skips the prompt.

$ rapid-mlx rm qwen3.5-9b-4bit -y

info

Print the per-alias profile — HF repo, tool/reasoning parsers, hybrid flag, MoE flag, spec-decode support, PFlash tier — for one alias or raw HF repo.

$ rapid-mlx info qwen3.6-35b-8bit
$ rapid-mlx info mlx-community/SmolLM3-3B-4bit

ps

List every running rapid-mlx serve process on this machine — PID, port, loaded model, uptime.

Benchmark

bench

Run a benchmark against a model. Freeform mode by default (any --num-prompts / --max-tokens / batching combo), with a --submit path that runs the standardized B=1 community bench and opens a PR to community-benchmarks/.

$ rapid-mlx bench qwen3.5-4b-4bit
$ rapid-mlx bench qwen3.6-35b-8bit --submit                # canonical B=1
$ rapid-mlx bench gpt-oss-20b-mxfp4-q8 --tier speed
$ rapid-mlx bench gpt-oss-20b-mxfp4-q8 --tier all          # smoke → speed → harness

Flags: freeform batching / KV / prefix-cache flags mirror serve (they configure the throwaway server bench spawns); --submit locks every knob for comparability; --sampled re-runs at temp 0.7 / top_p 0.9 into a separate bucket; --notes attaches a max-200-char annotation; --tier {smoke,speed,harness,all} runs a validation ladder (harness drives 5 first-class agent flows: codex/opencode/qwen-code/hermes/aider); --base-url reuses an already-running server for --tier; --long-prompt-tokens + --pflash replicate the long-prompt TTFT profile from PR #649.

Interpret

jlens

Read a model's internal thoughts across layers via the Jacobian lens. Handy for debugging why a model answers the way it does.

$ rapid-mlx jlens "why is the sky blue"
$ rapid-mlx jlens "solve x^2 - 2x - 3 = 0" --model qwen3.6-35b-8bit --step 1 --verbose
$ rapid-mlx jlens "hello" --json

Flags: --model / -m (default qwen3-1.7b), --step (probe every Nth layer, default 2), --json, --verbose / -v. Deep dive: see the jlens page.

Agent / IDE integration

agents

List, configure, and integration-test the first-class agent clients (codex, claude-code, opencode, qwen-code, kilo-code, aider, openhands, hermes, langchain, pydanticai, smolagents).

$ rapid-mlx agents                          # list
$ rapid-mlx agents codex                    # setup guide
$ rapid-mlx agents aider --setup            # auto-configure
$ rapid-mlx agents hermes --test            # run integration flow
$ rapid-mlx agents aider --agent-version 0.90.0 --setup

Flags: agent_name (omit to list), --setup, --test, --model (auto-detected from the running server), --base-url (default http://localhost:8000/v1), --agent-version.

Diagnostics

doctor

One-shot environment check — Apple Silicon detection, macOS + Darwin versions, free disk, HF cache size, Python version, mlx / mlx-lm / transformers / fastapi / uvicorn / rapid-mlx versions, optional-extras status, network probes. Use -v for the underlying probe detail.

$ rapid-mlx doctor
$ rapid-mlx doctor -v

telemetry

Manage anonymous, opt-in usage telemetry. See the telemetry page for the full event schema.

$ rapid-mlx telemetry status    # enabled/disabled + why
$ rapid-mlx telemetry enable
$ rapid-mlx telemetry disable
$ rapid-mlx telemetry preview   # exact bytes we would send
$ rapid-mlx telemetry reset     # wipe client id + consent

Maintenance

upgrade

Detect this install's method (brew, pip, install.sh) and run the right upgrade command. --dry-run just prints what it would do.

$ rapid-mlx upgrade
$ rapid-mlx upgrade --dry-run
$ rapid-mlx upgrade -y

version

Print the version. Same as the top-level --version / -V.

help

Print help for a subcommand. rapid-mlx help serve is equivalent to rapid-mlx serve --help.

Deprecated aliases

The pre-rename binaries vllm-mlx, vllm-mlx-chat, and vllm-mlx-bench still ship as entry points and forward to the same code — kept so muscle memory and old scripts keep working. New usage should always be rapid-mlx.

Next steps