Carrot404/agent-ssh-cli

agent-ssh-cli – Verwendungshinweise

agentsshcli ist ein CLI-Werkzeug, das über npm installiert und von einem nativen Rust-Executor für SSH-Operationen ausgeführt wird. Es ermöglicht KI oder Benutzern, über eine lokale Konfiguration sicher auf Remote-Server zuzugreifen.

Funktionen:

• Auflisten von SSH-Serververbindungen aus der lokalen Konfiguration
• Ausführen von Befehlen auf einem bestimmten Remote-Server
• Eintragen von SSH-Host-Public-Keys in die lokale known_hosts-Datei unter Verwendung eines vom Benutzer explizit bestätigten SHA256-Fingerprints
• Hochladen lokaler Dateien auf den Remote-Server
• Herunterladen von Dateien vom Remote-Server auf den lokalen Rechner
• Einschränkung ausführbarer Befehle durch eine Befehls-Whitelist/-Blacklist
• Kurzzeitiges Caching von SSH-Verbindungen durch einen Rust-Daemon, um wiederholte Verbindungskosten bei aufeinanderfolgenden Operationen zu reduzieren
• Verwaltung von Verbindungen, Anmeldeinformationen und Sicherheitsrichtlinien über einen visuellen Editor, der nur auf die lokale Loopback-Adresse hört
• Bei der npm-Installation wird automatisch das für die aktuelle Systemplattform passende optionale vorkompilierte Paket heruntergeladen. Derzeit unterstützt werden macOS arm64/x64, Linux x64/arm64, Windows x64

Was es nicht tut:

• Gibt keine Klartext-Passwörter, privaten Schlüssel oder andere sensible Authentifizierungsinformationen aus; Passwörter können verschlüsselt in der lokalen secrets.json gespeichert und nur über den SSH-Kanal stdin gesendet werden
• Scannt nicht das Netzwerk oder entdeckt Server, sondern verwendet nur die in der Konfigurationsdatei enthaltenen Verbindungen
• Umgeht keine in der Konfiguration festgelegten Befehlseinschränkungen

Die Befehls-Whitelist und -Blacklist verwenden die JavaScript RegExp-Syntax, nicht POSIX-konforme reguläre Ausdrücke. Leerzeichen müssen als \\s geschrieben werden, nicht als [:space:]. Beispiel:

{
  "commandBlacklist": [
    "(^|[;&|()\\s])rm(\\s|$)",
    "(^|[;&|()\\s])shutdown(\\s|$)",
    "(^|[;&|()\\s])reboot(\\s|$)"
  ]
}

Sicherheitsbestätigung

Vor der Ausführung gefährlicher Operationen muss eine Benutzerbestätigung eingeholt werden; die direkte Ausführung ist nicht erlaubt.

Gefährliche Operationen umfassen:

• Löschen, Leeren oder Überschreiben von Dateien oder Verzeichnissen, z. B. rm, truncate, Umleitungsüberschreibungen, Massenlöschungen
• Leeren von Caches, Logs, temporären Verzeichnissen oder Geschäftsdaten
• Neustart, Herunterfahren, Stoppen von Diensten oder Töten von Prozessen, z. B. reboot, shutdown, systemctl stop, kill
• Ändern von Berechtigungen, Eigentümern, Systemkonfigurationen oder Starteinträgen, z. B. chmod, chown, Bearbeiten von Dateien unter /etc
• Hochladen von Dateien, die vorhandene Dateien auf dem Remote-Server überschreiben
• Herunterladen von Dateien, die vorhandene lokale Dateien überschreiben
• Jegliche irreversiblen, den Online-Dienst beeinträchtigenden oder die Datenintegrität gefährdende Operationen

Bei der Bestätigung müssen der Zielverbindungsname, der Befehl oder der Dateipfad sowie die möglichen Auswirkungen erläutert und auf eine explizite Zustimmung des Benutzers gewartet werden, bevor die Ausführung fortgesetzt wird.

Umgebungsprüfung

Prüfen Sie vor dem Aufruf, ob die CLI selbst verfügbar ist:

agentsshcli --help

Wenn der obige Befehl fehlschlägt, prüfen Sie die zugrunde liegende Umgebung:

node --version
npm --version

Wenn node oder npm nicht vorhanden sind, weisen Sie den Benutzer an, zuerst Node.js >= 18 und npm >= 8 zu installieren.

Nachdem die CLI verfügbar ist, prüfen Sie, ob die Konfigurationsdatei existiert:

test -f "${AGENT_SSH_CONFIG:-$HOME/.agent-ssh-cli/config.json}"

Wenn die Konfigurationsdatei nicht existiert, weisen Sie den Benutzer an, eine Konfigurationsdatei zu erstellen, und führen Sie keine SSH-Befehle aus:

