Steuerungs-CLI¶

kortty-cli ist der Kommandozeilenclient für korTTYs Steuerungs-API. Er wird in jedem korTTY-Paket als zweiter Starter neben der Anwendung selbst ausgeliefert, findet das laufende korTTY von allein, authentifiziert sich und übersetzt die Antworten der API in etwas, mit dem ein Shell-Skript oder ein Coding-Agent arbeiten kann.

Er spricht ausschließlich mit einem korTTY auf demselben Rechner und nur, solange dort die Steuerungs-API eingeschaltet ist. Was die API verweigert, verweigert auch die CLI.

Wo der Befehl liegt¶

kortty-cli ist kein Skript, sondern ein echter Starter im gepackten Anwendungsabbild, der die mitgelieferte JVM startet – Java muss also nicht im PATH liegen.

Nur das pacman-Paket legt den Befehl für Sie in den PATH. Überall sonst nehmen Sie das Verzeichnis in den PATH auf oder verlinken den Starter in ein Verzeichnis, das schon darin liegt:

# macOS
sudo ln -s /Applications/korTTY.app/Contents/MacOS/kortty-cli /usr/local/bin/kortty-cli

# Linux deb/rpm
sudo ln -s /opt/kortty/bin/kortty-cli /usr/local/bin/kortty-cli

# Windows, for the current user
[Environment]::SetEnvironmentVariable(
    'Path', $env:Path + ';C:\Program Files\korTTY', 'User')

Der Starter heißt bewusst nicht kortty: dieser Name gehört dem grafischen Starter (/usr/bin/kortty unter Arch, korTTY sonst), und unter macOS und Windows, deren Dateisysteme Groß- und Kleinschreibung ignorieren, würde ein zweiter Starter namens kortty mit ihm kollidieren.

Aufbau eines Befehls¶

kortty-cli <group> <command> [options]

Die Gruppen sind pane, tab, window, agent, events, notify, raw, ping und schema, dazu mcp, das kein einzelner Aufruf ist, sondern ein dauerhaft laufender Server (siehe MCP-Clients bedienen). Innerhalb einer Gruppe ist der Befehlsname die API-Methode nach dem Punkt, deren Unterstriche als Bindestriche geschrieben werden – pane.send_text wird zu pane send-text. Vier Methoden ergeben sich nicht aus ihrem Namen und sind es wert, gemerkt zu werden: api.schema ist schema, events.subscribe ist events, notification.show ist notify, und alles ohne eigenen Befehl – events.unsubscribe, pane.resolve – erreichen Sie über raw.

Alles, was ein Befehl braucht, ist eine Option. Positionsargumente gibt es nur für die Tastennamen von pane send-keys und agent send-keys sowie für Methode und JSON von raw.

kortty-cli ping                                   # is a korTTY listening?
kortty-cli pane list                              # every open pane
kortty-cli pane read --focused --recent --lines 200
kortty-cli pane run --pane p1a2b3c4d --command 'make test'
kortty-cli pane wait-output --pane p1a2b3c4d --contains 'BUILD SUCCESSFUL' --timeout-ms 300000
kortty-cli raw events.unsubscribe '{"subscription":"s1"}'

kortty-cli schema gibt die vollständige maschinenlesbare Befehlsoberfläche aus – jeden Befehl, seine Optionen, seine Ergebnisform, seine Fehler und ein ausgearbeitetes Beispiel, direkt aus dem laufenden korTTY. Parameter, Ergebnisse und Fehler entstehen aus denselben Deklarationen, die der Server ausliefert, und die Zeile cli jedes Eintrags wird vor der Auslieferung gegen den Parser genau dieses Clients geprüft; beide beschreiben also die Version, mit der Sie gerade sprechen. Nutzen Sie sie statt zu raten, besonders aus einem Skript, das über Versionen hinweg funktionieren soll.

Befehlsreferenz¶

Jede Option, die der Client akzeptiert, ist entweder eine der unten aufgeführten globalen Optionen oder gehört zu einer der Befehle in der nachfolgenden Tabelle. Eine Option, die ein Befehl nicht auflistet, wird mit Exit 2 abgelehnt, bevor etwas an korTTY gesendet wird.

Globale Optionen¶

Befehle¶

Die --kind-Werte von agent list und agent start sind claude-code, codex, gemini-cli, minimax-code, qwen-code, opencode, cursor-agent, aider, amp, goose, crush, kiro, continue, grok, jules, copilot, grok-build, antigravity, cline und kilo. Die --state-Werte von agent list sind blocked, working, done, idle und unknown.

tab close und tab rename werden von der API als reserviert aufgeführt; kortty-cli verweigert sie selbst, sodass sie nie korTTY erreichen.

Einen Bereich auswählen¶

Jeder Befehl, der ein Paneel anspricht, benötigt genau einen Selektor, und jeder Selektor ist ein Flag. pane list, pane current und agent list benötigen keinen, und agent start akzeptiert --split-from anstelle eines Selektors:

