Guía de la CLI

La CLI de DevSpeak envuelve la API pública para flujos de trabajo desde la terminal. Actualmente apunta a POST /api/v1/translate para la generación completa de documentos y a POST /api/v1/refine para revisiones iterativas. El antiguo comando devspeak optimize sigue disponible, pero solo como alias en desuso de devspeak translate.

Instalación

``bash

npm install -g @devspeak/cli

`bash


npx @devspeak/cli translate "We need a login page that works with Google and saves user data"

> Nota de versión. Esta guía documenta 1.5.1. Las funciones marcadas (1.5.0+) —

> logout, whoami, update, doctor, el aviso pasivo de actualización y el flag global

> --no-color — no están disponibles en 1.4.0 ni en versiones anteriores. Las funciones

> marcadas (1.4.0+) — el comando completion, la ruta de configuración XDG, la validación

> local de flags y el endpoint predeterminado www — no están disponibles en 1.3.0 ni en

> versiones anteriores. En 1.3.0, la configuración vive en ~/.devspeakrc y el endpoint

> predeterminado es el dominio raíz https://devspeak.dev. Actualiza con

> npm install -g @devspeak/cli@latest o devspeak update.

`Mapeo comando-endpoint`

| Comando CLI | Ruta API | Notas |


| ----------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |

| devspeak login | GET /api/v1/health | Solo comprueba conectividad; guarda la configuración de forma local |

| devspeak logout | Ninguna | Elimina la API key almacenada del archivo de configuración local |

| devspeak whoami | Ninguna | Imprime la clave enmascarada, su origen, el endpoint y la ruta de configuración |

| devspeak translate [input] | POST /api/v1/translate | Comando principal. El flag --file adjunta archivos locales como contexto vía attachments[] |

| devspeak optimize [input] | POST /api/v1/translate | Alias en desuso; no llama a POST /api/v1/optimize |

| devspeak refine | POST /api/v1/refine | Envía la salida previa, el feedback y opcionalmente el input original |

| devspeak config show | Ninguna | Solo lee el archivo de configuración local |

| devspeak config set | Ninguna | Solo actualiza el archivo de configuración local |

| devspeak update | Registro de npm | Comprueba registry.npmjs.org en busca de una versión más reciente; --yes la instala |

| devspeak doctor | GET /api/v1/health | Auditoría del entorno: Node, configuración, clave, permisos, salud, versión |

| devspeak completion | Ninguna | Imprime un script de autocompletado para bash, zsh o fish en stdout |

devspeak translate y el alias heredado devspeak optimize serializan el mismo cuerpo de Stage 2 para /api/v1/translate. La CLI no llama a POST /api/v1/optimize.

Si necesitas la optimización léxica de la etapa 1, usa la aplicación web o llama directamente a POST /api/v1/optimize. La CLI no expone un comando para ese endpoint.

`Autenticación`

(1.4.0+) La CLI guarda la configuración en $XDG_CONFIG_HOME/devspeak/config.json, con valor por defecto ~/.config/devspeak/config.json y permisos chmod 600. En 1.3.0 la ruta es ~/.devspeakrc.

Un archivo ~/.devspeakrc preexistente de una versión anterior se sigue leyendo, y se migra a la nueva ubicación la primera vez que se escribe la configuración. El archivo anterior se conserva como ~/.devspeakrc.migrated.

`json


{
  "apiKey": "dsk_live_a1b2c3d4...",
  "endpoint": "https://www.devspeak.dev",
  "defaults": {
    "audience": "Senior Dev",
    "context": "Backend",
    "format": "Technical Spec",
    "tone": 75
  }
}

Prefijos compatibles:

| Prefijo | Significado |


| ----------- | ------------------------------- |

| dsk_live_ | API key de producción |

| dsk_test_ | API key de desarrollo / staging |

| dsk_sess_ | Session key efímera |

devspeak login

`bash


devspeak login

`bash


devspeak login --key dsk_live_a1b2c3d4... --endpoint https://www.devspeak.dev

Comportamiento:

Acepta --key, la variable de entorno DEVSPEAK_API_KEY o pregunta interactivamente.


Falla de inmediato cuando stdin no es un TTY y no se proporcionó una clave, en lugar de bloquearse en el prompt.

Rechaza claves que no empiecen con dsk_.

Verifica conectividad llamando a GET /api/v1/health.

Valida que el endpoint sea una URL http(s) absoluta y elimina una barra final.

Un login correcto imprime (en stderr, para mantener stdout apto para pipes):

`text

Authenticated successfully.


Config saved to /Users/you/.config/devspeak/config.json

devspeak whoami `(1.5.0+)`

Imprime la identidad activa en stdout: API key enmascarada, origen de la clave, endpoint y ruta de configuración.

`bash


devspeak whoami