mkdir -p ~/.agent-ssh-cli
# Dann lassen Sie den Benutzer ~/.agent-ssh-cli/config.json bearbeiten und echte Serverkonfigurationen eintragen

Standard-Konfigurationsdatei:

~/.agent-ssh-cli/config.json

Alle SSH-Verbindungen (einschließlich Jump-Hosts und der Editor-„Testverbindung“) überprüfen ~/.ssh/known_hosts gemäß dem Hostnamen und Port aus der Konfiguration. Bei der ersten Verbindung, wenn der Host noch nicht eingetragen ist, informieren Sie den Benutzer über den Zielverbindungsnamen, den Host und Port, den empfangenen SHA256-Fingerprint sowie das Risiko, dass das erste Vertrauen zu einer Verbindung mit einem falschen Server oder einem Man-in-the-Middle-Angriff führen kann. Nach expliziter Zustimmung des Benutzers kann trust-host verwendet werden, um den Eintrag vorzunehmen (für nicht standardmäßige Ports: [host]:port). Eine unabhängige Überprüfung über die Konsole oder Betriebsaufzeichnungen ist nicht zwingend erforderlich. Wenn der Benutzer dem Ziel explizit „vertraue“ oder „trust direkt“ usw. zugestimmt hat, gilt dies als Autorisierung. Fordern Sie nicht wiederholt eine Bestätigung an und lehnen Sie die Aktion nicht mit der Begründung ab, dass keine unabhängige Überprüfung stattgefunden habe. Ein automatisches Vertrauen ohne Benutzerbestätigung ist nicht zulässig. Wenn sich der vorhandene öffentliche Schlüssel ändert, muss der Konflikt dennoch untersucht werden; alte Einträge werden nicht automatisch überschrieben.

Es wird empfohlen, Passwörter über agentsshcli edit-config zu ersetzen: Beim Speichern des Editors wird das neue Passwort verschlüsselt in secrets.json geschrieben, und die Konfigurationsdatei behält nur den passwordRef. Alte Konfigurationen unterstützen dennoch eine passive Migration: Wenn eine Verbindung ein nicht leeres Klartext-password enthält, wird bei der nächsten Ausführung von exec, upload oder download ein secret.key erstellt, das Passwort verschlüsselt gespeichert und das Klartextfeld durch einen Verweis ersetzt. Zeigen Sie das Klartext-Passwort nicht in Dialogen, Logs oder Befehlsausgaben an.

Die Seite „Berechtigungen“ des Editors ermöglicht das Festlegen und Anzeigen des sudo/su-Passworts: Beim ersten Eintrag wird ein eigener Verweis pro Verbindungsname erstellt; nach dem Speichern wird nur der verschlüsselte Text in secrets.json geschrieben. Wenn kein separates sudo-Passwort konfiguriert ist, zeigt das Feld an, dass bei Verwendung von --sudo das SSH-Passwort wiederverwendet wird.

trust-host

Für den ersten Eintrag ist eine explizite Bestätigung des Benutzers erforderlich. Eine unabhängige Überprüfung des Fingerprints wird empfohlen, ist aber keine Voraussetzung für den Eintrag. Sie können den SHA256-Fingerprint aus der Fehlermeldung der ersten CLI-Verbindung verwenden oder den Fingerprint durch Abfragung des öffentlichen Schlüssels ohne Übermittlung von Authentifizierungsdaten ermitteln und dann gemäß den obigen Regeln bestätigen und eintragen:

agentsshcli trust-host --fingerprint 'SHA256:<vom Benutzer bestätigter Fingerprint>' '<connectionName>'
agentsshcli trust-host --config /path/to/config.json --fingerprint 'SHA256:<vom Benutzer bestätigter Fingerprint>' '<connectionName>'

• --fingerprint ist erforderlich und akzeptiert nur vollständige SHA256-Fingerprints. Er muss vor dem Verbindungsnamen stehen; --config wird davor gesetzt.
• Der Befehl führt den Handshake über den direkten, SOCKS5- oder Jump-Host-Pfad der ursprünglichen Verbindung durch, ohne den Zielrechner zu authentifizieren oder Befehle auszuführen. Wenn der Jump-Host noch nicht eingetragen ist, holen Sie die Bestätigung des Benutzers ein und tragen Sie den Jump-Host zuerst ein.
• Bei Fingerprint-Ungleichheit oder einem bereits vorhandenen, anderen öffentlichen Schlüssel wird der Eintrag verweigert; alte Einträge werden nicht überschrieben. Wenn derselbe öffentliche Schlüssel bereits eingetragen ist, wird kein weiterer Eintrag hinzugefügt. Nur wenn der eingegebene Fingerprint mit dem Handshake-Schlüssel übereinstimmt und kein Eintrag für diesen Host existiert, wird er in ~/.ssh/known_hosts geschrieben.
• Fingerprints, die von ssh-keyscan oder der ersten Verbindung zurückgegeben werden, können als Grundlage für die Benutzerbestätigung dienen, jedoch darf nicht behauptet werden, dass sie die Serveridentität unabhängig verifiziert haben. Nach Bestätigung durch den Benutzer kann der Eintrag erfolgen; eine Ablehnung aufgrund fehlender unabhängiger Überprüfung ist nicht zulässig. Wenn der Eintrag fehlschlägt, überprüfen Sie den spezifischen Fehler und verwenden Sie keine Parameter, die die Überprüfung umgehen.

