LM Studio CLI & API

Workflow completo para usar modelos locales con LM Studio: setup → uso → cleanup.

Fase 0 — Verificar LM Studio

which lms

Si no existe: LM Studio incluye lms desde v0.2.22+. Descargar desde https://lmstudio.ai e iniciar la app al menos una vez para que se registre el CLI en PATH.

lms status

Verifica si la app o el daemon están corriendo. Si no corre nada, iniciar LM Studio o usar lms daemon up para modo headless.

Fase 1 — Setup: Servidor + Modelo

1a — Levantar servidor

lms server start --port 1234
lms server status

Agregar --cors solo si se necesita acceso desde browser o extensiones (VS Code, etc) — implica un riesgo de seguridad.

1b — Descargar modelo (si no tiene uno)

lms get                          # muestra modelos recomendados
lms get llama-3.1-8b             # descarga quant recomendada
lms get llama-3.1-8b@q4_k_m     # quantización específica
lms get --mlx                    # solo modelos MLX (Apple Silicon)
lms get --gguf                   # solo modelos GGUF

Verificar modelos descargados:

lms ls              # lista legible
lms ls --json       # para parsear programáticamente
lms ls --llm        # solo LLMs (excluye embeddings)

1c — Cargar modelo en memoria

Antes de cargar, estimar uso de memoria:

lms load --estimate-only <model>

Cargar con configuración de GPU:

lms load <model> --gpu <valor> --context-length 4096

Configuración de GPU:

VRAM disponible	--gpu	Notas
≥16 GB	max	Full GPU offload, máxima velocidad
8–16 GB	auto	LM Studio decide el split óptimo
4–8 GB	0.5–0.8	Offload parcial, ajustar por modelo
<4 GB / sin GPU	off	Solo CPU, más lento pero funciona

Flags adicionales útiles:

• --identifier "mi-modelo" — nombre custom para referenciarlo en la API
• --ttl 3600 — auto-descarga del modelo tras 1h de inactividad
• --host 192.168.1.5 — cargar en instancia remota

Verificar modelo cargado:

lms ps

Fase 2 — Uso: Texto y Archivos

Chat rápido por CLI

lms chat <model> -p "tu prompt acá"
lms chat <model> -p "Resumí esto: $(cat archivo.txt)"
lms chat <model> -s "Sos un experto en seguridad" -p "analizá este log"
lms chat <model> --stats    # muestra tokens/segundo al final

Ctrl+C detiene la generación en cualquier momento.

Via API — Los 3 endpoints

Una vez que el servidor está corriendo, hay 3 formas de acceder:

API Nativa (/api/v1/chat) — stateful chats, MCP, reasoning, streaming events:

curl http://localhost:1234/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-id",
    "input": "Analizá este texto: ...",
    "stream": false
  }'

OpenAI-compatible (/v1/chat/completions) — tools, structured output, drop-in replacement:

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-id",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Anthropic-compatible (/v1/messages) — requiere LM Studio 0.4.1+:

curl http://localhost:1234/v1/messages \
  -H "x-api-key: lm-studio" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-id",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

Enviar archivo grande via API

CONTENT=$(cat archivo.txt)
curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg c "$CONTENT" \
    '{"model":"model-id","messages":[{"role":"user","content":("Analizá esto:\n"+$c)}]}')"

Desde SDKs (Python/TypeScript)

Apuntar cualquier SDK de OpenAI o Anthropic a localhost. El valor de api_key no importa si auth está deshabilitado (default):

# OpenAI SDK
from openai import OpenAI
client = OpenAI(base_url="http://localhost:1234/v1", api_key="lm-studio")

# Anthropic SDK (requiere 0.4.1+)
from anthropic import Anthropic
client = Anthropic(base_url="http://localhost:1234", api_key="lm-studio")

// OpenAI SDK (TypeScript)
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "http://localhost:1234/v1", apiKey: "lm-studio" });

Comparación de endpoints

Feature	Nativo /api/v1/chat	OpenAI /v1/chat/completions	Anthropic /v1/messages
Streaming	✅	✅	✅
Stateful chats	✅	❌	❌
MCP integration	✅	❌	❌
Custom tools	❌	✅	✅
Reasoning modes	✅	✅	❌
Context length override	✅	❌	❌

Para más detalles sobre la API nativa (stateful chats, MCP, schemas completos): ver references/lms-commands.md.

Fase 3 — Cleanup

Cuando terminás de usar LM Studio:

lms unload --all        # liberar memoria de todos los modelos
lms server stop         # parar servidor HTTP
lms daemon down         # cerrar daemon (si se usó modo headless)

Verificar que todo está limpio:

lms ps                  # debería estar vacío
lms server status       # debería decir "not running"

Si preferís, simplemente cerrar la app de LM Studio hace todo esto automáticamente.

Gotchas

• LM Studio debe abrirse al menos una vez antes de que lms funcione — la primera ejecución registra el CLI en PATH
• --cors es necesario para acceso desde browser/VS Code pero es un riesgo de seguridad — solo habilitarlo cuando se necesite
• --ttl en lms load no tiene default → el modelo queda cargado indefinidamente. En lms chat el default es 3600s (1h)
• Endpoint Anthropic-compat requiere v0.4.1+ (no 0.4.0)
• lms import por default mueve el archivo original, no copia. Usar --copy o --symbolic-link para preservar
• Auth es opt-in: si se activa en Server Settings, los tokens se generan una sola vez — guardarlos inmediatamente
• flash_attention y eval_batch_size solo aplican al engine llama.cpp, no a MLX
• Si un modelo falla al cargar sin error claro → verificar engine compatible con lms runtime ls

Troubleshooting

Problema	Solución
lms no encontrado	Abrir LM Studio al menos una vez
Modelo no carga / OOM	lms load --estimate-only <model>, reducir --gpu
Puerto ocupado	lms server start --port <otro>
Server no responde	lms server status + lms log stream
Runtime incompatible	lms runtime ls, probar otro engine
Auth rechazado	Verificar token en Server Settings → Manage Tokens