`text


API key:  dsk_live_a1b2...c3d4
Source:   config file
Endpoint: https://www.devspeak.dev
Config:   /Users/you/.config/devspeak/config.json

--json emite un objeto legible por máquina (authenticated, apiKey enmascarada, keySource, endpoint, configPath).

La variable de entorno DEVSPEAK_API_KEY tiene prioridad sobre la clave almacenada y se reporta como environment.

Cuando no hay clave disponible, whoami imprime Not authenticated. con la indicación de ejecutar devspeak login y sale con código 1.

La clave completa nunca se imprime — tampoco en la salida --json.

devspeak logout `(1.5.0+)`

Elimina la API key almacenada conservando el endpoint y los valores predeterminados de generación.

`bash

devspeak logout

Idempotente: sin clave almacenada reporta No API key stored — nothing to remove. y sale con código 0.

La clave sigue siendo válida en el servidor: logout solo la elimina de la configuración local e indica revocarla en Settings → API Keys.

Cuando DEVSPEAK_API_KEY

 está definida, la CLI advierte que la variable de entorno sigue otorgando acceso y debe eliminarse manualmente — no finge eliminar lo que no puede.

`Comandos de configuración`

devspeak config show

Imprime la configuración actual y enmascara la API key.

`bash

devspeak config show

Ejemplo de salida:

`text


{
  "apiKey": "dsk_live_a1b2...c3d4",
  "endpoint": "https://www.devspeak.dev",
  "defaults": {
    "audience": "Senior Dev",
    "context": "Backend",
    "format": "Technical Spec",
    "tone": 75
  }
}
Config path: /Users/you/.config/devspeak/config.json

El JSON se envía a stdout y la ruta de configuración a stderr, por lo que devspeak config show | jq funciona.

devspeak config set

Claves compatibles:

endpoint

audience

context

format

tone

`bash

devspeak config set audience "Tech Lead"


devspeak config set format "RFC"
devspeak config set tone 90
devspeak config set endpoint "https://www.devspeak.dev"

Los valores se validan contra los mismos conjuntos permitidos que aplica la API, por lo que una audiencia, contexto, formato, tono o endpoint inválido falla localmente y nunca se persiste.

Cada actualización correcta imprime Set = .

devspeak completion `(1.4.0+)`

Imprime un script de autocompletado para bash, zsh o fish en stdout.

`bash


devspeak completion bash >> ~/.bashrc
devspeak completion zsh  > "${fpath[1]}/_devspeak"
devspeak completion fish > ~/.config/fish/completions/devspeak.fish

`Comandos de mantenimiento`

devspeak update `(1.5.0+)`