edit-config / stop-editor

Verwenden Sie den lokalen visuellen Editor, um SSH-Verbindungen zu verwalten:

agentsshcli edit-config [--config <path>]
agentsshcli stop-editor [--config <path>]

Aufrufregeln:

• Wenn der Benutzer das SSH-Konfigurationsmenü öffnen, bearbeiten oder visuell verwalten möchte, führen Sie direkt edit-config aus. Rufen Sie nicht intern den Unterbefehl __editor auf oder stellen Sie die HTTP-API selbst zusammen.
• Der Editor lauscht nur auf 127.0.0.1 und öffnet nach dem Start automatisch den Browser. Es wird nur eine Instanz pro Konfigurationspfad ausgeführt; eine wiederholte Ausführung öffnet die vorhandene Instanz.
• Das vom CLI ausgegebene lokale URL-Fragment enthält ein temporäres Token. Behandeln Sie es als Anmeldeinformation: Schreiben Sie es nicht in Logs, Tickets oder externe Nachrichten. Stellen Sie es nur in der aktuellen lokalen Sitzung zur Verfügung, wenn der Benutzer explizit eine manuelle Adresse benötigt.
• Wenn 10 Minuten lang keine authentifizierte gültige API oder keine echten pointerdown-, keydown- oder input-Ereignisse eingegangen sind, beendet sich der Editor automatisch und löscht die Statusdatei. Wenn die Seite ungültig wird, führen Sie edit-config erneut aus.
• stop-editor stoppt nur den lokalen Editor, der dieser Konfiguration zugeordnet ist, nicht den SSH-Daemon, zwischengespeicherte Verbindungen oder Remote-Aufgaben.
• Führen Sie stop-editor nicht aus, während der Benutzer möglicherweise noch nicht gespeicherte Änderungen auf der Seite hat. Rufen Sie es nur auf, wenn der Benutzer das Stoppen explizit angefordert oder bestätigt hat, dass nicht gespeicherte Inhalte verworfen werden können.
• edit-config / stop-editor unterstützen --config, --help und --version, jedoch nicht --no-cache, --cache-ttl oder Positionsparameter.
• Die Konfigurationsdatei könnte von anderen Prozessen geändert werden. Wenn beim Speichern ein Konflikt erkannt wird, laden Sie sie zuerst neu. Umgehen Sie nicht die Hash-Überprüfung und überschreiben Sie nicht direkt.
• Das JSON-Panel unterstützt „Global / Aktuelle Verbindung“ und „Vorschau / Quelltext“. Die serverseitige Validierung ist der endgültige Konfigurationsvertrag; Hinweise im Frontend können das Speicherergebnis nicht ersetzen.
• Die Seite „Testverbindung“ führt einen SSH-Handshake und eine Authentifizierung (einschließlich nicht gespeicherter Passwortentwürfe) mit der aktuellen Konfiguration und den relevanten Jump-Hosts durch, trennt die Verbindung danach, speichert keine Konfiguration und führt keine Befehle aus. Es kann gleichzeitig nur ein Test durchgeführt werden.
• Das Anzeigen von Passwörtern erfolgt durch Entschlüsselung im lokalen Backend. Der Klartext wird nur kurzzeitig auf der Seite angezeigt und nach 15 Sekunden gelöscht. Extrahieren Sie Passwörter nicht über das Terminal, Skripte oder HTTP-Debug-Schnittstellen.
• Verwenden Sie zum Ersetzen von Passwörtern die Ersetzungsfunktion auf der Seite. Nach dem Speichern enthält config.json nur noch den passwordRef, und der verschlüsselte Text wird in die secrets.json im selben Verzeichnis geschrieben. Das Kopieren einer Verbindung überträgt nicht den Passwortverweis.
• Der Editor zeigt keine verbindungsspezifischen PTY-Steuerelemente an, gibt jedoch vorhandene pty-Einstellungen weiter. Überschreiben Sie die PTY-Zuweisung bei der Befehlsausführung weiterhin mit exec --pty / --no-pty.

