Carrot404/agent-ssh-cli

Instructions d'utilisation de agent-ssh-cli

agentsshcli est un outil en ligne de commande installé via npm, dont l'exécuteur natif Rust effectue les opérations SSH. Il permet à un IA ou à un utilisateur d'opérer en toute sécurité sur des serveurs distants via une configuration locale.

Ce qu'il peut faire :

• Lister les connexions de serveurs SSH dans la configuration locale
• Exécuter des commandes sur un serveur distant spécifié
• Enregistrer la clé publique d'un hôte SSH dans le fichier known_hosts local après confirmation explicite de l'empreinte SHA256 par l'utilisateur
• Transférer un fichier local vers un serveur distant
• Télécharger un fichier d'un serveur distant vers le local
• Restreindre les commandes exécutables via des listes noires et blanches
• Mettre en cache les connexions SSH via un daemon Rust pour réduire la surcharge de reconnexion lors d'opérations consécutives
• Gérer les connexions, les références d'identifiants et les politiques de sécurité via un éditeur visuel qui écoute uniquement sur l'adresse de boucle locale
• L'installation npm télécharge automatiquement le paquet précompilé optionnel correspondant au système actuel ; actuellement pris en charge : macOS arm64/x64, Linux x64/arm64, Windows x64

Ce qu'il ne fait pas :

• N'affiche pas les mots de passe en clair, les clés privées ou autres informations d'authentification sensibles ; les mots de passe peuvent être chiffrés et sauvegardés dans le fichier local secrets.json, et envoyés uniquement via le stdin du canal SSH
• Ne scanne pas le réseau ou ne découvre pas les serveurs ; il utilise uniquement les connexions du fichier de configuration
• Ne contourne pas les restrictions de commandes définies dans la configuration

Les listes noires et blanches de commandes utilisent la syntaxe JavaScript RegExp, pas les expressions régulières POSIX. Les caractères d'espacement doivent être écrits comme \\s, pas [:space:]. Par exemple :

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

Confirmation de sécurité

Avant d'exécuter une opération dangereuse, il est obligatoire de demander la confirmation de l'utilisateur ; l'exécution ne doit pas être directe.

Les opérations dangereuses incluent :

• Supprimer, vider ou écraser des fichiers ou répertoires, par exemple rm, truncate, redirection avec écrasement, suppression en masse
• Vider le cache, les journaux, les répertoires temporaires ou les données métier
• Redémarrer, éteindre, arrêter un service ou tuer un processus, par exemple reboot, shutdown, systemctl stop, kill
• Modifier les permissions, le propriétaire, la configuration système ou les éléments de démarrage, par exemple chmod, chown, modifier un fichier sous /etc
• Transférer un fichier et écraser un fichier distant existant
• Télécharger un fichier et écraser un fichier local existant
• Toute opération irréversible, affectant un service en ligne ou l'intégrité des données

Lors de la confirmation, le nom de la connexion cible, la commande ou le chemin du fichier, l'impact potentiel doivent être expliqués, et l'utilisateur doit donner son accord explicite avant l'exécution.

Vérification de l'environnement

Avant d'appeler l'outil, vérifiez d'abord si la CLI elle-même est disponible :

agentsshcli --help

Si la commande ci-dessus échoue, vérifiez ensuite l'environnement de base :

node --version
npm --version

Si node ou npm n'existent pas, invitez l'utilisateur à installer Node.js >= 18 et npm >= 8.

Une fois la CLI disponible, vérifiez si le fichier de configuration existe :

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

Si le fichier de configuration n'existe pas, invitez l'utilisateur à le créer, et n'exécutez pas de commandes SSH :

mkdir -p ~/.agent-ssh-cli
# Ensuite, laissez l'utilisateur éditer ~/.agent-ssh-cli/config.json et y insérer la configuration du serveur réel

Fichier de configuration par défaut :

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

