Riferimento dei comandi
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. |