Keinen oder mehr als einen anzugeben ist ein Syntaxfehler (Code 2), der die vier benennt; ein bloßes p1a2b3c4d oder @focused an der Stelle einer Option ist ebenfalls ein Syntaxfehler.

--current löst der Client auf, nicht der Server: er geht seine eigene Prozessabstammung durch und fragt korTTY, welcher Bereich eine dieser Prozesskennungen besitzt. Deshalb funktioniert es ohne jede Vorbereitung aus einer Untershell, einer Makefile-Regel oder einem verschachtelten Skript, und deshalb scheitert es dort, wo es nicht funktionieren kann, mit einer klaren Meldung, statt den falschen Bereich anzusprechen.

Eine Verbindung öffnen¶

kortty-cli tab create --connection <id|name> öffnet eine gespeicherte oder Teamwork-Verbindung in einem neuen Tab und gibt den Tab aus. --isolation none|process|sandbox führt sie mit dieser Sitzungs-Isolation statt der eigenen der Verbindung aus, --incognito öffnet sie als Inkognito-Sitzung, und --window w2 wählt das Fenster. Die Mindest-Isolation der Organisation wird nie unterschritten: wer weniger verlangt, wird mit Exit-Code 3 abgelehnt. Braucht die Anmeldung eine Rückfrage, meldet die Antwort "pending": true, und korTTY fragt Sie, bevor es den Tab öffnet.

kortty-cli tab create --connection web-01 --isolation sandbox --incognito

Warten¶

Befehle, die warten – pane wait-output, agent wait, agent prompt --wait-until, agent start --wait – blockieren, bis die Bedingung erfüllt ist oder die Zeit abläuft, und enden bei Zeitüberschreitung mit Code 4. Jede Wartezeit hat serverseitig eine harte Obergrenze von zehn Minuten; eine längere Anforderung wird gekappt, und die Antwort sagt es.

Anfragen einer Verbindung laufen nacheinander. Ein Skript, das auf einen Bereich warten und gleichzeitig in einem anderen etwas tun will, startet daher einfach zwei Befehle nebenläufig – jeder öffnet seine eigene Verbindung. Bis zu acht Verbindungen dürfen gleichzeitig offen sein.

Ereignisse beobachten¶

kortty-cli events abonniert die Coding-Agent-Ereignisse von korTTY und gibt sie, sobald sie auftreten, als ein JSON-Objekt pro Zeile aus, bis der Strom beendet wird.

kortty-cli events --kinds agent.state_changed --panes p1a2b3c4d --count 1
kortty-cli events --include-evidence --timeout 60000

--kinds und --panes akzeptieren kommagetrennte Listen und schränken ein, was geliefert wird. Die Arten sind agent.added, agent.state_changed, agent.seen, agent.alias_changed, agent.removed, agent.evidence und events.overflow. Ohne --kinds wird jede Art außer agent.evidence gesendet. agent.evidence wird nur mit --include-evidence gesendet, und höchstens einmal pro Sekunde pro Paneel. events.overflow wird immer gesendet und meldet, wie viele Frames verloren gingen, wenn der Stream hinterherhinkt. --count N stoppt nach N Ereignissen. Drei Dinge beenden den Stream: --count wird erreicht, die --timeout passiert oder Sie unterbrechen ihn. Die ersten beiden beenden mit 0. Ein Interrupt wird nicht behandelt — es gibt absichtlich keinen Signalhandler, sodass der Prozess mit dem Shell-128 + SIGINT = 130 endet, was in einem CI-Job, der den Stream in timeout einwickelt, berücksichtigt werden sollte.

Ohne --count und ohne --timeout hat der Strom überhaupt keine Frist und läuft, bis korTTY endet oder Sie ihn anhalten.

MCP-Clients bedienen¶

kortty-cli mcp macht den Client zu einem Model Context Protocol-Server, sodass ein KI-Assistent, der MCP spricht, Ihre korTTY-Bereiche lesen kann. Er unterstützt ausschließlich den MCP-Transport über stdio: Der Host des Assistenten startet kortty-cli mcp als Kindprozess und tauscht mit ihm über stdin und stdout zeilenweise JSON-RPC-Nachrichten aus. Es gibt keinen Netzwerk-Listener; der Prozess erreicht korTTY über denselben lokalen Endpunkt der Steuerungs-API wie jeder andere Befehl und meldet sich als mcp-Client an, sodass korTTY auf jede Anfrage die MCP-Regeln anwendet.

korTTY muss es erlauben: Die Steuerungs-API muss eingeschaltet sein, der separate Schalter MCP-Server unter Einstellungen › Terminal › Steuerungs-API muss eingeschaltet sein, und die Unternehmensrichtlinie darf mcp-server nicht verweigern. Solange eine dieser Bedingungen nicht erfüllt ist, liefert jeder Tool-Aufruf einen Fehler mit der Begründung, und der Assistent kann die Tools trotzdem auflisten.