Rückgabeverhalten:

• Bei erfolgreichem edit-config gibt stdout Konfigurationseditor geöffnet: <local-url> aus, Exit-Code 0. Wenn der Browser nicht geöffnet werden kann, enthält die Fehlermeldung die manuell aufrufbare lokale URL.
• Bei erfolgreichem stop-editor gibt stdout Konfigurationseditor gestoppt aus. Wenn kein entsprechender Dienst läuft, wird Konfigurationseditor läuft nicht zurückgegeben, Exit-Code 1.
• Bei Speicherkonflikten, Konfigurationsvalidierungsfehlern oder unvollständigen Anmeldeinformationsverweisen im Editor sollte die ursprüngliche Konfiguration nicht geändert werden. Behandeln Sie die Fehler je nach spezifischer Meldung auf der Seite oder in stderr.

Beispiel für eine Konfiguration mit verstecktem Passwort:

{
  "name": "server",
  "host": "192.0.2.10",
  "port": 22,
  "username": "root",
  "password": "",
  "passwordRef": "agentsshcli:server"
}

Vollständige Felder der Konfigurationsdatei (jeder Eintrag ist ein eindeutiger Server mit name):

• name: Verbindungsname, muss eindeutig sein
• group / tags: Optional, einfache Gruppierung und Tag-Array. Der Editor unterstützt die Anzeige nach Gruppen oder Tags; Tags werden von Leerzeichen befreit und Duplikate entfernt
• host / port / username: SSH-Host, Port (Standard 22), Benutzername
• password / passwordRef / privateKey: Authentifizierungsmethode, nur eine der drei kann vorhanden sein; passphrase wird nur in Verbindung mit privateKey verwendet
• jumpHost: Verbindungsname des Jump-Hosts, der dem name eines anderen Rechners in der Konfigurationsdatei entspricht. Bei der Verbindung wird zuerst eine SSH-Verbindung zum Jump-Host hergestellt und dann über einen direkten Kanal zum Zielserver
• socksProxy: SOCKS5-Proxy-Adresse, z. B. socks5://127.0.0.1:1080. Kann auch ohne Protokoll als 127.0.0.1:1080 geschrieben werden
• pty: Gibt an, ob standardmäßig ein Pseudo-Terminal zugewiesen wird. exec --pty / --no-pty kann dies temporär überschreiben
• privilegeEnabled: Gibt an, ob exec --sudo/--su erlaubt ist. Standard: false
• sudoUser: Zielbenutzer für sudo, Standard: root. sudoPassword/sudoPasswordRef speichert das sudo-Passwort des aktuellen SSH-Benutzers. Wenn nicht vorhanden, kann das SSH-Passwort wiederverwendet werden
• suUser: Zielbenutzer für su, Standard: root. suPassword/suPasswordRef muss das Passwort des Zielbenutzers enthalten
• commandWhitelist / commandBlacklist: Arrays für Befehls-Whitelist/-Blacklist in Form regulärer Ausdrücke

Beispiel für Jump-Hosts:

[
  {
    "name": "Zielrechner",
    "host": "10.0.0.5",
    "username": "root",
    "passwordRef": "agentsshcli:Zielrechner",
    "jumpHost": "Jump-Host"
  },
  {
    "name": "Jump-Host",
    "host": "203.0.113.10",
    "port": 22,
    "username": "ubuntu",
    "privateKey": "/path/to/jump_key"
  }
]

Angabe einer anderen Konfigurationsdatei:

AGENT_SSH_CONFIG=/path/to/config.json agentsshcli list

Wenn die CLI nicht verfügbar ist, aber Node/npm funktionieren, weisen Sie den Benutzer an, sie zu installieren:

npm install -g agent-ssh-cli
agentsshcli --help

Für die Entwicklung oder das lokale Debuggen aus dem Quellcode muss zuerst der native Rust-Executor erstellt werden:

npm run build:native
npm test

Globale Parameter

• --config <path>: Gibt den Pfad zur Konfigurationsdatei an. Hat Vorrang vor der Standardkonfiguration.
• --help, -h: Zeigt die Hilfe an.
• --version, -v: Zeigt die Version an.

exec, upload, download verwenden standardmäßig den Verbindungscache des Rust-Daemons, um wiederholte SSH-Handshakes und Authentifizierungskosten bei aufeinanderfolgenden Operationen zu reduzieren. Nur wenn --no-cache übergeben wird, wird der Cache übersprungen und eine direkte Verbindung hergestellt. Die Cache-bezogenen Parameter sind wie folgt:

