Blog Artículo

DeepSeek CLI: un agente IA nativo en tu terminal

Apr 29, 2026

5 min read

Esta entrada documenta la publicación de DeepSeek CLI v1.1.0, la primera versión que considero estable para uso real. Si vienes siguiendo el proyecto, esta es la build que recomiendo instalar; si llegas por primera vez, aquí explico de dónde sale la herramienta y cómo ponerla a funcionar.

Contexto: el origen del proyecto

DeepSeek CLI es una adaptación no oficial de Gemini CLI (la herramienta de terminal de Google) para que opere de forma nativa contra la API de DeepSeek.

El planteamiento del port fue tomar Gemini CLI como ejemplo de referencia —su arquitectura agente, su sistema de herramientas, su soporte MCP— y reemplazar la capa de proveedor: fuera la autenticación de Google, fuera los endpoints de Gemini, dentro un ContentGenerator nativo que habla directamente con DeepSeek. El resultado conserva la ergonomía de la CLI original pero corre sobre los modelos deepseek-v4-flash y deepseek-v4-pro.

Por qué la v1.1.0 es la versión que hay que instalar

Las versiones anteriores a la 1.1.0 no son recomendables para uso productivo. Las builds previas tenían un fallo crítico en la integración con la API v4 de DeepSeek: tras un par de turnos de conversación con modo de pensamiento activo, el servidor respondía con HTTP 400 y la sesión quedaba inutilizable.

La causa raíz era doble:

La función getMessageKey generaba claves diferentes para mensajes con tool_calls: undefined y tool_calls: [], por lo que el reasoning_content cacheado se buscaba bajo una clave incorrecta y se descartaba.
El filtro de historial heredado de Gemini eliminaba cualquier campo no textual de los turnos del asistente, removiendo la información de razonamiento incluso cuando la búsqueda en caché tenía éxito.

La v1.1.0 corrige ambos puntos en packages/core/src/core/deepseekContentGenerator.ts: normaliza la clave de caché y “esconde” el reasoning_content dentro de un Part invisible del mensaje del asistente, de manera que sobrevive al filtro de historial y se reincorpora al request siguiente. Con eso, el modo de pensamiento de DeepSeek V4 funciona de forma estable.

Cambios destacados de esta release

Más allá del fix crítico, la 1.1.0 incorpora una serie de ajustes relevantes:

Optimizaciones de costo y latencia

El clasificador de tareas ya no usa modo de pensamiento. La clasificación es una salida JSON estructurada y no se beneficia del razonamiento extendido; deshabilitarlo ahorra tokens y un round-trip completo.
El umbral de complejidad del clasificador subió de 50 a 70, por lo que más tareas se enrutan a deepseek-v4-flash (más barato) en lugar de deepseek-v4-pro, sin regresión observable en el set de evaluación.
Las herramientas se envían a la API en orden alfabético estable, mejorando el hit rate del prompt cache de DeepSeek entre turnos.

Telemetría real de uso

Se activa stream_options.include_usage: true en los requests de streaming, de forma que el chunk SSE final reporta el conteo real de tokens. Antes el comando /stats mostraba ceros.
El contador prompt_cache_hit_tokens se mapea a cachedContentTokenCount en los metadatos de uso, con log de debug por cada hit.

`exit_plan_mode` reparado

Cuando el modelo proponía un plan sin haberlo escrito previamente a disco, la aprobación fallaba porque el validador no encontraba el archivo. La herramienta ahora acepta un parámetro opcional plan_content; cuando se proporciona, escribe el plan en el directorio validado antes de pedir la aprobación. Resultado: el modelo puede salir del modo de planeación en un solo paso.

Branding consistente

Todas las referencias visibles para el usuario que aún decían gemini ahora dicen deepseek: el comando deepseek --resume, los mensajes de error, las pistas de reanudación, los snapshots de tests. En versiones previas había mezcla de ambos nombres en distintos puntos de la UI.

Variables de entorno y directorio de estado

Nueva variable DEEPSEEK_DEBUG: cuando se establece, el generador escribe en stderr la forma de los requests/responses, los aciertos y fallos de caché y las decisiones de recuperación de razonamiento.
El caché de razonamiento y los logs de debug viven en ~/.deepseek/, independiente del directorio de trabajo y de cualquier override de GEMINI_CLI_HOME que se haya configurado para parches previos.

Instalación

Instalación nueva

npm install -g @sluisr/deepseek-cli

Luego ejecutar:

deepseek

En el primer arranque la CLI solicita la API key de DeepSeek. Se obtiene en platform.deepseek.com/api_keys. También puede exportarse en el entorno antes de iniciar la herramienta:

export DEEPSEEK_API_KEY="sk-..."
deepseek

Actualizar a la última versión

npm install -g @sluisr/deepseek-cli@latest

Verificación rápida

DEEPSEEK_API_KEY=sk-... deepseek --prompt "ping"

Para una sesión con logs detallados:

DEEPSEEK_API_KEY=sk-... DEEPSEEK_DEBUG=1 deepseek --prompt "design a small REST API"

Modelo de actualizaciones: notificación, no automatización

Es importante dejar este punto claro porque suele generar confusión: DeepSeek CLI no se actualiza automáticamente. No existe ningún proceso en segundo plano que reemplace la versión instalada sin intervención del usuario.

Lo que sí ocurre es que, al iniciar la CLI, esta consulta el registro de npm y compara la versión local con la última publicada. Si detecta que hay una versión más reciente, lo notifica en pantalla. La actualización propiamente dicha queda a cargo del usuario, ejecutando manualmente:

npm install -g @sluisr/deepseek-cli@latest

Esta separación es deliberada. Una herramienta que toca archivos del proyecto y ejecuta comandos de shell no debería cambiar de comportamiento sin que el operador lo apruebe. La notificación informa, pero el control queda en el usuario.

Notas de migración

No se requiere migrar configuración. Los archivos existentes en ~/.gemini/ se siguen leyendo; únicamente el caché de runtime y los logs se mueven a ~/.deepseek/.
Si en versiones previas se definió GEMINI_CLI_HOME para sortear problemas de rutas, puede eliminarse; el bug de duplicación que motivaba ese workaround ya no existe.
Cualquier script que dependiera del mensaje “Run gemini --resume to continue” debe actualizarse a deepseek --resume.

Configuración mínima

La configuración persistente vive en ~/.deepseek/settings.json. Los servidores MCP se declaran ahí:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Cierre

La 1.1.0 es la primera versión donde la integración con DeepSeek V4 se comporta como debería: modo de pensamiento estable, métricas de uso reales, branding limpio y un sistema de actualizaciones explícito. A partir de aquí el desarrollo se orienta a soporte de más herramientas MCP y mejoras en el router de modelos.

Reportes de bugs y pull requests en el repositorio:

github.com/sluisr-dev/deepseek-cli