Este es el mapa de la CLI de kovra. Cada comando pasa por la misma
decisión de política; ejecutar kovra <command> --help para ver sus
flags y argumentos exactos.
| Comando |
Qué hace |
kovra init |
Inicializa el registro de vaults y la master key. Crea una clave solo cuando el keyring no tiene ninguna; sobre una bóveda que ya guarda registros sellados pide --force y su aprobación. |
kovra setup |
Incorpora el repo actual: asegura el vault, registra el servidor MCP en .mcp.json, inserta el bloque de convenciones en CLAUDE.md, instala los hooks del gate de credenciales en .claude/settings.local.json (las reglas que deniegan Read, en .claude/settings.json) y registra kovrad al iniciar sesión (macOS). --dry-run muestra los cambios sin escribirlos. |
kovrad es el servicio de kovra por usuario; ejecuta el gate de credenciales. En macOS arranca al iniciar sesión y aparece como kovrad en Ajustes → General → Ítems de inicio → Permitir en segundo plano. Si lo apaga ahí, no arranca al iniciar sesión y kovra lo arranca solo cuando lo necesita, sin reiniciarlo si se cae; kovra daemon status y kovra doctor se lo recuerdan y distinguen ese interruptor de un registro que falló, que kovra daemon install repara.
| Comando |
Qué hace |
kovra daemon status |
Muestra si kovrad está corriendo: pid, versión, tiempo activo, conexiones y los contadores del gate. |
kovra daemon start |
Arranca kovrad si no está corriendo (y reinicia uno de otra versión). |
kovra daemon stop |
Detiene kovrad. |
kovra daemon install |
Registra kovrad para que arranque al iniciar sesión y se reinicie si se cae (macOS); termina cuando kovrad responde. |
kovra daemon uninstall |
Detiene kovrad y quita ese registro; desde entonces kovra setup lo deja apagado hasta kovra daemon install. |
| Comando |
Qué hace |
kovra add <coord> |
Crea un secreto (valor por prompt oculto o --stdin; nunca por argv). Crear uno en la bóveda de un proyecto (--project) sobre un secreto global crítico pide su aprobación, igual que add, set, generate, keygen, import, intake fulfill y unpack. --description escribe la nota de uso que leen los agentes (hasta 500 caracteres); --mint-only marca una credencial maestra que solo debe acuñar tokens hijos con alcance acotado (literales y referencias). |
kovra set <coord> |
Actualiza el valor de un secreto y conserva su nota y su marca mint-only. Sobrescribir uno high o inject-only pide su aprobación. |
kovra edit <coord> |
Edita metadatos (sensibilidad / descripción / referencia / --mint-only true|false); bajar la sensibilidad es un downgrade protegido. En un secreto crítico, una sola edición no puede cambiar a la vez la sensibilidad y la referencia. La CLI es el único lugar donde se desmarca un secreto mint-only o se cambia su nota; un agente solo puede marcarlo. |
kovra rm <coord> |
Elimina un secreto. Uno high o inject-only pide su aprobación (Touch ID, o la contraseña de su sesión). |
kovra list |
Lista secretos — solo metadatos, nunca valores. Los valores high, inject-only y de prod no muestran fingerprint (—). El modo muestra mint-only en un secreto marcado, y la columna de nota su nota de uso. |
kovra show <coord> |
Revela un valor a stdout (high requiere bioProve; inject-only nunca). Un secreto mint-only viene con el aviso de kovra en stderr. |
kovra generate <coord> |
Genera un valor aleatorio del lado del servidor; nunca se imprime. |
kovra import <coord> --from op://… |
Copia un valor de 1Password al vault como un literal. |
El flujo iniciado por el agente: un agente (o la persona) encola una solicitud para crear un secreto —
nombrando solo la coordenada, nunca un valor — y un humano la cumple por fuera de banda, de modo que el
valor nunca pasa por el contexto del agente. Ver kovra sobre MCP.
| Comando |
Qué hace |
kovra intake request <coord> |
Encola una solicitud para crear un secreto (--sensitivity, --description; sin valor aquí). |
kovra intake list |
Lista las solicitudes de creación de secretos pendientes. |
kovra intake fulfill <id> |
Provee el valor para una solicitud y la sella (--stdin / --clipboard / --window; crear un secreto high o prod pide confirmación). Sobre un secreto que ya existe, lo rota y siempre pide su aprobación. |
kovra intake cancel <id> |
Descarta una solicitud pendiente sin cumplirla. |
En macOS, la app de barra de menú kovra-menulet lista las solicitudes pendientes y abre la ventana
nativa de cumplimiento.
| Comando |
Qué hace |
kovra mcp |
Sirve el servidor MCP de kovra por stdio. Su agente lo inicia desde .mcp.json, que escribe kovra setup; no se ejecuta a mano. Scope desde KOVRA_MCP_OPERATIONS, KOVRA_MCP_ENVIRONMENTS y KOVRA_MCP_PROJECTS. Vea kovra por MCP. |
| Comando |
Qué hace |
kovra run --env <e> -- <cmd> |
Resuelve un .env.refs y ejecuta un comando con los valores inyectados en el proceso hijo. --allow agrega un ejecutable (por su ruta resuelta) a la allowlist para high/prod en esa ejecución, con su aprobación — que se pide solo cuando la ejecución de verdad entrega un valor así. Una ejecución que entrega high/prod recibe un entorno saneado (PATH fijo, sin variables que cargan código). Una ejecución que inyecta un secreto mint-only escribe un aviso en el stderr de kovra — la coordenada, el consejo de kovra y la nota — antes de lanzar el hijo (también con --stdio), y se ejecuta igual. |
kovra allow add / rm / list |
Administra la allowlist de ejecutables — los programas revisados que pueden recibir un valor high/prod. Está sellada con la clave del vault, así que solo kovra la escribe; add pide su aprobación. Cada entrada fija el contenido del programa (una edición lo saca de la lista; list lo marca changed since it was approved); se rechazan los intérpretes y lanzadores genéricos (sh, bash, env, python, node, make, npm, docker, …). |
kovra run --stdio -- <cmd> |
Igual, pero hereda stdin/stdout/stderr en el hijo (alias --interactive) — necesario para envolver procesos interactivos y servidores MCP de stdio. La salida no se captura, así que no hay enmascarado; el secreto igual se inyecta solo por el entorno y los gates de high/prod siguen aplicando. |
| Comando |
Qué hace |
kovra code <coord> |
Imprime el código TOTP actual (nunca la semilla). Se controla como un reveal: un enrolamiento inject-only nunca muestra un código, y un código de prod pedido desde la sesión de un agente se rechaza (I14); desde su propia shell pide su aprobación. |
kovra keygen <coord> |
Genera y custodia un keypair asimétrico (la mitad privada nunca en disco). |
kovra pubkey <coord> |
Imprime la clave pública OpenSSH de un keypair (gratis). |
kovra sign <coord> [archivo] |
Firma un archivo, o stdin, con la clave privada; la firma va a stdout. Una clave high, inject-only o de prod pide su aprobación, y la aprobación muestra el SHA-256 de los datos firmados y, en la Mac, el documento mismo (vea Qué muestra la aprobación de una firma). --reason "<texto>" indica para qué es la firma, en una línea de 200 caracteres como máximo; la aprobación lo muestra como texto de quien pide, que kovra no verifica, y la auditoría lo registra. Un motivo vacío, más largo, o con un salto de línea, un carácter de control, de formato, bidi, combinante o invisible, o un espacio que no sea el espacio común se rechaza con código de salida 2, antes de pedir nada. |
kovra verify <coord> [archivo] |
Verifica una firma (--signature <archivo>) con la clave pública, también la de una entrada solo-pública (gratis). |
kovra encrypt / decrypt |
Cifra hacia / descifra con un keypair ed25519. |
kovra ssh-add <coord> |
Carga una clave custodiada en el ssh-agent en ejecución, solo en memoria. Rechaza las claves high, inject-only y de prod — esas firman solo a través de kovra ssh-agent. |
kovra ssh-agent |
Ejecuta kovra como un ssh-agent gobernado (firma en memoria; high/prod confirman por cada firma, y el diálogo indica el proceso que la pide y qué se firma). |
| Comando |
Qué hace |
kovra add <coord> --reference azure-kv://… |
Almacena un puntero a Azure Key Vault. |
kovra add <coord> --reference aws-sm://… |
Almacena un puntero a AWS Secrets Manager. |
Las referencias se resuelven en tiempo de ejecución bajo la propia identidad. Ver
Referencias cloud.
| Comando |
Qué hace |
kovra preflight <operación> … |
Responde, antes de que una operación se ejecute, si le pediría aprobación, dónde (la Mac, el teléfono vinculado, o solo el teléfono por SSH) y por qué. Nunca pregunta, nunca imprime un valor y nunca contacta al teléfono; --json imprime los mismos campos. Vea Preflight. kovra preflight sign <coord> --reason "<texto>" revisa el motivo como lo hace kovra sign y lo rechaza de la misma forma (código de salida 2). |
| Comando |
Qué hace |
kovra phone pair |
Vincula la app kovra Mobile de su iPhone (próximamente, todavía no publicada): imprime un QR y, cuando el teléfono responde, el código de 6 dígitos que comparten ambas pantallas, y conserva la vinculación cuando usted la aprueba en la Mac. --relay <url> elige otro relay. |
kovra phone status |
Muestra el teléfono vinculado, su relay y si las notificaciones están activas o silenciadas. |
kovra phone forget |
Olvida el teléfono vinculado, con aprobación en la Mac. |
Vea Aprobar desde su iPhone.
| Comando |
Qué hace |
kovra license status |
Muestra la licencia: estado, plan, arrendamiento y gracia, y si las actualizaciones están permitidas. --json para la app de la barra de menús. |
kovra license activate |
Activa esta Mac con el código que le envió Kaeus (prompt oculto, o --stdin; nunca un argumento). |
kovra license refresh |
Renueva la licencia ahora (kovrad la renueva por su cuenta). |
kovra license deactivate |
Libera el cupo de esta Mac en la licencia (activarla de nuevo necesita un código nuevo); se aprueba solo en esta Mac. |
Una licencia nunca le impide llegar a sus secretos; solo gobierna las actualizaciones. Vea La licencia Free.
| Comando |
Qué hace |
kovra confirm <text> |
Solicita una confirmación humana atendida (exit 0 si se aprueba) — para que un host/app gobierne su propia acción. La aprobación presenta el texto como del programa que llama: A program — not kovra — asks you to approve. |
kovra approve [id] |
Builds de desarrollo y plataformas distintas de macOS: aprueba/deniega un pedido del broker de archivos. En una Mac toda aprobación es en la ventana de revisión de kovra, y un agente no puede aprobar: dentro de una sesión de Claude Code se niega. |
| Comando |
Qué hace |
kovra ui |
Levanta la UI de administración loopback bajo demanda. En macOS se abre por defecto en una ventana nativa; --browser la abre en cambio en el navegador del sistema (--no-open también implica el modo navegador y solo imprime la URL; rechazado en macOS, donde la URL impresa nunca lleva el token de sesión); --window fuerza la ventana nativa; --persistent la mantiene levantada y la bloquea al quedar inactiva en lugar de apagarse. |
| Comando |
Qué hace |
kovra scaffold |
Escanea el código fuente en busca de referencias a variables de entorno y propone un .env.refs (lee solo nombres, nunca valores). |
kovra doctor (lint) |
Valida la configuración de secretos de un proyecto; solo coordenadas + estado, nunca un valor. Sale con un código distinto de cero ante un hallazgo grave. Sin ./.env.refs no verifica ningún contrato, imprime sus notas sobre esta Mac (PATH, kovrad, notificaciones, licencia) y sale con 0; con --refs <archivo>, un archivo que falta es un error, así que un hook o un paso de CI que deba validar el contrato pasa --refs. |
kovra hooks |
Administra los git hooks que mantienen los secretos fuera de los commits. |
kovra audit |
Consulta el registro de auditoría — coordenadas, fingerprints truncados, timestamps, origen; nunca un valor. |
kovra key export / import |
Respalda / restaura la master key del vault (recuperación ante desastres). export se aprueba solo con biometría cuando la Mac tiene Touch ID; import restaura solo una clave que abre los registros de la bóveda. |