• --no-cache: Überspringt den Verbindungscache des Rust-Daemons. Dieser Befehl stellt eine unabhängige Verbindung her und trennt sie wieder (direkter Modus).
• --cache-ttl <ms>: Legt die Leerlaufzeit (in Millisekunden) für den Verbindungscache des Rust-Daemons fest. Standard: 180000.
• --json: Gibt für exec, upload, download strukturiertes JSON aus (Felder: exitCode/stdout/stderr), geeignet für Skripte und KI-Analyse.

Alle Parameter (wie --no-cache, --cache-ttl, --json, --timeout, --pty) müssen vor dem Verbindungsnamen (dem ersten Positionsparameter) stehen; sie können in beliebiger Reihenfolge gemischt werden. Wenn sie nach dem Verbindungsnamen stehen, werden sie als Teil des Befehls interpretiert und führen zu einer „Nicht unterstützter Parameter“-Meldung. Befehle sollten in Anführungszeichen gesetzt werden.

init-config

Generiert eine Standard-Konfigurationsdatei unter ~/.agent-ssh-cli/config.json (überschreibt keine vorhandene Datei):

agentsshcli init-config

list

Listet die in der Konfiguration enthaltenen Server auf.

agentsshcli list
agentsshcli list --json
agentsshcli list --group Produktion --tag Applikation

Parameter:

• --json: Gibt das Ergebnis im JSON-Format aus. Die aktuelle Standardausgabe ist ebenfalls JSON.
• --config <path>: Gibt die Konfigurationsdatei an.
• --group <group> / --tag <tag>: Groß-/Kleinschreibung-beachtender exakter Filter. Bei gleichzeitiger Angabe wird die Schnittmenge gebildet.

Rückgabewerte:

• Bei Erfolg gibt stdout ein Array mit Servern aus, das die Felder name, host, port, username, group, tags enthält. Wenn ein Jump-Host konfiguriert ist, wird auch jumpHost angegeben. Bei keiner Übereinstimmung wird [] ausgegeben.
• Es werden keine Passwörter, privaten Schlüssel, Passphrasen oder sensible/Steuerfelder wie Whitelist/Blacklist ausgegeben.
• Exit-Code: 0

Beispielausgabe:

[
  {
    "name": "Server",
    "group": null,
    "tags": [],
    "host": "192.0.2.10",
    "port": 22,
    "username": "root"
  }
]

exec

Führt einen Befehl auf einem Remote-Rechner aus.

Positionsparameter-Form:

agentsshcli exec "<connectionName>" "<command>"
agentsshcli exec --no-cache "<connectionName>" "<command>"
agentsshcli exec --cache-ttl 60000 "<connectionName>" "<command>"
agentsshcli exec --pty "<connectionName>" "<command>"
agentsshcli exec --no-pty "<connectionName>" "<command>"
agentsshcli exec --sudo "<connectionName>" "systemctl status app"
agentsshcli exec --su "<connectionName>" "id && pwd"

Regeln für sudo/su-Erhöhung

Wenn der Benutzer die Verwendung von sudo, su, Root-Identität oder einen anderen Zielbenutzer auf einem vorhandenen Nicht-Root-Verbindung wünscht, müssen die CLI-Top-Level-Parameter --sudo oder --su verwendet werden. Ändern Sie nicht selbstständig den Remote-Befehl.

• --sudo/--su müssen vor dem Verbindungsnamen oder --connection stehen.
• Es ist verboten, sudo, sudo -S, sudo -n, su oder su -c in den <command> einzufügen. Diese Schreibweise umgeht den Passwortkanal der CLI-Erhöhung, kann auf interaktive Eingabe warten oder fälschlicherweise annehmen, dass das Tool kein Passwort unterstützt.
• Lehnen Sie nicht aufgrund eines Timeouts eines normalen su -c ab, dass agentsshcli nicht auf die Passwortaufforderung reagieren kann. agentsshcli 0.5.0+ sendet die konfigurierten verschlüsselten Anmeldeinformationen automatisch über den SSH-Kanal stdin.
• Bei --su --json kann stderr weiterhin die Remote-Password:-Eingabeaufforderung enthalten. Diese Aufforderung enthält kein echtes Passwort und stellt keinen Authentifizierungsfehler dar. Das Ergebnis muss anhand des JSON-exitCode und der stdout-Ausgabe von whoami/id -u beurteilt werden.
• Stellen Sie vor der Verwendung sicher, dass die Verbindungskonfiguration privilegeEnabled: true und der Zielbenutzer konfiguriert ist. su erfordert ein separates Passwort. Wenn kein sudo-Passwort verfügbar ist, wird die entfernte NOPASSWD-Richtlinie unterstützt.

Richtige Schreibweise:

agentsshcli exec --json --sudo "<connectionName>" "whoami; id -u"
agentsshcli exec --json --su "<connectionName>" "whoami; id -u"
agentsshcli exec --no-cache --json --su "<connectionName>" "id"

Falsche Schreibweise:

agentsshcli exec "<connectionName>" "su -c 'id'"
agentsshcli exec "<connectionName>" "sudo -S id"
agentsshcli exec "<connectionName>" "sudo -n id"

Benannte Parameter-Form:

agentsshcli exec --connection "<connectionName>" --command "<command>" --directory "/root" --timeout 5000
agentsshcli exec --connection "<connectionName>" --command-file "./script.sh" --timeout 5000
agentsshcli exec --no-cache --connection "<connectionName>" --command "<command>"

Parameter:

• <connectionName>: Verbindungsname
• <command>: Remote-Befehl
• --connection <name>, -c <name>: Verbindungsname
• --command <command>: Remote-Befehl
• --command-file <path>: Liest den Inhalt einer lokalen UTF-8-Datei und führt ihn als Remote-Befehl aus (wird nicht zuerst hochgeladen und dann ausgeführt). Geeignet für mehrzeilige Skripte. Die Datei muss LF-Zeilenumbrüche verwenden, keine Windows CRLF-Zeilenumbrüche. Kann nicht gleichzeitig mit --command oder dem Positionsparameter <command> verwendet werden.
• --directory <dir>, -d <dir>: Remote-Arbeitsverzeichnis
• --timeout <ms>, -t <ms>: Timeout in Millisekunden, Standard: 30000
• --pty: Weist diesem Befehl ein Pseudo-Terminal zu. Hat Vorrang vor der Konfigurationsdatei.
• --no-pty: Weist diesem Befehl kein Pseudo-Terminal zu. Hat Vorrang vor der Konfigurationsdatei.
• --sudo: Führt den Befehl mit sudo-Erhöhung aus. Erfordert, dass die Verbindungskonfiguration privilegeEnabled: true ist.
• --su: Führt den Befehl mit su-Benutzerwechsel aus. Erfordert, dass die Verbindungskonfiguration privilegeEnabled: true ist. Ist gegenseitig ausschließend mit --sudo.
• --json: Gibt strukturiertes JSON aus (exitCode/stdout/stderr).
• --no-cache: Wiederverwendet keine Verbindung. Muss vor dem Verbindungsnamen oder --connection stehen.
• --cache-ttl <ms>: Leerlaufzeit des Verbindungscaches in Millisekunden. Muss vor dem Verbindungsnamen oder --connection stehen.

Erhöhungsmodi unterstützen nur nicht-interaktive Befehle: Das CLI sendet das Passwort über den SSH-Kanal stdin und schließt dann stdin. Der Zielbefehl kann keine weiteren Eingaben lesen. Wenn keine separaten sudo-Anmeldeinformationen vorhanden sind, kann das SSH-Passwort wiederverwendet werden. Ohne verfügbares Passwort wird nicht-interaktives sudo -n verwendet, das die entfernte NOPASSWD-Richtlinie oder einen gültigen Authentifizierungscache unterstützt. Wenn ein Passwort erforderlich ist, schlägt der Befehl sofort fehl. Bei Anmeldung mit privatem Schlüssel, wenn der Remote-Rechner ein Passwort erfordert, muss sudoPassword/sudoPasswordRef konfiguriert werden. su erfordert immer ein separates Zielbenutzer-Passwort.

Bei Verwendung von --command-file muss die Skriptdatei LF-Zeilenumbrüche verwenden. CRLF-Dateien übertragen \r an die entfernte Bash, was zu $'xxx\r': command not found führen kann.

Empfohlene Schreibweise für macOS/Linux:

cat > /tmp/remote-command.sh <<'EOF'
pwd
EOF
agentsshcli exec --connection "<connectionName>" --command-file /tmp/remote-command.sh

Empfohlene Schreibweise für Windows PowerShell (explizite LF):

[System.IO.File]::WriteAllText("$env:TEMP\remote-command.sh", "pwd`n", [System.Text.UTF8Encoding]::new($false))
agentsshcli exec --connection "<connectionName>" --command-file "$env:TEMP\remote-command.sh"

Rückgabewerte:

• Bei Erfolg mit stdout: stdout gibt das Ergebnis des Remote-Befehls aus.
• Bei Erfolg ohne stdout: Keine Ausgabe.
• Exit-Code: 0.
• Bei Nicht-Null-Exit-Code des Remote-Befehls, Timeout, Treffer in der Blacklist, Verfehlen der Whitelist oder Verbindungsfehler: stderr gibt die Fehlermeldung aus, Exit-Code: 1.
• Im --json-Modus wird JSON ausgegeben. exitCode ist der echte Exit-Code des Remote-Befehls (Nicht-Null bedeutet Befehlsfehler). stdout/stderr geben die entfernte Ausgabe unverändert zurück. Bei Befehlsfehlern bleibt der Exit-Code des Prozesses 1.