Toutes les connexions SSH (y compris via bastion et le "test de connexion" de l'éditeur) vérifient ~/.ssh/known_hosts en fonction du nom d'hôte et du port de la configuration. Lors d'une première connexion sans enregistrement, expliquez à l'utilisateur le nom de la connexion cible, l'hôte et le port, l'empreinte SHA256 reçue, et le risque qu'une première confiance puisse conduire à une connexion à un serveur erroné ou à une attaque de l'homme du milieu ; une fois que l'utilisateur a explicitement confirmé, vous pouvez utiliser trust-host pour l'enregistrer (pour un port autre que 22, le format est [host]:port). Il n'est pas obligatoire de vérifier indépendamment via la console ou les enregistrements d'exploitation. Lorsque l'utilisateur a explicitement donné son accord pour la cible actuelle (par exemple "j'ai confiance", "fais confiance"), cela est considéré comme une autorisation ; ne demandez pas de confirmation répétée et ne refusez pas au motif que la vérification n'a pas été effectuée de manière indépendante. N'utilisez pas la confiance automatique sans confirmation de l'utilisateur ; si la clé publique existante a changé, vous devez toujours enquêter sur le conflit et ne pas écraser automatiquement l'ancien enregistrement.

Il est recommandé d'utiliser agentsshcli edit-config pour remplacer le mot de passe : lors de la sauvegarde, l'éditeur chiffrera le nouveau mot de passe et l'écrira dans secrets.json, tandis que le fichier de configuration ne conservera qu'une passwordRef. L'ancienne configuration est toujours prise en charge pour une migration passive : si une connexion contient un password en clair non vide, la prochaine exécution de exec, upload ou download générera un secret.key, chiffrera et sauvegardera le mot de passe, et remplacera le champ en clair par une référence. N'affichez pas les mots de passe en clair dans les conversations, les journaux ou les sorties de commandes.

La page "Limites d'autorisation" de l'éditeur permet de définir et de consulter le mot de passe sudo / su : lors de la première saisie, une référence indépendante est générée pour le nom de connexion ; après la sauvegarde, seul le texte chiffré est écrit dans secrets.json ; si un mot de passe sudo n'est pas configuré séparément, le champ indique d'utiliser le mot de passe SSH lors de l'exécution avec --sudo.

trust-host

L'enregistrement initial nécessite la confirmation explicite de l'utilisateur ; la vérification indépendante de l'empreinte est une méthode recommandée, mais pas une condition préalable à l'enregistrement. Vous pouvez utiliser l'empreinte SHA256 renvoyée par l'erreur de première connexion de la CLI, ou obtenir l'empreinte via une sonde de clé publique sans envoyer d'identifiants d'authentification, puis confirmer et enregistrer selon les règles ci-dessus :

agentsshcli trust-host --fingerprint 'SHA256:<empreinte_confirmée_par_utilisateur>' '<nomConnexion>'
agentsshcli trust-host --config /chemin/vers/config.json --fingerprint 'SHA256:<empreinte_confirmée_par_utilisateur>' '<nomConnexion>'

• --fingerprint est obligatoire et n'accepte que l'empreinte SHA256 complète ; il doit être placé avant le nom de connexion ; --config doit être placé avant celui-ci.
• La commande effectue la poignée de main via le chemin direct, SOCKS5 ou bastion existant de la connexion, sans authentifier la machine cible et sans exécuter de commande. Si le bastion n'est pas enregistré, obtenez d'abord la confirmation de l'utilisateur et enregistrez le bastion.
• Si l'empreinte ne correspond pas ou si une clé publique différente existe déjà, l'écriture est refusée et l'ancien enregistrement n'est pas écrasé ; si la même clé publique est déjà enregistrée, elle n'est pas ajoutée à nouveau. L'enregistrement dans ~/.ssh/known_hosts n'est effectué que lorsque l'empreinte fournie correspond à la clé de la poignée de main et qu'il n'y a pas d'enregistrement pour cet hôte.
• Les empreintes renvoyées par ssh-keyscan ou la première connexion peuvent être utilisées comme objet de confirmation par l'utilisateur, mais vous ne pouvez pas prétendre qu'elles ont déjà vérifié indépendamment l'identité du serveur. Après confirmation de l'utilisateur, l'enregistrement est possible ; ne refusez pas en raison d'un manque de vérification indépendante. En cas d'échec d'enregistrement, vérifiez l'erreur spécifique et n'utilisez pas de paramètres qui contournent la vérification.

edit-config / stop-editor

Utilisation de l'éditeur visuel local pour gérer les connexions SSH :

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

Règles d'appel :

• Lorsque l'utilisateur demande d'ouvrir, d'éditer ou de gérer visuellement la configuration SSH, exécutez directement edit-config ; n'appelez pas vous-même la sous-commande interne __editor ou ne construisez pas d'API HTTP.
• L'éditeur écoute uniquement sur 127.0.0.1 et ouvre automatiquement le navigateur après son démarrage. Une seule instance est exécutée pour un même chemin de configuration ; une exécution répétée ouvre l'instance existante.
• Le fragment d'URL local (contenant un jeton temporaire) affiché par la CLI doit être traité comme un identifiant ; ne l'écrivez pas dans des journaux, des tickets ou des messages externes. Ne fournissez l'URL que dans la session locale actuelle si l'utilisateur demande explicitement un accès manuel à l'adresse.
• Si aucune API valide authentifiée ou aucun événement réel (pointerdown, keydown, input) n'est reçu pendant 10 minutes consécutives, l'éditeur se ferme automatiquement et supprime le fichier d'état. Si la page a expiré, réexécutez edit-config.
• stop-editor arrête uniquement l'éditeur local correspondant à cette configuration ; il n'arrête pas le daemon SSH, les connexions en cache ou les tâches distantes.
• N'exécutez pas stop-editor alors que l'utilisateur pourrait avoir des modifications non sauvegardées sur la page ; appelez-le uniquement lorsque l'utilisateur demande explicitement l'arrêt ou a confirmé qu'il peut abandonner les modifications non sauvegardées.
• edit-config / stop-editor prennent en charge --config, --help et --version ; ils n'acceptent pas --no-cache, --cache-ttl ou des arguments positionnels.
• Le fichier de configuration peut être modifié par d'autres processus ; en cas de conflit lors de la sauvegarde, rechargez d'abord le fichier, ne contournez pas la vérification du hachage et n'écrasez pas directement.
• Le panneau JSON prend en charge les modes "Global / Connexion actuelle" et "Aperçu / Source" ; la validation côté serveur est le contrat de configuration final, les indications côté client ne peuvent pas remplacer le résultat de la sauvegarde.
• Le "Test de connexion" de la page effectue une connexion SSH et une authentification (y compris les brouillons de mots de passe non sauvegardés) avec le brouillon actuel et le bastion associé, puis se déconnecte ; il ne sauvegarde pas la configuration et n'exécute pas de commande. Un seul test peut être effectué à la fois.
• L'affichage du mot de passe est déchiffré par le backend local ; le texte en clair n'est affiché que brièvement sur la page et est effacé après 15 secondes. N'extrayez pas le mot de passe via le terminal, des scripts ou une interface de débogage HTTP.
• Le remplacement du mot de passe doit être effectué via l'opération de remplacement de la page ; après la sauvegarde, config.json ne contient plus que passwordRef, et le texte chiffré est écrit dans le fichier secrets.json du même répertoire. La copie d'une connexion ne copie pas la référence du mot de passe.
• L'éditeur n'affiche pas de contrôle PTY au niveau de la connexion, mais transmet le pty existant ; lors de l'exécution de commandes, continuez à utiliser exec --pty / --no-pty pour une surcharge temporaire.

Comportement de retour :

• En cas de succès de edit-config, la sortie standard affiche Éditeur de configuration ouvert : <url-locale> et le code de sortie est 0. En cas d'échec de l'ouverture du navigateur, le message d'erreur contient l'URL locale accessible manuellement.
• En cas de succès de stop-editor, la sortie standard affiche Éditeur de configuration arrêté ; s'il n'y a pas de service correspondant, le retour est Éditeur de configuration non en cours d'exécution, avec un code de sortie de 1.
• En cas de conflit de sauvegarde, d'échec de validation de la configuration ou de référence d'identifiant incomplète dans l'éditeur, la configuration d'origine ne doit pas être modifiée ; gérez l'erreur en fonction de l'erreur spécifique sur la page ou dans la sortie d'erreur standard.

Exemple de configuration avec mot de passe masqué :

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

Champs complets du fichier de configuration (chaque élément est un serveur unique avec name) :

• name: Nom de connexion, doit être unique
• group / tags: Facultatif, groupe unique et tableau d'étiquettes ; l'éditeur prend en charge l'affichage par groupe ou étiquette ; les étiquettes sont nettoyées des espaces et dédoublonnées
• host / port / username: Hôte SSH, port (par défaut 22), nom d'utilisateur
• password / passwordRef / privateKey: Mode d'authentification, un seul des trois peut être conservé ; passphrase est utilisé uniquement avec privateKey
• jumpHost: Nom de connexion du serveur bastion, doit correspondre au name d'une autre machine dans le fichier de configuration ; lors de la connexion, une connexion SSH est d'abord établie avec le bastion, puis un canal direct est utilisé pour atteindre la machine cible
• socksProxy: Adresse du proxy SOCKS5, par exemple socks5://127.0.0.1:1080 ; on peut également omettre le protocole et écrire 127.0.0.1:1080
• pty: Indique si un pseudo-terminal est alloué par défaut ; exec --pty / --no-pty peut le remplacer temporairement
• privilegeEnabled: Indique si exec --sudo/--su est autorisé, par défaut false
• sudoUser: Utilisateur cible pour sudo, par défaut root ; sudoPassword/sudoPasswordRef stocke le mot de passe sudo de l'utilisateur SSH actuel ; en son absence, le mot de passe SSH peut être réutilisé
• suUser: Utilisateur cible pour su, par défaut root ; suPassword/suPasswordRef doit stocker le mot de passe de l'utilisateur cible
• commandWhitelist / commandBlacklist: Tableaux d'expressions régulières pour les listes blanches/noires de commandes

Exemple avec bastion :

[
  {
    "name": "Machine cible",
    "host": "10.0.0.5",
    "username": "root",
    "passwordRef": "agentsshcli:Machine cible",
    "jumpHost": "Bastion"
  },
  {
    "name": "Bastion",
    "host": "203.0.113.10",
    "port": 22,
    "username": "ubuntu",
    "privateKey": "/chemin/vers/jump_key"
  }
]

Spécifier un autre fichier de configuration :

AGENT_SSH_CONFIG=/chemin/vers/config.json agentsshcli list

Si la CLI n'est pas disponible mais que Node/npm fonctionnent, invitez l'utilisateur à installer :

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

Pour le développement à partir des sources ou le débogage local, il est nécessaire de construire d'abord l'exécuteur natif Rust :

npm run build:native
npm test

Paramètres généraux

• --config <chemin>, -c <chemin>: Spécifie le chemin du fichier de configuration, prioritaire par rapport à la configuration par défaut
• --help, -h: Affiche l'aide
• --version, -v: Affiche la version

exec, upload, download utilisent par défaut le cache de connexion du daemon Rust, afin de réduire la surcharge des poignées de main et de l'authentification SSH lors d'opérations consécutives ; le cache est ignoré et une connexion directe est utilisée uniquement si --no-cache est passé. Les paramètres liés au cache sont les suivants :

• --no-cache: Ignore le cache de connexion du daemon Rust, la commande actuelle établit et ferme la connexion de manière indépendante (mode connexion directe)
• --cache-ttl <ms>: Définit la durée d'inactivité en millisecondes pour le cache de connexion du daemon Rust, par défaut 180000
• --json: exec, upload, download produisent une sortie structurée JSON (champs exitCode/stdout/stderr), facilitant l'analyse par les scripts et l'IA

Tous les paramètres (--no-cache, --cache-ttl, --json, --timeout, --pty, etc.) doivent être placés avant le nom de la connexion (premier argument positionnel) ; ils peuvent être mélangés dans n'importe quel ordre. S'ils sont placés après le nom de la connexion, ils seront interprétés comme faisant partie de la commande et une erreur « paramètre non pris en charge » sera retournée. Mettez la commande entre guillemets.

init-config

Génère un fichier de configuration par défaut dans ~/.agent-ssh-cli/config.json (ne l'écrase pas s'il existe déjà) :

agentsshcli init-config

list

Liste les serveurs dans la configuration.

agentsshcli list
agentsshcli list --json
agentsshcli list --group Production --tag Application

Paramètres :

• --json: Produit une sortie au format JSON. La sortie par défaut actuelle est également en JSON.
• --config <chemin>: Spécifie le fichier de configuration
• --group <groupe> / --tag <étiquette>: Filtre précis sensible à la casse ; si les deux sont fournis, l'intersection est utilisée

Valeurs de retour :

• En cas de succès, la sortie standard affiche un tableau de serveurs contenant name, host, port, username, group, tags ; si un bastion est configuré, il y a également jumpHost ; aucun résultat ne donne []
• Les mots de passe, clés privées, passphrases, listes noires/blanches ou autres champs sensibles ou de contrôle ne sont pas affichés
• Le code de sortie est 0

Exemple de sortie :

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

exec

Exécute une commande sur le serveur distant.

Format avec arguments positionnels :

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

Règles d'élévation sudo/su

Lorsque l'utilisateur demande d'exécuter une commande avec sudo, su, en tant que root, ou en changeant d'utilisateur via une connexion non root existante, les paramètres --sudo ou --su au niveau de la CLI doivent être utilisés ; n'utilisez pas vous-même des commandes interactives distantes.

• --sudo/--su doivent être placés avant le nom de la connexion ou l'argument --connection.
• Il est interdit d'incorporer sudo, sudo -S, sudo -n, su ou su -c dans <commande> ; cette forme contourne le canal de mot de passe d'élévation de la CLI, peut attendre une saisie interactive ou faire échouer la commande en indiquant à tort que l'outil ne prend pas en charge le mot de passe.
• Ne concluez pas que agentsshcli ne peut pas répondre à l'invite de mot de passe parce qu'un su -c normal a expiré ; agentsshcli 0.5.0+ envoie automatiquement les identifiants chiffrés de la configuration via le stdin du canal SSH.
• Lorsque --su --json réussit, stderr peut encore contenir le texte Password: du message distant ; ce message ne contient pas le vrai mot de passe et ne signifie pas un échec d'authentification. Vous devez combiner le exitCode JSON et les sorties stdout comme whoami/id -u pour déterminer le résultat.
• Avant utilisation, vérifiez que la configuration de la connexion a privilegeEnabled: true et que l'utilisateur cible est configuré ; su nécessite toujours un mot de passe indépendant ; sudo, en l'absence de mot de passe disponible, prend en charge une politique distante NOPASSWD.

Écriture correcte :

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

Écriture incorrecte :

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

Format avec arguments nommés :

agentsshcli exec --connection "<nomConnexion>" --commande "<commande>" --directory "/root" --timeout 5000
agentsshcli exec --connection "<nomConnexion>" --commande-fichier "./script.sh" --timeout 5000
agentsshcli exec --no-cache --connection "<nomConnexion>" --commande "<commande>"

Paramètres :

• <nomConnexion>: Nom de connexion
• <commande>: Commande distante
• --connection <nom>, -c <nom>: Nom de connexion
• --commande <commande>: Commande distante
• --commande-fichier <chemin>: Lit le contenu d'un fichier local UTF-8 et l'exécute comme commande distante (pas un téléchargement puis exécution), adapté pour les scripts multi-lignes ; le fichier doit utiliser des sauts de ligne LF, PAS CRLF Windows ; ne peut pas être utilisé en même temps que --commande ou l'argument positionnel <commande>
• --directory <rép>, -d <rép>: Répertoire de travail distant
• --timeout <ms>, -t <ms>: Délai d'attente en millisecondes, par défaut 30000
• --pty: Alloue un pseudo-terminal pour cette commande, prioritaire sur la configuration
• --no-pty: N'alloue pas de pseudo-terminal pour cette commande, prioritaire sur la configuration
• --sudo: Utilise sudo pour l'élévation de privilèges, nécessite privilegeEnabled: true dans la configuration de connexion
• --su: Utilise su pour changer d'utilisateur, nécessite privilegeEnabled: true dans la configuration de connexion ; mutuellement exclusif avec --sudo
• --json: Produit une sortie structurée JSON (exitCode/stdout/stderr)
• --no-cache: Ne réutilise pas la connexion, doit être placé avant le nom de la connexion ou --connection
• --cache-ttl <ms>: Durée d'inactivité du cache de connexion en millisecondes, doit être placé avant le nom de la connexion ou --connection

Le mode d'élévation ne prend en charge que les commandes non interactives : la CLI envoie le mot de passe via le stdin du canal SSH puis ferme stdin ; la commande cible ne peut pas continuer à lire l'entrée. Si les identifiants sudo indépendants sont manquants, le mot de passe SSH peut être réutilisé ; en l'absence de mot de passe disponible, utilisez sudo -n non interactif, prenant en charge la politique distante NOPASSWD ou un cache d'authentification valide ; si un mot de passe est requis, la commande échoue immédiatement. Si une connexion par clé privée exige un mot de passe distant, configurez sudoPassword/sudoPasswordRef. Su nécessite toujours un mot de passe d'utilisateur cible indépendant.

Lors de l'utilisation de --commande-fichier, assurez-vous que le fichier de script utilise des sauts de ligne LF. Un fichier CRLF transmettra \r au bash distant, ce qui peut provoquer une erreur $'xxx\r': command not found.

Écriture recommandée sur macOS/Linux :

cat > /tmp/remote-command.sh <<'EOF'
pwd
EOF
agentsshcli exec --connection "<nomConnexion>" --commande-fichier /tmp/remote-command.sh

Écriture recommandée sur Windows PowerShell (forcer LF) :

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

Valeurs de retour :

• En cas de succès avec stdout, la sortie standard affiche le résultat de la commande distante
• En cas de succès sans stdout, rien n'est affiché
• Le code de sortie est 0
• Si la commande distante se termine avec un code non nul, si un délai d'attente est dépassé, si la commande est dans la liste noire, si elle n'est pas dans la liste blanche, ou si la connexion échoue, la sortie d'erreur standard affiche un message d'erreur et le code de sortie est 1
• En mode --json, la sortie est un JSON, où exitCode est le code de sortie réel de la commande distante (non nul signifie un échec de la commande), et stdout/stderr renvoient fidèlement la sortie distante ; en cas d'échec de la commande, le code de sortie du processus est 1

Remarques importantes :

• Lorsque vous utilisez pkill -f / pgrep -f dans une commande, le motif correspond correspondra au shell distant lui-même qui exécute la commande (la ligne de commande contient cette chaîne), ce qui entraînera la mort du shell, l'interruption de la commande et l'absence de sortie. Pour vous exclure, utilisez une astuce regex, par exemple pkill -f 'name[.]log'.
• Si une session distante est terminée anormalement (shell tué, etc.), une erreur [distant] Session terminée anormalement (pas d'état de sortie) sera signalée ; le succès ne sera pas renvoyé silencieusement.
• Si la commande démarre un processus d'arrière-plan à la fin et ne redirige pas stdout, le canal distant ne sera pas fermé et la commande attendra jusqu'au délai d'attente total ; pour une exécution en arrière-plan, redirigez stdout/stderr vers un fichier (par exemple, > /tmp/x.log 2>&1 < /dev/null &).
• Mettez la commande entre guillemets (par exemple --commande "<commande>" ou argument positionnel "<commande>") : des jetons comme --json, --timeout dans le contenu de la commande seront interprétés comme des paramètres de la CLI ; s'ils ne sont pas entre guillemets, ils peuvent être avalés ou provoquer une erreur.

upload

Transfère un fichier local vers le serveur distant.

Format avec arguments positionnels :

agentsshcli upload "<nomConnexion>" "<cheminLocal>" "<cheminDistant>"
agentsshcli upload --no-cache "<nomConnexion>" "<cheminLocal>" "<cheminDistant>"

Format avec arguments nommés :

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

Paramètres :

• <nomConnexion>: Nom de connexion
• <cheminLocal>: Chemin du fichier local
• <cheminDistant>: Chemin du fichier distant cible
• --connection <nom>, -c <nom>: Nom de connexion
• --local <chemin>, -l <chemin>: Chemin du fichier local
• --distant <chemin>, -r <chemin>: Chemin du fichier distant cible
• --timeout <ms>: Délai d'attente total en millisecondes, par défaut aucune limite (permet les longs temps d'exécution pour les gros fichiers), différent du délai par défaut de exec (30s)
• --recursive: Transfère récursivement un répertoire, en conservant les chemins relatifs ; les liens symboliques ne sont pas suivis : les liens vers des répertoires sont ignorés (pour éviter les boucles), les liens vers des fichiers sont transférés avec leur contenu
• --json: Produit une sortie structurée JSON
• --no-cache: Ne réutilise pas la connexion, doit être placé avant le nom de la connexion ou --connection
• --cache-ttl <ms>: Durée d'inactivité du cache de connexion en millisecondes, doit être placé avant le nom de la connexion ou --connection

Stabilité du transfert :

• Le transfert écrit d'abord dans un fichier temporaire distant <cheminDistant>.part, puis, après vérification, le renomme en fichier cible final.
• Un fichier <cheminDistant>.part.meta est également écrit pour les métadonnées de reprise ; si la taille, la date de modification ou la taille des blocs du fichier local changent, l'ancien fichier temporaire est supprimé et le transfert redémarre, évitant une concaténation erronée.
• Si le transfert est interrompu, le prochain transfert du même fichier local vers le même chemin distant reprendra à partir de la taille existante du fichier .part.
• En mode --no-cache, utilisez Ctrl+C pour arrêter le transfert en cours ; en mode daemon, utilisez stop-daemon pour arrêter brutalement le pool de connexions, mais cela affectera les autres tâches du même daemon ; ce n'est pas une annulation précise d'un seul transfert.

Valeurs de retour :

• En cas de succès, la sortie standard affiche Fichier transféré avec succès
• Le code de sortie est 0
• Le transfert d'un seul fichier ne crée pas de répertoire distant : si le répertoire cible n'existe pas (ou si un chemin du même nom est un fichier), l'erreur est Le répertoire distant n'existe pas ou est inaccessible : <rép> ; vous devez d'abord créer le répertoire, ou utiliser --recursive pour transférer un répertoire entier (le mode récursif crée automatiquement les répertoires)
• Si le fichier local n'existe pas, si l'écriture distante échoue ou si la connexion échoue, la sortie d'erreur standard affiche un message d'erreur et le code de sortie est 1
• En mode --json, en cas de succès, la sortie standard est {"exitCode":0,"stdout":"Fichier transféré avec succès","stderr":""} ; en cas d'échec, exitCode est 1

download

Télécharge un fichier distant vers le local.

Format avec arguments positionnels :

agentsshcli download "<nomConnexion>" "<cheminDistant>" "<cheminLocal>"
agentsshcli download --no-cache "<nomConnexion>" "<cheminDistant>" "<cheminLocal>"

Format avec arguments nommés :

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

• <nomConnexion>: Nom de connexion
• <cheminDistant>: Chemin du fichier distant
• <cheminLocal>: Chemin du fichier local cible
• --connection <nom>, -c <nom>: Nom de connexion
• --distant <chemin>, -r <chemin>: Chemin du fichier distant
• --local <chemin>, -l <chemin>: Chemin du fichier local cible
• --timeout <ms>: Délai d'attente total en millisecondes, par défaut aucune limite (permet les longs temps d'exécution pour les gros fichiers), différent du délai par défaut de exec (30s)
• --recursive: Télécharge récursivement un répertoire, en conservant les chemins relatifs ; les liens symboliques distants sont ignorés
• --json: Produit une sortie structurée JSON
• --no-cache: Ne réutilise pas la connexion, doit être placé avant le nom de la connexion ou --connection
• --cache-ttl <ms>: Durée d'inactivité du cache de connexion en millisecondes, doit être placé avant le nom de la connexion ou --connection