Die meisten MCP-Hosts werden mit einem JSON-Eintrag wie diesem konfiguriert; tragen Sie in command den vollständigen Pfad von kortty-cli aus der Tabelle oben ein, falls er nicht in Ihrem PATH liegt:

{
  "mcpServers": {
    "kortty": {
      "command": "kortty-cli",
      "args": ["mcp"]
    }
  }
}

Der Server bietet diese Tools an. Jedes Argument trägt den Namen des API-Parameters, den es füllt, und pane nimmt eine Bereichs-ID aus pane_list oder @focused entgegen:

Die Lese-Tools sind als schreibgeschützt und die Schreib-Tools als destruktiv gekennzeichnet, sodass ein Host, der vor destruktiven Tools nachfragt, vor jedem von ihnen nachfragt. korTTY fragt ebenfalls nach, unabhängig vom Host: Jeder Aufruf eines Schreib-Tools öffnet in korTTY eine Rückfrage zur Zustimmung, und ein solcher Aufruf wartet bis zu 70 Sekunden auf Ihre Antwort, bevor er aufgibt. Ein Tool-Ergebnis ist die JSON-Antwort der API als Text; korTTY hat die ihm bekannten Geheimnisse bereits maskiert und die Größe begrenzt. Eine Verweigerung, eine abgelehnte oder unbeantwortete Rückfrage, ein beendetes korTTY oder ein ausgeschalteter MCP-Server kommt als Tool-Fehler mit dem Grund zurück, zum Beispiel method_not_allowed_for_mcp oder mcp_write_denied, und der Assistent kann ihn Ihnen anzeigen. Die Tool-Liste wird bei jeder tools/list-Anfrage einmal gelesen, daher wirkt das Ein- oder Ausschalten der Schreib-Tools erst, wenn der Assistent die Tools das nächste Mal auflistet.

Jeder Tool-Aufruf öffnet eine eigene Verbindung, daher muss der Assistent nach einem Neustart von korTTY nicht neu gestartet werden. Aufrufe werden nacheinander bearbeitet: Ein langes pane_wait_output verzögert die nächste Antwort, bis es zurückkehrt. stdout enthält ausschließlich Protokollnachrichten; kortty-cli mcp schreibt pro Anfrage eine Diagnosezeile nach stderr, die die Methode oder das Tool nennt, aber nie deren Argumente oder Ergebnisse, und --quiet unterdrückt diese Zeilen. --config-dir funktioniert wie bei jedem anderen Befehl.

Exit-Codes¶

Der Exit-Code kommt vom Server, nicht aus einer Tabelle im Client, damit beide nie auseinanderlaufen können.

Jeder Fehler zeigt eine einzeilige Diagnose auf stderr im Format kortty-cli: <message> (<code>), wobei <code> der stabile Wire-Code ist — not_found, timeout, blocked_by_policy — aus dem der obige Exit-Code abgeleitet wurde. Fügen Sie --pretty hinzu, um das ganze JSON-RPC-Fehlerobjekt zu erhalten, das das, was ein Skript überprüfen sollte, ist:

kortty-cli pane read --focused --pretty 2>err.json || code=$(jq -r .error.data.code err.json)

Fehler, die der Client selbst erkennt, sind die Ausnahme: eine unparsbare Befehlszeile, ein nicht laufendes korTTY, ein --current, das keiner Panes entspricht, und ein abgelaufener Client-Termin, der nie auf dem Server erreicht wurde – diese Fehler tragen keine Netzwerkcode und geben auf beiden Einstellungen einen reinen kortty-cli: <message> aus. Entscheiden Sie sich nach dem Exit-Code für diese Fälle.

Die Installation prüfen¶

kortty-cli --version gibt die Version aus und beendet sich mit 0. --version und --help antworten beide ohne laufendes korTTY, was --version zur richtigen Wahl für einen Installationscheck oder einen CI-Feuchtigkeits-Test macht.

kortty-cli --version || echo 'kortty-cli is not installed or not on PATH'

Hinweise fürs Skripten¶

• Auf stdout steht nichts außer dem Ergebnis des Befehls, kortty-cli pane read --focused lässt sich also sauber weiterleiten.
• Diagnosen, Warnungen und Fehlerobjekte gehen auf stderr.
• Das Authentifizierungstoken liest der Client aus ~/.kortty/control/endpoint.json. Es gibt bewusst weder eine Option --token noch eine Umgebungsvariable: ein Token auf der Kommandozeile landet in der Prozessliste und in der Shell-Historie.
• korTTY protokolliert eine Zeile pro Aktion der CLI und zeigt eine Desktop-Benachrichtigung, sobald ein Programm zum ersten Mal in einen Bereich tippt. Ihr Skript ist absichtlich nicht unsichtbar.