Hinweise:

• Bei Verwendung von pkill -f / pgrep -f in einem Befehl kann das Suchmuster die ausführende Remote-Shell selbst treffen (die Befehlszeile enthält die Zeichenfolge), was dazu führt, dass die Shell getötet wird und der Befehl ohne Ausgabe abbricht. Verwenden Sie reguläre Ausdrucks-Tricks, um die Shell selbst auszuschließen, z. B. pkill -f 'name[.]log'.
• Wenn eine Remote-Sitzung ungewöhnlich beendet wird (Shell wird getötet usw.), wird [remote] Sitzung ungewöhnlich beendet (kein Exit-Status) gemeldet, kein stiller Erfolg.
• Wenn ein Befehl am Ende einen Hintergrundprozess startet und stdout nicht umleitet, schließt der Remote-Rechner den Kanal nicht und der Befehl wartet bis zum Gesamt-Timeout. Für Hintergrundausführung leiten Sie stdout/stderr in eine Datei um, z. B. > /tmp/x.log 2>&1 < /dev/null &.
• Befehle müssen in Anführungszeichen gesetzt werden (z. B. --command "<command>" oder Positionsparameter "<command>"): Token wie --json, --timeout usw. innerhalb des Befehls werden als CLI-Parameter analysiert. Ohne Anführungszeichen können sie verschluckt werden oder Fehler verursachen.

upload

Lädt eine lokale Datei auf den Remote-Server hoch.

Positionsparameter-Form:

agentsshcli upload "<connectionName>" "<localPath>" "<remotePath>"
agentsshcli upload --no-cache "<connectionName>" "<localPath>" "<remotePath>"

Benannte Parameter-Form:

agentsshcli upload --connection "<connectionName>" --local "./tmp/upload.txt" --remote "/usr/local/test/upload.txt"
agentsshcli upload --no-cache --connection "<connectionName>" --local "./tmp/upload.txt" --remote "/usr/local/test/upload.txt"

Parameter:

• <connectionName>: Verbindungsname
• <localPath>: Pfad zur lokalen Datei
• <remotePath>: Zielpfad auf dem Remote-Server
• --connection <name>, -c <name>: Verbindungsname
• --local <path>, -l <path>: Pfad zur lokalen Datei
• --remote <path>, -r <path>: Zielpfad auf dem Remote-Server
• --timeout <ms>: Gesamt-Timeout in Millisekunden, Standard: unbegrenzt (ermöglicht lange Laufzeiten für große Dateien); unterscheidet sich vom Standard-Timeout von 30s bei exec
• --recursive: Lädt Verzeichnisse rekursiv hoch, relative Pfade bleiben erhalten. Symbolische Links werden nicht verfolgt: Links zu Verzeichnissen werden übersprungen (um Schleifen zu vermeiden), Links zu Dateien werden mit ihrem Inhalt hochgeladen.
• --json: Gibt strukturiertes JSON aus
• --no-cache: Wiederverwendet keine Verbindung. Muss vor dem Verbindungsnamen oder --connection stehen.
• --cache-ttl <ms>: Leerlaufzeit des Verbindungscaches in Millisekunden. Muss vor dem Verbindungsnamen oder --connection stehen.

Upload-Stabilität:

• Der Upload schreibt zuerst in eine temporäre Datei <remotePath>.part auf dem Remote-Server. Nach Abschluss wird die Prüfsumme validiert und die Datei in den endgültigen Zielnamen umbenannt.
• Gleichzeitig werden Metadaten für Fortsetzungsdownloads in <remotePath>.part.meta geschrieben. Wenn sich die lokale Dateigröße, der Änderungszeitpunkt oder die Blockgröße ändern, werden alte temporäre Dateien gelöscht und der Upload neu gestartet, um fehlerhafte Zusammenführungen zu vermeiden.
• Wenn der Upload unterbrochen wird, wird beim nächsten Upload derselben lokalen Datei auf denselben Remote-Pfad ab der vorhandenen .part-Größe fortgesetzt (Resume).
• Im --no-cache-Modus kann der aktuelle Upload mit Ctrl+C gestoppt werden. Im Daemon-Modus kann stop-daemon verwendet werden, um die Verbindungspool grob zu stoppen, was jedoch andere Aufgaben innerhalb desselben Daemons beeinträchtigt und keine präzise Stornierung einzelner Uploads darstellt.

Rückgabewerte:

