Riferimento dei comandi

Aggiornato il 10 novembre 2026

Ogni comando si scrive konsolity <command> [options]. konsolity help e konsolity <command> --help mostrano la guida nella lingua del sistema. Gli output --json sono stabili e pensati per gli script; non contengono mai un segreto.

Panoramica

Comando Dominio richiesto Ruolo
login Attiva la macchina (Attivare una macchina)
setup-token Crea un token di lunga durata per la CI e i container
status Account, macchina, ambito, scadenza, stato
hosts hosts Host nell'ambito
run hosts, accesso completo Esegue un comando su un host
snippet list snippets Snippet nell'ambito
snippet run snippets + hosts, accesso completo Esegue uno snippet su un host
sessions sessions Sessioni CLI in corso sull'account
sessions end sessions Termina una sessione
mcp mcp Server MCP locale per Claude Code (MCP locale)
serve mcp + integrazione Claude Gestisce le richieste del connettore Claude (Servizio)
service install Installa serve come servizio di sistema
rotate Rinnova il token della macchina
policy Mostra l'ambito e le regole applicate
logout Revoca la macchina e cancella tutto in locale
version Versione, sistema, architettura
update Aggiorna il binario (firma verificata)

Un comando fuori dall'ambito risponde scope_denied; un comando su una macchina in sola lettura risponde read_only.

login

konsolity login [--name <name>] [--scopes hosts,snippets,sessions,mcp] [--read-only]

Attiva la macchina con un codice approvato dal tuo account. Dettagli ed esempi: Attivare una macchina.

setup-token

konsolity setup-token [--name <name>] [--scopes <list>] [--read-only]

Stesso flusso di login, ma mostra una sola volta un token ksetup_... invece di salvare qualcosa. Forniscilo poi tramite KONSOLITY_TOKEN. Vedi setup-token.

status

konsolity status [--json]

Mostra l'account, il nome e il tipo della macchina, l'ambito (domini, sola lettura o accesso completo), la scadenza, l'età del token, lo stato del server e il numero di host raggiungibili.

$ 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]

Elenca gli host nell'ambito: etichetta, indirizzo, utente, gruppo. Mai una password o una chiave.

$ 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>

Esegue un comando su un host via SSH: connessione dedicata breve, chiave host fissata obbligatoria, output in tempo reale nel terminale, codice di uscita del comando remoto restituito come codice di uscita di konsolity. <host> è l'etichetta dell'host o il suo identificativo. Tutto ciò che segue -- è il comando, così com'è.

Opzione Ruolo
--timeout <seconds> Timeout del comando, limitato dal timeout massimo della macchina (60 s per impostazione predefinita).
--json Un unico output JSON alla fine: 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

Prima di eseguire il comando, la CLI verifica l'ambito e le regole, poi scrive l'avvio nel registro: se questa scrittura non riesce, il comando non viene eseguito. Un comando distruttivo attende la tua conferma:

$ 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 mostra gli snippet nell'ambito (nome, gruppo). snippet run esegue uno snippet, così come è salvato nella cassaforte, su un host nell'ambito. <snippet> è il suo nome o il suo identificativo. Valgono le stesse regole di run: registro, conferma se il contenuto è distruttivo, codice di uscita restituito.

$ konsolity snippet run "Clear the cache" web-01
Cache cleared.

sessions

konsolity sessions [--follow] [--json]
konsolity sessions end <id>

Elenca le sessioni CLI in corso sull'account: macchina, comando, da quanto tempo. --follow mantiene l'elenco aperto e lo aggiorna. sessions end <id> termina una sessione: il comando corrispondente viene interrotto in meno di 5 secondi.

$ 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

Avvia un server MCP locale stdio, da collegare in Claude Code:

claude mcp add konsolity -- konsolity mcp

Dettagli sugli strumenti e sui limiti: MCP locale per Claude Code.

serve

konsolity serve

Gestisce le richieste del connettore Claude dell'account (claude.ai, app Claude) come fa l'app desktop, ma senza interfaccia, entro l'ambito e le regole. Richiede il dominio mcp e l'integrazione Claude del piano Studio. Resta in primo piano; su un server, installalo come servizio.

service install

sudo konsolity service install

Installa konsolity serve come servizio di sistema (systemd, launchd o un'attività pianificata di Windows). Vedi Servizio e archiviazione.

rotate

konsolity rotate

Forza il rinnovo del token della macchina. La rotazione è comunque automatica ogni 24 ore. La chiave della macchina non cambia.

policy

konsolity policy [--json]

Mostra cosa applica davvero la macchina: domini, sola lettura o accesso completo, host, snippet, regole dei comandi, «Qualsiasi comando», timeout massimo.

logout

konsolity logout

Revoca la macchina sul server, poi cancella il token, la chiave della macchina e le copie locali. Per usare di nuovo la macchina serve una nuova attivazione.

version

konsolity version

Mostra la versione, il sistema e l'architettura.

update

konsolity update

Scarica l'ultima versione, verifica il suo hash SHA-256 e la firma Ed25519 del manifesto, poi sostituisce il binario. Se è stata installata con apt, dnf o Homebrew, la CLI ti rimanda a quel gestore.

Variabili d'ambiente

Variabile Ruolo
KONSOLITY_TOKEN Token di lunga durata ksetup_... (CI, container). Sostituisce i segreti salvati.

Codici di uscita

Codice Significato
0 Successo.
codice remoto run e snippet run terminano con il codice di uscita del comando remoto (ad esempio 1 se il comando non è riuscito sull'host).
1 Errore generico: macchina non attivata, rete irraggiungibile, host o snippet non trovato, riga del registro non scritta (il comando allora non viene avviato), segreti locali illeggibili.
2 Errore d'uso: opzione sconosciuta, comando mancante o troppo lungo (al massimo 4.000 caratteri), KONSOLITY_TOKEN non valido.
3 Rifiuto: dominio assente dall'ambito (scope_denied), macchina in sola lettura (read_only), nessuna regola corrisponde (denied), regole assenti (policy_missing), piano richiesto (plan_required) o attivazione rifiutata.
4 Comando distruttivo non confermato: rifiutato nell'app o nella console, o senza risposta entro 5 minuti. Non è stato avviato.
77 Macchina revocata, scaduta o usata da un altro computer (impronta diversa), oppure sessione terminata dall'app o dalla console: le connessioni vengono interrotte e il comando fermato. Salvo nel caso di una semplice fine della sessione, anche i segreti locali vengono cancellati.