Comprueba el registro de npm (https://registry.npmjs.org/@devspeak/cli/latest) en busca de una versión más reciente.

`bash


devspeak update        # reporta el estado e imprime el comando exacto de actualización
devspeak update --yes  # instala vía npm install -g @devspeak/cli@

Actualizada → lo confirma y sale con código 0.

Desactualizada → imprime npm install -g @devspeak/cli@; con --yes

 ejecuta la instalación con una versión fijada y revalidada (sin interpolación de shell, nada descargado de la red se ejecuta en un shell).

Registro inaccesible → un mensaje claro de desconexión y código 1, nunca un crash.

`Aviso pasivo de actualización (1.5.0+)`

Como máximo una vez cada 24 horas, un proceso en segundo plano separado refresca la última versión conocida del registro en $XDG_CONFIG_HOME/devspeak/update-check.json. Cuando esa versión en caché es más reciente que la CLI en ejecución, la siguiente invocación imprime una línea en stderr:

`text

Update available: 1.5.0 → 1.6.0. Run devspeak update.

La comprobación solo se ejecuta en un TTY, se omite cuando la variable de entorno CI está definida, nunca bloquea ni hace fallar un comando, y puede desactivarse por completo:

`bash

devspeak doctor `(1.5.0+)`

Auditoría del entorno en un solo paso. Cada comprobación imprime ✓/✗ con una línea de solución accionable en caso de fallo.

`bash


devspeak doctor
devspeak doctor --json

Comprobaciones, en orden:

1. Versión de Node.js ≥ 18


2. El archivo de configuración es JSON válido

3. API key presente y con prefijo dsk_

4. Permisos del archivo de configuración en 0600

5. El endpoint responde a GET /api/v1/health


6. Versión instalada vs la última del registro de npm

Sale con código 0 solo cuando todas las comprobaciones pasan. --json emite { ok, checks: [{ name, ok, detail, fix? }] }.

`Flag global` --no-color `(1.5.0+)`

Fuerza la desactivación del color independientemente de la detección de TTY y de FORCE_COLOR. NO_COLOR y la detección automática sin TTY siguen funcionando como antes.

`bash


devspeak --no-color doctor

`Comandos de traducción`

devspeak translate [input]

Comando principal para la generación completa de la etapa 2 a través de POST /api/v1/translate.

La CLI no envía ningún modelo fijado, así que el router LLM del servidor elige el modelo gestionado según las señales de la solicitud, salvo que primero se resuelva una credencial BYOK almacenada, en cuyo caso tu proveedor atiende la petición.

Opciones

| Flag | Significado | Predeterminado |


| --------------------------- | ------------------------------------------------------------------------ | ---------------- |

| -a, --audience | Audiencia objetivo | Senior Dev |

| -c, --context | Contexto técnico | Backend |

| -f, --format | Formato de salida | Technical Spec |

| -t, --tone | Nivel de detalle 0..100 | 75 |

| -i, --instructions | Instrucciones personalizadas | ninguna |

| --file | Adjunta un archivo local como contexto (PDF, Markdown, TXT — máx. 10 MB) | ninguna |

| -o, --output | Escribir la salida en un archivo | ninguna |

| --json | Imprimir el payload data crudo como JSON | false |

Valores enum

| Opción | Valores |


| ---------- | ----------------------------------------------------------------------------------------- |

| audience | Junior Dev, Senior Dev, Tech Lead, SRE, Data Engineer |

| context | Backend, Frontend, Mobile, Data/ML, DevOps |

| format | Technical Spec, Jira Tickets, API Design, RFC, Data Model, Prompt, Optimize |

Ejemplos:

`bash


devspeak translate "We need user auth with Google SSO"

`bash


cat requirements.txt | devspeak translate --format "Jira Tickets" --output tickets.md

`bash


devspeak translate "Add Redis caching for API responses" \
  --audience "SRE" \
  --context "DevOps" \
  --format "RFC" \
  --tone 90 \
  --instructions "Include monitoring and alerting requirements"

Si no se proporciona input posicional, la CLI lee desde stdin. Si se ejecuta de forma interactiva sin argumento posicional ni datos por tubería, termina con una pista de uso.

Comportamiento de salida:

Sin --output, el Markdown generado se escribe en stdout.

El resumen de metadatos (wordCount, latencyMs, model) se escribe en stderr.

Con --json, la CLI imprime el payload data devuelto por la API, no el envelope completo { success, data }.

Con --output, la CLI escribe el archivo y muestra Written to en stderr antes del resumen de metadatos.

`Adjuntar archivos como contexto (`--file`)`

El flag --file lee un archivo local, lo codifica en base64 y lo envía en el campo attachments del cuerpo de la solicitud POST /api/v1/translate. En el servidor, el contenido de los archivos de texto se decodifica e inyecta como bloque de contexto junto al contexto de workspace enviado al LLM.

Tipos compatibles: .pdf, .md, .mdx, .txt

Límite: 10 MB — validado localmente antes de cualquier llamada de red.

`bash


Adjuntar un PRD en PDF como contexto
devspeak translate "Implementar el flujo de autenticación" \
  --file ./docs/requerimientos.pdf \
  --audience "Tech Lead" \
  --format "Technical Spec" \
  --tone 85

`bash


Adjuntar un runbook Markdown para un RFC de SRE
devspeak translate "Agregar caché Redis para respuestas de API" \
  --audience "SRE" \
  --context "DevOps" \
  --format "RFC" \
  --tone 90 \
  --instructions "Incluir requisitos de monitoreo y alertas" \
  --file ./runbooks/estandares-cache.md

`bash


Combinar entrada por stdin con un archivo adjunto
cat feature-notes.txt | devspeak translate \
  --file ./architecture/current-state.md \
  --format "RFC"

Comportamiento de errores:

Archivo inexistente → la CLI termina mostrando la ruta completa antes de hacer ninguna solicitud de red.


Archivo mayor a 10 MB → la CLI lo rechaza mostrando el tamaño real.
Extensión no compatible → la CLI lista los tipos aceptados.

El nombre y tamaño del archivo adjunto se imprimen en stderr (no contaminan stdout).

> Nota sobre PDFs: los archivos .pdf se codifican en base64 y se envían al modelo como adjunto de documento, por lo que su contenido se lee por completo. La calidad de la extracción depende del PDF: un documento escaneado sin capa de texto incrustada aporta poco contexto util.

devspeak optimize [input]

Alias heredado por compatibilidad. Usa las mismas flags y envía exactamente el mismo cuerpo de petición a POST /api/v1/translate.

`bash

devspeak optimize "We need user auth with Google SSO"

Cuando se usa, la CLI imprime una advertencia de deprecación en stderr:

`text

[DEPRECATED] devspeak optimize is deprecated. Use devspeak translate instead.

`Comando de refinamiento`

devspeak refine

Envuelve POST /api/v1/refine.

Opciones obligatorias

| Flag | Significado |


| ----------------------- | ------------------------------------------------------------------------------------- |

| -p, --previous | Salida previa que se va a refinar. Usa @ruta/al/archivo.md para cargar desde disco. |

| -F, --feedback | Solicitud concreta de cambio |

Flags opcionales

| Flag | Significado | Predeterminado |


| ------------------------ | ------------------------------------------ | ---------------- |

| -r, --original | Texto de entrada original para contexto | "" |

| -a, --audience | Audiencia objetivo | Senior Dev |

| -c, --context | Contexto técnico | Backend |

| -f, --format | Formato de salida | Technical Spec |

| -t, --tone | Nivel de detalle 0..100 | 75 |

| -o, --output | Escribir la salida en un archivo | ninguna |

| --json | Imprimir el payload data crudo como JSON | false |

Ejemplos:

`bash


devspeak refine \
  --previous @spec.md \
  --feedback "Add a section on rate limiting and explicit error codes" \
  --original "We need a login page that works with Google and saves user data"

`bash


devspeak refine \
  --previous "## Technical Specification..." \
  --feedback "Make it more concise" \
  --tone 40 \
  --json

La salida de refine sigue las mismas convenciones de stdout y stderr que translate.

Cuando --previous empieza por @, la CLI carga el archivo desde disco y termina con error si el archivo no existe.

`Planes y cuota gratuita de API`

Todos los planes pueden crear una clave API en Settings → API Keys. En GRATIS y VIBECODER tienes una clave y 50 solicitudes a la API por mes calendario (UTC) con el modelo predeterminado de DevSpeak, y el límite por hora del plan GRATIS sigue aplicando. Cada llamada a translate u optimize cuenta como una solicitud; una solicitud que falla no cuenta. DEVELOPER y superiores no tienen límite mensual de solicitudes, admiten hasta 3 claves (ilimitadas en ENTERPRISE) y pueden elegir cualquier modelo gestionado con el campo managedModel de la API (el servidor MCP lo expone como argumento).

`Errores y notas operativas`

| Mensaje | Significado |


| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |

| No API key configured. Run \devspeak login\ first. | Faltan credenciales locales |

| Invalid API key format. Keys start with dsk_live_ or dsk_test_ | Falló la validación del prefijo |

| Cannot reach API at ... | Falló la comprobación de conectividad con el endpoint |

| Provide input text as argument or pipe via stdin | translate se ejecutó de forma interactiva sin argumento posicional ni datos por tubería |

| Input must be at least 10 characters | El input de translate está por debajo del mínimo del servidor |

| File not found: ... | translate --file apunta a un archivo inexistente |

| Previous output must not be empty | refine --previous se resolvió a un valor vacío |

| Feedback must not be empty | refine --feedback falta o está vacío |

| Free API allowance used: ... | Se agotaron las 50 solicitudes mensuales de GRATIS o VIBECODER; el mensaje indica la fecha de reinicio y el enlace para mejorar el plan |

| The free API allowance runs on DevSpeak's default model ... | Se fijó un managedModel` en GRATIS o VIBECODER (API o MCP); quítalo o mejora a DEVELOPER |

Seguridad

La CLI nunca registra API keys completas.

La configuración almacenada usa permisos solo para el propietario.

El tráfico de producción usa HTTPS.

Las API keys pueden revocarse desde el panel de DevSpeak en cualquier momento.

Para ver los contratos REST subyacentes, consulta [/docs/api-reference](/docs/api-reference).

Guía de la CLI

Instalación

Mapeo comando-endpoint

Autenticación

devspeak login

devspeak whoami (1.5.0+)

devspeak logout (1.5.0+)

Comandos de configuración

devspeak config show

devspeak config set

devspeak completion (1.4.0+)

Comandos de mantenimiento

devspeak update (1.5.0+)

Aviso pasivo de actualización (1.5.0+)

devspeak doctor (1.5.0+)

Flag global --no-color (1.5.0+)

Comandos de traducción

devspeak translate [input]

Adjuntar archivos como contexto (--file)

Adjuntar un PRD en PDF como contexto

Adjuntar un runbook Markdown para un RFC de SRE

Combinar entrada por stdin con un archivo adjunto

devspeak optimize [input]

Comando de refinamiento

devspeak refine

Planes y cuota gratuita de API

Errores y notas operativas

Seguridad

`Mapeo comando-endpoint`

`Autenticación`

devspeak whoami `(1.5.0+)`

devspeak logout `(1.5.0+)`

`Comandos de configuración`

devspeak completion `(1.4.0+)`

`Comandos de mantenimiento`

devspeak update `(1.5.0+)`

`Aviso pasivo de actualización (1.5.0+)`

devspeak doctor `(1.5.0+)`

`Flag global` --no-color `(1.5.0+)`

`Comandos de traducción`

`Adjuntar archivos como contexto (`--file`)`

`Comando de refinamiento`

`Planes y cuota gratuita de API`

`Errores y notas operativas`