Referencia de comandos
Todos los comandos se escriben konsolity <comando> [opciones]. konsolity help y konsolity <comando> --help muestran la ayuda en el idioma del sistema. Las salidas en --json son estables y están pensadas para scripts; nunca contienen secretos.
Visión general
| Comando | Ámbito necesario | Función |
|---|---|---|
login |
Activar la máquina (Activar una máquina) | |
setup-token |
Crear un token de larga duración para la CI y los contenedores | |
status |
Cuenta, máquina, alcance, caducidad, estado | |
hosts |
hosts |
Hosts del alcance |
run |
hosts, acceso completo |
Ejecutar un comando en un host |
snippet list |
snippets |
Fragmentos del alcance |
snippet run |
snippets + hosts, acceso completo |
Lanzar un fragmento en un host |
sessions |
sessions |
Sesiones CLI en curso en la cuenta |
sessions end |
sessions |
Terminar una sesión |
mcp |
mcp |
Servidor MCP local para Claude Code (MCP local) |
serve |
mcp + integración con Claude |
Atender las solicitudes del conector Claude (Servicio) |
service install |
Instalar serve como servicio del sistema |
|
rotate |
Renovar el token de la máquina | |
policy |
Mostrar el alcance y las reglas aplicadas | |
logout |
Revocar la máquina y borrarlo todo localmente | |
version |
Versión, sistema, arquitectura | |
update |
Actualizar el binario (firma verificada) |
Un comando fuera del alcance responde scope_denied; un comando en solo lectura responde read_only.
login
konsolity login [--name <name>] [--scopes hosts,snippets,sessions,mcp] [--read-only]
Activa la máquina con un código validado desde tu cuenta. Detalles y ejemplos: Activar una máquina.
setup-token
konsolity setup-token [--name <name>] [--scopes <list>] [--read-only]
Mismo flujo que login, pero muestra una sola vez un token ksetup_... en lugar de guardar nada. Después, pásalo mediante KONSOLITY_TOKEN. Consulta setup-token.
status
konsolity status [--json]
Muestra la cuenta, el nombre y el tipo de la máquina, el alcance (ámbitos, solo lectura o completo), la caducidad, la antigüedad del token, el estado del servidor y el número de hosts accesibles.
$ konsolity status
Account anthony@example.com
Machine build-01 (machine)
Scope hosts, snippets, mcp · full access
Expires on 2027-02-08
Token renewed 3 h ago
Server api.konsolity.com · reachable
Hosts 4
hosts
konsolity hosts [--json]
Enumera los hosts del alcance: etiqueta, dirección, usuario, grupo. Nunca una contraseña ni una clave.
$ konsolity hosts
web-01 203.0.113.10 deploy Production
web-02 203.0.113.11 deploy Production
db-01 10.0.0.5 admin Data
run
konsolity run <host> [--timeout <seconds>] [--json] -- <command>
Ejecuta un comando en un host por SSH: conexión corta dedicada, clave de host fijada obligatoria, salida en directo en el terminal, código de retorno del comando remoto transmitido como código de salida de konsolity. <host> es la etiqueta del host o su identificador. Todo lo que sigue a -- es el comando, tal cual.
| Opción | Función |
|---|---|
--timeout <seconds> |
Tiempo límite del comando, limitado por el tiempo máximo de la máquina (60 s por defecto). |
--json |
Una única salida JSON al final: exit_code, stdout, stderr, duration_ms. |
$ konsolity run web-01 -- systemctl status nginx
● nginx.service - A high performance web server
Active: active (running) since Mon 2026-11-09 08:12:44 UTC
$ echo $?
0
Antes de lanzar el comando, la CLI comprueba el alcance y las reglas y anota el inicio en el registro: si esa escritura falla, el comando no se lanza. Un comando destructivo espera tu confirmación:
$ konsolity run db-01 -- "mysql -e 'DROP TABLE sessions_old'"
Destructive command: confirmation requested in the Konsolity app.
https://app.konsolity.com/cli/confirm/9f3c2a71
Waiting (5 min at most)...
Allowed. Running.
snippet
konsolity snippet list [--json]
konsolity snippet run <snippet> <host> [--timeout <seconds>] [--json]
snippet list muestra los fragmentos del alcance (nombre, grupo). snippet run lanza un fragmento, tal como está guardado en la bóveda, en un host del alcance. <snippet> es su nombre o su identificador. Se aplican las mismas reglas que con run: registro, confirmación si el contenido es destructivo, código de retorno transmitido.
$ konsolity snippet run "Clear the cache" web-01
Cache cleared.
sessions
konsolity sessions [--follow] [--json]
konsolity sessions end <id>
Enumera las sesiones CLI en curso en la cuenta: máquina, comando, desde cuándo. --follow mantiene la lista abierta y la actualiza. sessions end <id> termina una sesión: el comando correspondiente se detiene en menos de 5 segundos.
$ konsolity sessions
a1b2c3 build-01 run web-01: tail -f /var/log/nginx/access.log for 12 min
d4e5f6 laptop mcp for 1 h
$ konsolity sessions end a1b2c3
mcp
konsolity mcp
Lanza un servidor MCP stdio local, para conectarlo a Claude Code:
claude mcp add konsolity -- konsolity mcp
Detalles de las herramientas y de los límites: MCP local para Claude Code.
serve
konsolity serve
Atiende las solicitudes del conector Claude de la cuenta (claude.ai, app de Claude) igual que la app de escritorio, pero sin interfaz, dentro de los límites del alcance y de las reglas. Requiere el ámbito mcp y la integración con Claude del plan Studio. Se queda en primer plano; en un servidor, instálalo como servicio.
service install
sudo konsolity service install
Instala konsolity serve como servicio del sistema (systemd, launchd o tarea programada de Windows). Consulta Servicio y almacenamiento.
rotate
konsolity rotate
Fuerza la renovación del token de la máquina. En cualquier caso, la rotación es automática cada 24 horas. La clave de máquina no cambia.
policy
konsolity policy [--json]
Muestra lo que la máquina aplica realmente: ámbitos, solo lectura o completo, hosts, fragmentos, reglas de comandos, «Cualquier comando», tiempo máximo.
logout
konsolity logout
Revoca la máquina en el servidor y después borra el token, la clave de máquina y las copias locales. Para volver a usarla, hace falta una nueva activación.
version
konsolity version
Muestra la versión, el sistema y la arquitectura.
update
konsolity update
Descarga la última versión, comprueba su suma SHA-256 y la firma Ed25519 del manifiesto y después sustituye el binario. Si se instaló con apt, dnf o Homebrew, la CLI te remite a ese gestor.
Variables de entorno
| Variable | Función |
|---|---|
KONSOLITY_TOKEN |
Token de larga duración ksetup_... (CI, contenedores). Sustituye a los secretos guardados. |
Códigos de salida
| Código | Significado |
|---|---|
0 |
Éxito. |
| código remoto | run y snippet run salen con el código de retorno del comando remoto (por ejemplo, 1 si el comando ha fallado en el host). |
1 |
Error general: máquina no activada, red inaccesible, host o snippet no encontrado, línea de registro no escrita (la orden no se lanza entonces), secretos locales ilegibles. |
2 |
Error de uso: opción desconocida, orden ausente o demasiado larga (4000 caracteres como máximo), KONSOLITY_TOKEN no válido. |
3 |
Rechazo: dominio ausente del alcance (scope_denied), máquina de solo lectura (read_only), ninguna regla coincide (denied), reglas ausentes (policy_missing), plan requerido (plan_required) o activación rechazada. |
4 |
Orden destructiva no confirmada: rechazada en la app o la consola, o sin respuesta en 5 minutos. No se ha lanzado. |
77 |
Máquina revocada, caducada o usada desde otro ordenador (huella diferente), o sesión terminada desde la app o la consola: las conexiones se cortan y el comando se detiene. Salvo en un simple fin de sesión, los secretos locales también se borran. |