Tutorial sobre el paquete npm @devspeak/cli: instalación global, autenticación con clave de API mediante devspeak login, traducción de texto desde argumentos o stdin, adjuntar contexto local en PDF y Markdown con --file, y cómo integrar la CLI en un pipeline de CI usando la variable de entorno DEVSPEAK_API_KEY.

Automatiza Especificaciones con la CLI de DevSpeak

La CLI de DevSpeak expone el mismo motor de traducción que la aplicación web, lo que la hace utilizable desde una terminal, un script de shell o un trabajo de CI. Este tutorial cubre desde la instalación hasta un paso de CI funcionando.

Lo que Aprenderás

  • Instalar y autenticar la CLI
  • Traducir texto desde argumentos, stdin y archivos locales
  • Ejecutar la CLI de forma no interactiva en CI

    • Requisitos Previos

  • Node.js 18 o superior
  • Una clave de API de DevSpeak desde Ajustes de la Cuenta → Credenciales. Todos los planes pueden crear una: GRATIS y VIBECODER incluyen una clave y 50 solicitudes a la API al mes con el modelo predeterminado; DEVELOPER y superiores no tienen límite mensual de solicitudes

    • Tiempo Estimado

    ~8 minutos

    Paso 1 — Instala

    ``bash

    npm install -g @devspeak/cli

    `

    Verifica la instalación:

    `bash

    devspeak --version

    `

    Paso 2 — Autentícate

    `bash

    devspeak login

    `

    La clave se escribe en $XDG_CONFIG_HOME/devspeak/config.json con permisos 600. Confirma que quedó registrada:

    `bash

    devspeak whoami

    `

    La salida enmascara la clave. Nunca se imprime completa, lo que hace que whoami sea seguro de ejecutar en una terminal compartida.

    Punto de Control

    En este punto deberías tener:

  • [ ] devspeak --version mostrando un número de versión

  • [ ] devspeak whoami reportando una clave enmascarada y un endpoint

    • Si whoami falla, ejecuta devspeak doctor para una auditoría completa del entorno.

    Paso 3 — Traduce

    Hay tres vías de entrada disponibles. Las tres llegan a POST /api/v1/translate.

    `bash

    Argumento posicional

    devspeak translate "Users should be able to export their data as CSV"

    Canalizado desde stdin

    cat notes.txt | devspeak translate --format "Jira Tickets"

    Con contexto de archivo local

    devspeak translate "Implement the auth flow" --file ./docs/prd.pdf

    `

    --file acepta PDF, Markdown y texto plano. Cada archivo puede pesar hasta 10 MiB, pero una petición lleva como máximo unos 3,1 MB de adjuntos en total, y ese total es el límite con el que realmente te vas a topar. Desde la versión 1.5.2, la CLI comprueba localmente, antes de cualquier llamada de red, que el archivo no esté vacío, sea de un tipo admitido y no supere ese total de 3,1 MB, así que esos fallos son inmediatos. Las versiones anteriores solo comprobaban 10 MB, así que un archivo más grande pasaba y después la API lo rechazaba. Si devspeak --version muestra una versión anterior a la 1.5.2, actualiza con npm install -g @devspeak/cli.

    Paso 4 — Ejecútala en CI

    devspeak login es interactivo y se quedará colgado en un runner de CI. Usa la variable de entorno en su lugar: tiene precedencia sobre cualquier clave almacenada.

    `yaml

  • name: Generate specification

    • env:

    DEVSPEAK_API_KEY: ${{ secrets.DEVSPEAK_API_KEY }}

    run: |

    devspeak translate "$(cat request.txt)" \

    --audience "Senior Dev" \

    --format "Technical Spec" > spec.md

    `

    Como los documentos van a stdout y los diagnósticos a stderr, la redirección anterior captura únicamente la especificación.

    Solución de Problemas

    command not found: devspeak

    El directorio bin global de npm no está en tu PATH. Ejecuta npm prefix -g, agrega su subdirectorio bin a tu PATH, o invoca la CLI con npx @devspeak/cli. command -v devspeak muestra qué binario resuelve tu shell.

    401 Unauthorized en CI pero no en local

    El runner está leyendo una clave distinta. DEVSPEAK_API_KEY tiene precedencia sobre el archivo de configuración, así que verifica que el secreto esté expuesto al paso y no solo al workflow.

    Valor inválido para --audience

    La audiencia, el contexto, el formato y el tono se validan localmente contra los mismos enums que aplica la API. Ejecuta devspeak translate --help para ver los valores aceptados.

    Resumen

    Has aprendido a:

  • Instalar y autenticar la CLI

  • Traducir desde argumentos, stdin y archivos locales
  • Invocar la CLI de forma no interactiva desde CI

    • Siguientes Pasos

  • Lee la [referencia de la API](/docs/api-reference) para acceso HTTP directo
  • Añade devspeak doctor --json` como comprobación previa del pipeline