Primeros pasos con Koove CLI: de npm install a tu primer secreto cifrado en 5 minutos

Por qué importa un CLI de gestión de secretos ahora mismo

En la era del código generado por IA, las claves acaban hardcodeadas más a menudo, no menos. Tu asistente de IA pega una API key en un fichero de configuración porque es la forma más rápida de que la demo funcione, y ahí se queda hasta que alguien la encuentra — normalmente en un repositorio público. Si quieres entender bien por qué pasa esto y cómo montar tu flujo de trabajo para evitarlo, lo explicamos con más detalle en /ai-security.

Koove CLI existe para eliminar la tentación de raíz: tu código (y tu asistente de IA) referencia los secretos por nombre, nunca por valor. El valor real vive cifrado, y solo se descifra en dispositivos o backends que han demostrado quiénes son.

Este tutorial de gestor de secretos te lleva de cero a tu primer secreto cifrado en unos cinco minutos. Sin cadenas de certificados, sin paneles que tengas que recorrer a clics — solo terminal.

Paso 1: instalación

npm install -g @koove/cli

Comprueba que se ha instalado bien:

koove --version

Si prefieres no instalarlo de forma global, puedes usar npx para comandos puntuales:

npx @koove/cli set STRIPE_SECRET_KEY sk_live_xxx --env prod

Paso 2: crea tu cuenta e inicia sesión

Necesitas una cuenta de Koove antes de que el CLI pueda hablar con nada. Regístrate en /register — tarda menos de un minuto, sin tarjeta de crédito para el plan gratuito (consulta los límites actuales en /plans).

Una vez tengas cuenta:

koove login

Esto abre una ventana del navegador para autenticarte y luego guarda un token de sesión local en tu máquina. Nada sensible de tu bóveda se cachea localmente — el token solo permite que tu CLI pida blobs cifrados, que igualmente tienen que pasar por el flujo de descifrado.

Paso 3: guarda tu primer secreto

Imagina que estás conectando Stripe en un proyecto de Node. En vez de meter la clave en .env y confiar en que nadie la commitee:

koove set STRIPE_SECRET_KEY sk_live_51J... --env prod

Puedes crear tantos entornos como quieras — dev, staging, prod, ci, lo que encaje con tu pipeline:

koove set STRIPE_SECRET_KEY sk_test_51J... --env dev

Lista lo que tienes guardado (los valores nunca se imprimen, solo nombres y metadatos):

koove list --env prod

NAME                 ENV     UPDATED
STRIPE_SECRET_KEY    prod    2024-06-11 10:32
DATABASE_URL         prod    2024-06-10 18:04

Paso 4: recupéralo

Para obtener el valor de un secreto directamente (útil para depurar o scripts puntuales):

koove get STRIPE_SECRET_KEY --env prod

Lo normal es que no quieras que el valor se imprima en ningún sitio — quieres inyectarlo en el entorno de un proceso en tiempo de ejecución:

koove run --env prod -- node server.js

koove run resuelve todos los secretos que necesita tu app, los descifra en memoria y los pasa como variables de entorno al proceso hijo. Nada toca disco, nada queda en el historial de tu shell.

Paso 5: úsalo desde código

Para servicios backend, el SDK suele ser más limpio que invocar el CLI desde un script. La referencia completa está en /docs/sdk, pero el patrón básico es este:

import { Koove } from "@koove/sdk";

const koove = new Koove({ env: "prod" });

async function getStripeClient() {
  const key = await koove.get("STRIPE_SECRET_KEY");
  return new Stripe(key);
}

El SDK autentica el backend como consumidor verificado (mediante una credencial de servicio que generas una vez) y descifra el secreto localmente después de que el servidor demuestre su identidad. Tu código nunca ve el blob cifrado en bruto, y el backend de Koove nunca ve el valor descifrado.

Qué pasa realmente por debajo

Koove usa cifrado envelope construido sobre primitivas open-source: X25519 para el intercambio de claves, AES-256-GCM para el payload. Cuando ejecutas koove set, el valor se cifra en el cliente antes de salir de tu máquina. El servidor de Koove solo almacena texto cifrado — no tiene ninguna clave que le permita leer tus secretos.

El descifrado solo ocurre en consumidores que han demostrado ser quienes dicen ser:

Clientes móviles se autentican mediante Apple App Attest o Google Play Integrity, más biometría, antes de que se libere ninguna clave.
Servicios backend se autentican con una credencial de servicio asociada a ese backend.

Esto es sustancialmente distinto a guardar secretos en un fichero .env o en una variable de CI que puede leer cualquier proceso de la máquina — pero no es magia. Koove reduce por dónde pueden filtrarse los secretos en claro; no convierte en inofensivo un dispositivo comprometido o una credencial de servicio filtrada. Si un atacante consigue una sesión válida y verificada, obtiene aquello que esa sesión está autorizada a leer — igual que en cualquier sistema de control de acceso.

Vale la pena decir con claridad una limitación honesta: si un secreto ya se ha descifrado y copiado fuera de un entorno comprometido, revocar el acceso en Koove detiene las lecturas futuras — no llega hasta esa copia y la borra de donde ya salió. Si sospechas que un secreto se ha expuesto, rota la clave en el proveedor correspondiente (por ejemplo, genera una nueva clave de Stripe); revocación y rotación son acciones distintas.

Entornos y rotación

Mantén los entornos estrictamente separados. Un error común es compartir una única credencial de prod entre dev y staging "de forma temporal". No lo hagas. Usa:

koove set STRIPE_SECRET_KEY sk_test_xxx --env dev
koove set STRIPE_SECRET_KEY sk_live_xxx --env prod

Cuando rotes una clave en el proveedor (Stripe, AWS, lo que sea), actualiza Koove de inmediato:

koove set STRIPE_SECRET_KEY sk_live_new... --env prod

El texto cifrado antiguo queda superado; los consumidores que piden valores frescos vía koove run o el SDK reciben el nuevo automáticamente.

Cómo conectar tu asistente de IA

Si usas Cursor, Copilot o un agente propio para generar código, dile explícitamente que llame a los secretos por nombre y que nunca pegue valores literales:

koove set NAME value --env prod

Luego, en el código generado, el asistente solo debería escribir process.env.NAME o koove.get("NAME") — nunca la cadena literal. Este es el hábito clave que evita que los secretos acaben en el historial de commits, y es el flujo de trabajo que desarrollamos con más profundidad en /ai-security.

Por dónde seguir

Referencia completa de comandos y SDK: /docs/sdk
Límites de plan y funciones de equipo: /plans
Preguntas frecuentes (acceso offline, compartir en equipo, rotación de claves): /faq

Para cerrar

Cinco minutos te dan un CLI funcionando, un secreto cifrado y un hábito difícil de romper: nombres en el código, valores en Koove. Si estás construyendo algo con herramientas asistidas por IA ahora mismo, merece la pena hacer esto antes del primer commit, no después de la primera filtración. Pasa por /register y ejecuta tu primer koove set.