Befehlsreferenz

Aktualisiert am 10. November 2026

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.