• Bei Erfolg gibt stdout File uploaded successfully aus.
• Exit-Code: 0.
• Einzelfalldatei-Upload erstellt kein Remote-Verzeichnis: Wenn das Zielverzeichnis nicht existiert (oder ein gleichnamiger Pfad eine Datei ist), wird direkt Remote-Verzeichnis existiert nicht oder ist nicht zugänglich: <dir> gemeldet. Das Verzeichnis muss zuerst erstellt werden, oder es sollte --recursive für den Upload des gesamten Verzeichnisses verwendet werden (der rekursive Modus erstellt automatisch Verzeichnisse).
• Wenn die lokale Datei nicht existiert, der Remote-Schreibvorgang fehlschlägt oder die Verbindung fehlschlägt, gibt stderr die Fehlermeldung aus, Exit-Code: 1.
• Im --json-Modus ist stdout bei Erfolg {"exitCode":0,"stdout":"File uploaded successfully","stderr":""}, bei Fehlschlag ist exitCode 1.

download

Lädt eine Datei vom Remote-Server herunter.

Positionsparameter-Form:

agentsshcli download "<connectionName>" "<remotePath>" "<localPath>"
agentsshcli download --no-cache "<connectionName>" "<remotePath>" "<localPath>"

Benannte Parameter-Form:

agentsshcli download --connection "<connectionName>" --remote "/usr/local/test/upload.txt" --local "./tmp/download.txt"
agentsshcli download --no-cache --connection "<connectionName>" --remote "/usr/local/test/upload.txt" --local "./tmp/download.txt"

• <connectionName>: Verbindungsname
• <remotePath>: Pfad zur Datei auf dem Remote-Server
• <localPath>: Zielpfad auf dem lokalen Rechner
• --connection <name>, -c <name>: Verbindungsname
• --remote <path>, -r <path>: Pfad zur Datei auf dem Remote-Server
• --local <path>, -l <path>: Zielpfad auf dem lokalen Rechner
• --timeout <ms>: Gesamt-Timeout in Millisekunden, Standard: unbegrenzt (ermöglicht lange Laufzeiten für große Dateien); unterscheidet sich vom Standard-Timeout von 30s bei exec
• --recursive: Lädt Verzeichnisse rekursiv herunter, relative Pfade bleiben erhalten. Symbolische Links auf dem Remote-Server werden übersprungen.
• --json: Gibt strukturiertes JSON aus
• --no-cache: Wiederverwendet keine Verbindung. Muss vor dem Verbindungsnamen oder --connection stehen.
• --cache-ttl <ms>: Leerlaufzeit des Verbindungscaches in Millisekunden. Muss vor dem Verbindungsnamen oder --connection stehen.

Download-Stabilität:

• Der Download schreibt zuerst in eine temporäre Datei <localPath>.part und schreibt Metadaten für Fortsetzungsdownloads in <localPath>.part.meta. Nach Abschluss wird die Größe überprüft und die Datei in den endgültigen Namen umbenannt.
• Wenn der Download unterbrochen wird, wird beim nächsten Download derselben Remote-Datei auf denselben lokalen Pfad ab der vorhandenen .part-Größe fortgesetzt. Wenn sich die Eigenschaften der Remote-Datei ändern, wird die alte .part-Datei automatisch gelöscht und der Download neu gestartet.

Rückgabewerte:

• Bei Erfolg gibt stdout File downloaded successfully aus.
• Exit-Code: 0.
• Bei lokalem Schreibfehler, Remote-Lesefehler oder Verbindungsfehler gibt stderr die Fehlermeldung aus, Exit-Code: 1.
• Im --json-Modus ist stdout bei Erfolg {"exitCode":0,"stdout":"File downloaded successfully","stderr":""}, bei Fehlschlag ist exitCode 1.

stop-daemon

Stoppt den SSH-Cache-Prozess (Verbindungspool), der der aktuellen Konfigurationsdatei zugeordnet ist. Es ist ein Wartungsbefehl für den Verbindungspool, keine präzise Stornierung einzelner Upload-Aufgaben, und beeinträchtigt andere Aufgaben innerhalb desselben Daemons:

agentsshcli stop-daemon [--config <path>]

help/version

agentsshcli --help
agentsshcli help list
agentsshcli help exec
agentsshcli help upload
agentsshcli help download
agentsshcli help edit-config
agentsshcli help stop-editor
agentsshcli --version

Rückgabewerte:

• Bei erfolgreicher Hilfe gibt stdout den Hilfetext aus, Exit-Code: 0.
• Bei erfolgreicher Version gibt stdout die Versionsnummer aus, Exit-Code: 0.

Fehlerregeln

…

[gekürzt für Übersetzung]