Referencia de comandos

Actualizado el 10 de noviembre de 2026

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.