Befehlsreferenz
Jeder Befehl wird konsolity <command> [options] geschrieben. konsolity help und konsolity <command> --help zeigen die Hilfe in der Sprache des Systems an. Die --json-Ausgaben sind stabil und für Skripte gedacht; sie enthalten nie ein Geheimnis.
Überblick
| Befehl | Erforderliche Domäne | Funktion |
|---|---|---|
login |
Die Maschine aktivieren (Eine Maschine aktivieren) | |
setup-token |
Ein langlebiges Token für CI und Container erstellen | |
status |
Konto, Maschine, Bereich, Ablaufzeit, Status | |
hosts |
hosts |
Hosts im Bereich |
run |
hosts, voller Zugriff |
Einen Befehl auf einem Host ausführen |
snippet list |
snippets |
Snippets im Bereich |
snippet run |
snippets + hosts, voller Zugriff |
Ein Snippet auf einem Host ausführen |
sessions |
sessions |
Laufende CLI-Sitzungen des Kontos |
sessions end |
sessions |
Eine Sitzung beenden |
mcp |
mcp |
Lokaler MCP-Server für Claude Code (Lokaler MCP) |
serve |
mcp + Claude-Integration |
Die Anfragen des Claude-Connectors bearbeiten (Dienst) |
service install |
serve als Systemdienst installieren |
|
rotate |
Das Token der Maschine erneuern | |
policy |
Den angewendeten Bereich und die Regeln anzeigen | |
logout |
Die Maschine widerrufen und lokal alles löschen | |
version |
Version, System, Architektur | |
update |
Das Binary aktualisieren (Signatur geprüft) |
Ein Befehl außerhalb des Bereichs antwortet mit scope_denied; ein Befehl auf einer Maschine mit reinem Lesezugriff antwortet mit read_only.
login
konsolity login [--name <name>] [--scopes hosts,snippets,sessions,mcp] [--read-only]
Aktiviert die Maschine mit einem Code, den Sie über Ihr Konto freigeben. Details und Beispiele: Eine Maschine aktivieren.
setup-token
konsolity setup-token [--name <name>] [--scopes <list>] [--read-only]
Gleicher Ablauf wie login, zeigt aber einmalig ein Token ksetup_... an, statt etwas zu speichern. Übergeben Sie es anschließend über KONSOLITY_TOKEN. Siehe setup-token.
status
konsolity status [--json]
Zeigt das Konto, den Namen und Typ der Maschine, den Bereich (Domänen, nur lesend oder vollständig), die Ablaufzeit, das Alter des Tokens, den Serverstatus und die Anzahl der erreichbaren Hosts an.
$ 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]
Listet die Hosts im Bereich auf: Bezeichnung, Adresse, Benutzer, Gruppe. Nie ein Passwort oder ein Schlüssel.
$ 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>
Führt einen Befehl per SSH auf einem Host aus: kurze eigene Verbindung, fixierter Host-Schlüssel erforderlich, Live-Ausgabe im Terminal, der Exit-Code des entfernten Befehls wird als Exit-Code von konsolity weitergegeben. <host> ist die Bezeichnung des Hosts oder seine Kennung. Alles nach -- ist der Befehl, unverändert.
| Option | Funktion |
|---|---|
--timeout <seconds> |
Zeitlimit des Befehls, begrenzt durch das maximale Zeitlimit der Maschine (standardmäßig 60 s). |
--json |
Eine einzige JSON-Ausgabe am Ende: 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
Vor der Ausführung prüft die CLI den Bereich und die Regeln und schreibt dann den Start in das Protokoll: Schlägt dieses Schreiben fehl, wird der Befehl nicht ausgeführt. Ein destruktiver Befehl wartet auf Ihre Bestätigung:
$ 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 zeigt die Snippets im Bereich an (Name, Gruppe). snippet run führt ein Snippet so, wie es im Tresor gespeichert ist, auf einem Host im Bereich aus. <snippet> ist sein Name oder seine Kennung. Es gelten dieselben Regeln wie bei run: Protokoll, Bestätigung bei destruktivem Inhalt, weitergegebener Exit-Code.
$ konsolity snippet run "Clear the cache" web-01
Cache cleared.
sessions
konsolity sessions [--follow] [--json]
konsolity sessions end <id>
Listet die laufenden CLI-Sitzungen des Kontos auf: Maschine, Befehl, seit wann. --follow hält die Liste offen und aktualisiert sie. sessions end <id> beendet eine Sitzung: Der zugehörige Befehl wird in weniger als 5 Sekunden gestoppt.
$ 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
Startet einen lokalen stdio-MCP-Server, den Sie in Claude Code anbinden:
claude mcp add konsolity -- konsolity mcp
Details zu den Tools und Grenzen: Lokaler MCP für Claude Code.
serve
konsolity serve
Bearbeitet die Anfragen des Claude-Connectors des Kontos (claude.ai, Claude-App) wie die Desktop-App, aber ohne Oberfläche, innerhalb des Bereichs und der Regeln. Erfordert die Domäne mcp und die Claude-Integration des Tarifs Studio. Läuft im Vordergrund; installieren Sie es auf einem Server als Dienst.
service install
sudo konsolity service install
Installiert konsolity serve als Systemdienst (systemd, launchd oder eine geplante Windows-Aufgabe). Siehe Dienst und Speicherung.
rotate
konsolity rotate
Erzwingt die Erneuerung des Maschinen-Tokens. Die Rotation erfolgt ohnehin automatisch alle 24 Stunden. Der Maschinenschlüssel ändert sich nicht.
policy
konsolity policy [--json]
Zeigt an, was die Maschine tatsächlich anwendet: Domänen, nur lesend oder vollständig, Hosts, Snippets, Befehlsregeln, „Beliebiger Befehl“, maximales Zeitlimit.
logout
konsolity logout
Widerruft die Maschine auf dem Server und löscht dann das Token, den Maschinenschlüssel und die lokalen Kopien. Um die Maschine wieder zu verwenden, ist eine neue Aktivierung nötig.
version
konsolity version
Zeigt die Version, das System und die Architektur an.
update
konsolity update
Lädt die neueste Version herunter, prüft ihren SHA-256-Hash und die Ed25519-Signatur des Manifests und ersetzt dann das Binary. Bei einer Installation mit apt, dnf oder Homebrew verweist die CLI Sie auf diesen Paketmanager.
Umgebungsvariablen
| Variable | Funktion |
|---|---|
KONSOLITY_TOKEN |
Langlebiges Token ksetup_... (CI, Container). Ersetzt die gespeicherten Geheimnisse. |
Exit-Codes
| Code | Bedeutung |
|---|---|
0 |
Erfolg. |
| entfernter Code | run und snippet run beenden sich mit dem Exit-Code des entfernten Befehls (zum Beispiel 1, wenn der Befehl auf dem Host fehlgeschlagen ist). |
1 |
Allgemeiner Fehler: Maschine nicht aktiviert, Netzwerk nicht erreichbar, Host oder Snippet nicht gefunden, Protokollzeile nicht geschrieben (der Befehl wird dann nicht gestartet), lokale Geheimnisse nicht lesbar. |
2 |
Bedienfehler: unbekannte Option, fehlender oder zu langer Befehl (höchstens 4.000 Zeichen), ungültiges KONSOLITY_TOKEN. |
3 |
Ablehnung: Domäne fehlt im Bereich (scope_denied), Maschine mit reinem Lesezugriff (read_only), keine Regel passt (denied), Regeln fehlen (policy_missing), Tarif erforderlich (plan_required) oder Aktivierung abgelehnt. |
4 |
Destruktiver Befehl nicht bestätigt: in der App oder der Konsole abgelehnt oder innerhalb von 5 Minuten unbeantwortet. Er wurde nicht gestartet. |
77 |
Maschine widerrufen, abgelaufen oder von einem anderen Computer aus verwendet (anderer Fingerabdruck), oder Sitzung aus der App oder der Konsole beendet: Die Verbindungen werden getrennt und der Befehl gestoppt. Außer bei einem einfachen Sitzungsende werden auch die lokalen Geheimnisse gelöscht. |