Stabilité du téléchargement :

• Le téléchargement écrit d'abord dans un fichier temporaire local <cheminLocal>.part, et écrit <cheminLocal>.part.meta pour les métadonnées de reprise ; après vérification de la taille, il renomme le fichier en fichier cible final.
• Si le téléchargement est interrompu, le prochain téléchargement du même fichier distant vers le même chemin local reprendra à partir de la taille existante du fichier .part ; si les caractéristiques du fichier distant changent, l'ancien fichier .part est automatiquement supprimé et le téléchargement redémarre.

Valeurs de retour :

• En cas de succès, la sortie standard affiche Fichier téléchargé avec succès
• Le code de sortie est 0
• Si l'écriture locale échoue, si la lecture distante échoue ou si la connexion échoue, la sortie d'erreur standard affiche un message d'erreur et le code de sortie est 1
• En mode --json, en cas de succès, la sortie standard est {"exitCode":0,"stdout":"Fichier téléchargé avec succès","stderr":""} ; en cas d'échec, exitCode est 1

stop-daemon

Arrête le processus de cache SSH (pool de connexions) correspondant au fichier de configuration actuel. C'est une commande de maintenance du pool de connexions, pas une annulation précise d'une seule tâche de transfert ; elle affectera les autres tâches du même daemon :

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

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

Valeurs de retour :

• En cas de succès de help, la sortie standard affiche le texte d'aide, code de sortie 0
• En cas de succès de version, la sortie standard affiche le numéro de version, code de sortie 0

Règles d'erreur

...

[Contenu tronqué pour la traduction]