Carrot404/agent-ssh-cli

Instrucciones de uso de agent-ssh-cli

agentsshcli es una herramienta de línea de comandos instalada a través de npm, con un ejecutor nativo en Rust para operaciones SSH, diseñada para que la IA o el usuario operen servidores remotos de forma segura utilizando configuraciones locales.

Lo que puede hacer:

• Listar las conexiones SSH de la configuración local
• Ejecutar comandos en un servidor remoto especificado
• Registrar la clave pública del host SSH en el known_hosts local utilizando la huella SHA256 confirmada explícitamente por el usuario
• Subir archivos locales al servidor remoto
• Descargar archivos del servidor remoto al local
• Limitar los comandos ejecutables mediante listas blancas y negras
• Cachear conexiones SSH durante un breve período mediante un daemon de Rust, reduciendo la sobrecarga de conexiones repetidas en operaciones consecutivas
• Gestionar conexiones, referencias de credenciales y políticas de seguridad a través de un editor visual que solo escucha en la interfaz de bucle local
• La instalación mediante npm descarga automáticamente el paquete precompilado opcional según el sistema actual; actualmente compatible con macOS arm64/x64, Linux x64/arm64, Windows x64

Lo que NO hace:

• No muestra contraseñas en texto plano, claves privadas ni otra información de autenticación sensible; las contraseñas se pueden guardar cifradas en el secrets.json local y se envían solo a través del stdin del canal SSH
• No escanea la red ni descubre servidores; solo utiliza las conexiones del archivo de configuración
• No elude las restricciones de comandos de la configuración

Las listas blancas y negras de comandos usan sintaxis de expresiones regulares de JavaScript, no POSIX. Los caracteres de espacio en blanco deben escribirse como \s, no como [:space:]. Por ejemplo:

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

Confirmación de seguridad

Antes de ejecutar operaciones peligrosas, se debe obtener la confirmación del usuario; no se pueden ejecutar directamente.

Las operaciones peligrosas incluyen:

• Eliminar, vaciar o sobrescribir archivos o directorios, por ejemplo rm, truncate, redirección de sobrescritura, eliminación masiva
• Limpiar cachés, registros, directorios temporales o datos de negocio
• Reiniciar, apagar, detener servicios o matar procesos, por ejemplo reboot, shutdown, systemctl stop, kill
• Modificar permisos, propietario, configuración del sistema o elementos de inicio, por ejemplo chmod, chown, editar archivos en /etc
• Subir archivos que sobrescriban archivos existentes en el remoto
• Descargar archivos que sobrescriban archivos existentes en el local
• Cualquier operación irreversible que afecte a servicios en línea o a la integridad de los datos

Al confirmar, se debe indicar el nombre de la conexión objetivo, el comando o la ruta del archivo, el posible impacto y esperar el consentimiento explícito del usuario antes de ejecutar.

Validación del entorno

Antes de llamar al CLI, verifique prioritariamente que el CLI esté disponible:

agentsshcli --help

Si el comando anterior falla, verifique el entorno base:

node --version
npm --version

Si node o npm no existen, indique al usuario que instale Node.js >= 18 y npm >= 8.

Una vez que el CLI esté disponible, verifique si existe el archivo de configuración:

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

Si el archivo de configuración no existe, indique al usuario que lo cree; no continúe ejecutando comandos SSH:

mkdir -p ~/.agent-ssh-cli
# Luego pida al usuario que edite ~/.agent-ssh-cli/config.json e incluya la configuración real del servidor

Archivo de configuración predeterminado:

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

Todas las conexiones SSH (incluyendo las de servidores intermedios y las "pruebas de conexión" del editor) verifican ~/.ssh/known_hosts según el nombre de host y el puerto de la configuración. En la primera conexión sin registro, informe al usuario sobre el nombre de la conexión objetivo, el host y el puerto, la huella SHA256 recibida, y el riesgo de que la primera confianza pueda conectar a un servidor incorrecto o sufrir un ataque de intermediario; una vez que el usuario confirme explícitamente, se puede usar trust-host para registrar (para puertos no estándar, [host]:port), sin requerir verificación independiente desde la consola o registros de operaciones. Si el usuario ya ha indicado explícitamente "confiar" o "directo trust" para el objetivo actual, se considera autorizado; no pida confirmación repetidamente ni lo rechace por falta de verificación independiente. No confíe automáticamente sin confirmación del usuario; si la clave pública existente cambia, se debe investigar el conflicto, no sobrescribir automáticamente los registros antiguos.

Se recomienda usar agentsshcli edit-config para reemplazar contraseñas: al guardar en el editor, la nueva contraseña se cifra y se escribe en secrets.json, mientras que el archivo de configuración solo conserva passwordRef. La configuración antigua aún admite migración pasiva: si la conexión contiene una password en texto plano no vacía, la próxima vez que se ejecute exec, upload o download, se generará secret.key, se cifrará la contraseña y se reemplazará el campo de texto plano por una referencia. No muestre contraseñas en texto plano en la conversación, registros o salida de comandos.

La página "Límites de permisos" del editor permite configurar y ver la contraseña de sudo / su: la primera vez que se introduce, se genera una referencia independiente por nombre de conexión; al guardar, solo se escribe el texto cifrado en secrets.json; si no se ha configurado una contraseña de sudo por separado, el campo indicará que al ejecutar --sudo se reutilizará la contraseña SSH.

trust-host

El primer registro debe obtener la confirmación explícita del usuario; la verificación independiente de la huella es un método recomendado, no un requisito previo para el registro. Se puede usar la huella SHA256 devuelta en el error de la primera conexión del CLI, o obtener la huella mediante sondeo de clave pública sin enviar credenciales de autenticación, y luego confirmar y registrar según las reglas anteriores:

agentsshcli trust-host --fingerprint 'SHA256:<huella_confirmada_por_usuario>' '<nombreConexion>'
agentsshcli trust-host --config /ruta/a/config.json --fingerprint 'SHA256:<huella_confirmada_por_usuario>' '<nombreConexion>'

• --fingerprint es obligatorio, solo acepta huellas SHA256 completas, y debe colocarse antes del nombre de la conexión; --config se coloca antes de este.
• El comando realiza el handshake a través de la ruta original de la conexión (directa, SOCKS5 o mediante servidor intermedio), sin autenticar la máquina objetivo ni ejecutar comandos. Si el servidor intermedio no está registrado, primero obtenga la confirmación del usuario y regístrelo.
• Si la huella no coincide o ya existe una clave pública diferente, se rechaza la escritura, sin sobrescribir registros antiguos; si la misma clave pública ya está registrada, no se añade de nuevo. Solo se escribe en ~/.ssh/known_hosts cuando la huella proporcionada coincide con la clave pública del handshake y no hay un registro de ese host.
• La huella devuelta por ssh-keyscan o la primera conexión puede ser el objeto de confirmación del usuario, pero no se puede afirmar que ya han verificado la identidad del servidor de forma independiente. Después de la confirmación del usuario, se puede registrar; no se debe rechazar por falta de verificación independiente; si el registro falla, verifique el error específico sin usar parámetros que omitan la verificación.

edit-config / stop-editor

Gestiona las conexiones SSH mediante el editor visual local:

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

Reglas de llamada:

• Cuando el usuario solicite abrir, editar o gestionar visualmente la configuración SSH, ejecute directamente edit-config; no llame internamente al subcomando __editor ni construya manualmente una API HTTP.
• El editor solo escucha en 127.0.0.1 y abre automáticamente el navegador al iniciarse. Solo se ejecuta una instancia por ruta de configuración; la ejecución repetida abre la instancia existente.
• El fragmento de URL local que el CLI muestra en stdout contiene un token temporal; debe tratarse como una credencial y no escribirse en registros, tickets de soporte ni mensajes externos; solo se proporciona en la sesión local actual si el usuario necesita explícitamente acceso manual a la dirección.
• Si durante 10 minutos consecutivos no hay una API válida autenticada o eventos reales de pointerdown, keydown o input, el editor se cierra automáticamente y elimina el archivo de estado. Si la página caduca, vuelva a ejecutar edit-config.
• stop-editor solo detiene el editor local correspondiente a esa configuración; no detiene el daemon SSH, las conexiones en caché ni las tareas remotas.
• No ejecute stop-editor por iniciativa propia cuando el usuario pueda tener cambios no guardados en la página; llámelo solo si el usuario solicita explícitamente detenerlo o ha confirmado que puede descartar los cambios no guardados.
• edit-config / stop-editor aceptan --config, --help y --version; no aceptan --no-cache, --cache-ttl ni argumentos posicionales.
• El archivo de configuración puede ser modificado por otro proceso; si al guardar se detecta un conflicto de hash, recargue primero, sin omitir la verificación de hash ni sobrescribir directamente.
• El panel JSON admite "Global/Conexión actual" y "Vista previa/Código fuente"; la validación del backend es el contrato final de configuración, y las indicaciones del frontend no pueden reemplazar el resultado del guardado.
• La "Prueba de conexión" de la página realiza un handshake SSH y autenticación (incluyendo contraseñas en borrador no guardadas) con el borrador actual y los servidores intermedios relevantes; una vez completada, se desconecta, sin guardar la configuración ni ejecutar comandos; solo se puede realizar una prueba a la vez.
• Ver una contraseña la descifra el backend local; el texto plano solo se muestra brevemente en la página y se borra después de 15 segundos; no extraiga contraseñas a través del terminal, scripts o interfaces de depuración HTTP.
• Para reemplazar una contraseña, use la operación de reemplazo de la página; al guardar, config.json solo conserva passwordRef, y el texto cifrado se escribe en secrets.json en el mismo directorio. Copiar una conexión no copia la referencia de contraseña.
• El editor no muestra controles de PTY a nivel de conexión, pero transmite el pty existente; al ejecutar comandos, siga usando exec --pty / --no-pty para sobrescribir temporalmente.

Comportamiento de retorno:

• Si edit-config tiene éxito, stdout muestra Editor de configuración abierto: <url-local>, y el código de salida es 0. Si falla al abrir el navegador, el mensaje de error incluye la URL local a la que se puede acceder manualmente.
• Si stop-editor tiene éxito, stdout muestra Editor de configuración detenido; si no hay un servicio correspondiente, muestra El editor de configuración no está en ejecución, con código de salida 1.
• Si hay conflictos de guardado en el editor, fallos de validación de configuración o referencias de credenciales incompletas, no se debe modificar la configuración original; maneje según el error específico de la página o stderr.

Ejemplo de configuración con contraseña oculta:

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

Campos completos del archivo de configuración (cada ítem es un servidor único por name):

• name: Nombre de la conexión, debe ser único
• group / tags: Agrupación opcional de un solo nivel y arreglo de etiquetas; el editor admite visualización por grupo o etiqueta; las etiquetas se limpian de espacios y se deduplican
• host / port / username: Host SSH, puerto (por defecto 22), nombre de usuario
• password / passwordRef / privateKey: Métodos de autenticación; solo se puede mantener uno de los tres; passphrase solo se usa junto con privateKey
• jumpHost: Nombre de conexión del servidor intermedio; debe ser el name de otra máquina en el archivo de configuración; al conectar, primero establece SSH al servidor intermedio y luego llega a la máquina objetivo a través de un canal directo
• socksProxy: Dirección del proxy SOCKS5, por ejemplo socks5://127.0.0.1:1080; también se puede omitir el protocolo y escribir 127.0.0.1:1080
• pty: Si se asigna un pseudo-terminal por defecto; exec --pty / --no-pty pueden sobrescribir temporalmente
• privilegeEnabled: Si se permite exec --sudo/--su, por defecto false
• sudoUser: Usuario objetivo de sudo, por defecto root; sudoPassword/sudoPasswordRef guarda la contraseña de sudo del usuario SSH actual; si falta, se puede reutilizar la contraseña SSH
• suUser: Usuario objetivo de su, por defecto root; suPassword/suPasswordRef debe guardar la contraseña del usuario objetivo
• commandWhitelist / commandBlacklist: Arreglos de expresiones regulares para listas blancas/negras de comandos

Ejemplo con servidor intermedio:

[
  {
    "name": "Máquina objetivo",
    "host": "10.0.0.5",
    "username": "root",
    "passwordRef": "agentsshcli:Máquina objetivo",
    "jumpHost": "Servidor intermedio"
  },
  {
    "name": "Servidor intermedio",
    "host": "203.0.113.10",
    "port": 22,
    "username": "ubuntu",
    "privateKey": "/ruta/a/jump_key"
  }
]

Especificar otro archivo de configuración:

AGENT_SSH_CONFIG=/ruta/a/config.json agentsshcli list

Si el CLI no está disponible pero Node/npm funcionan, indique al usuario que lo instale:

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

Para desarrollo desde código fuente o depuración local, primero debe construir el ejecutor nativo Rust:

npm run build:native
npm test

Parámetros globales

• --config <ruta>: Especifica la ruta del archivo de configuración, con prioridad sobre la configuración predeterminada
• --help, -h: Muestra la ayuda
• --version, -v: Muestra la versión

exec, upload y download usan por defecto la caché de conexiones del daemon de Rust para reducir la sobrecarga de handshake y autenticación SSH en operaciones consecutivas; solo si se pasa --no-cache se salta la caché y se conecta directamente. Los parámetros relacionados con la caché son:

• --no-cache: Salta la caché de conexiones del daemon de Rust; este comando establece y cierra la conexión de forma independiente, modo de conexión directa
• --cache-ttl <ms>: Establece los milisegundos de inactividad de la caché de conexiones del daemon de Rust; por defecto 180000
• --json: exec, upload y download producen JSON estructurado (campos exitCode/stdout/stderr), ideal para scripts y la IA

Todos los parámetros (--no-cache, --cache-ttl, --json, --timeout, --pty, etc.) deben colocarse antes del nombre de la conexión (primer argumento posicional); se pueden mezclar en cualquier orden entre sí; si se colocan después del nombre de la conexión, se tratarán como parte del contenido del comando y se generará un error de "parámetro no soportado"; los comandos deben ir entre comillas.

init-config

Genera el archivo de configuración predeterminado en ~/.agent-ssh-cli/config.json (no sobrescribe si ya existe):

agentsshcli init-config

list

Lista los servidores de la configuración.

agentsshcli list
agentsshcli list --json
agentsshcli list --group Producción --tag Aplicación

Parámetros:

• --json: Salida en formato JSON. Actualmente, la salida predeterminada también es JSON.
• --config <ruta>: Especifica el archivo de configuración
• --group <grupo> / --tag <etiqueta>: Filtrado exacto con distinción entre mayúsculas y minúsculas; si se usan ambos, se toma la intersección

Valores de retorno:

• En caso de éxito, stdout muestra un arreglo de servidores con name, host, port, username, group, tags; si hay servidor intermedio, también jumpHost; si no hay coincidencias, muestra []
• No muestra contraseñas, claves privadas, passphrase, listas blancas/negras ni otros campos sensibles o de control
• Código de salida 0

Ejemplo de salida:

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

exec

Ejecuta comandos en remoto.

Forma de argumentos posicionales:

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

Reglas de elevación de privilegios sudo/su

Cuando el usuario solicite ejecutar comandos con sudo, su, como root o cambiando de usuario a través de una conexión no root existente, se deben usar los parámetros de nivel superior del CLI --sudo o --su; no se debe recurrir a comandos interactivos remotos.

• --sudo/--su deben colocarse antes del nombre de la conexión o de --connection.
• Está prohibido incluir sudo, sudo -S, sudo -n, su o su -c en <command>; esta práctica elude el canal de contraseñas de elevación del CLI y puede esperar entrada interactiva o hacer que el comando falle porque la herramienta no admite contraseñas.
• No se debe concluir que agentsshcli no puede responder a las indicaciones de contraseña solo porque un su -c normal agote el tiempo de espera; agentsshcli 0.5.0+ envía automáticamente las credenciales cifradas de la configuración a través del stdin del canal SSH.
• Cuando --su --json tiene éxito, stderr puede contener texto de indicación de Password: del remoto; esta indicación no contiene la contraseña real ni significa que la autenticación haya fallado. Se debe evaluar el resultado combinando el exitCode JSON y el whoami/id -u en stdout.
• Antes de usar, verifique que la configuración de la conexión tenga privilegeEnabled: true y que el usuario objetivo esté configurado; su requiere una contraseña independiente; si sudo no tiene contraseña disponible, se admite la política remota de NOPASSWD.

Escritura correcta:

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

Escritura incorrecta:

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

Forma de parámetros con nombre:

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

Parámetros:

• <nombreConexion>: Nombre de la conexión
• <comando>: Comando remoto
• --connection <nombre>, -c <nombre>: Nombre de la conexión
• --command <comando>: Comando remoto
• --command-file <ruta>: Lee el contenido de un archivo local UTF-8 y lo ejecuta como comando remoto (no lo sube primero); adecuado para scripts multilínea; el archivo debe usar saltos de línea LF, no CRLF de Windows; no se puede usar junto con --command o el argumento posicional <comando>
• --directory <dir>, -d <dir>: Directorio de trabajo remoto
• --timeout <ms>, -t <ms>: Valor de tiempo de espera en milisegundos; por defecto 30000
• --pty: Asigna un pseudo-terminal para este comando; tiene prioridad sobre el archivo de configuración
• --no-pty: No asigna pseudo-terminal para este comando; tiene prioridad sobre el archivo de configuración
• --sudo: Ejecuta con elevación de privilegios mediante sudo; requiere que la conexión tenga privilegeEnabled: true
• --su: Ejecuta cambiando de usuario mediante su; requiere que la conexión tenga privilegeEnabled: true; es mutuamente excluyente con --sudo
• --json: Salida JSON estructurada (exitCode/stdout/stderr)
• --no-cache: No reutiliza la conexión; debe colocarse antes del nombre de la conexión o de --connection
• --cache-ttl <ms>: Milisegundos de inactividad de la caché de conexiones; debe colocarse antes del nombre de la conexión o de --connection

El modo de elevación solo admite comandos no interactivos: el CLI envía la contraseña a través del stdin del canal SSH y luego cierra stdin; el comando objetivo no puede seguir leyendo entrada. Si faltan las credenciales independientes de sudo, se puede reutilizar la contraseña SSH; si no hay contraseña disponible, se usa sudo -n no interactivo, que admite NOPASSWD remoto o caché de autenticación válida; si se necesita una contraseña, falla inmediatamente. Si se usa inicio de sesión con clave privada y el remoto requiere contraseña, se debe configurar sudoPassword/sudoPasswordRef. su siempre requiere una contraseña independiente del usuario objetivo.

Al usar --command-file, asegúrese de que el archivo de script tenga saltos de línea LF. Un archivo CRLF enviará \r a bash en el remoto, lo que puede provocar errores como $'xxx\r': command not found.

Escritura recomendada en macOS/Linux:

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

Escritura recomendada en Windows PowerShell (LF explícito):

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

Valores de retorno:

• En caso de éxito con stdout, stdout muestra el resultado del comando remoto
• En caso de éxito sin stdout, no se muestra contenido
• Código de salida 0
• Si el comando remoto sale con código distinto de cero, hay tiempo de espera, coincide con la lista negra, no coincide con la lista blanca o falla la conexión, stderr muestra el mensaje de error y el código de salida es 1
• En modo --json, la salida es JSON; exitCode es el código de salida real del comando remoto (distinto de cero indica fallo del comando), stdout/stderr devuelven fielmente la salida remota; cuando el comando falla, el código de salida del proceso sigue siendo 1

Notas:

• Al usar pkill -f / pgrep -f en el comando, la cadena de coincidencia también afectará al shell remoto que ejecuta el comando (la línea de comandos contiene esa cadena), lo que puede matar el shell, interrumpir el comando y no producir salida. Para excluirse a sí mismo, use trucos de expresiones regulares, como pkill -f 'name[.]log'.
• Si la sesión remota se termina de forma anómala (shell muerto, etc.), se mostrará [remoto] Sesión terminada de forma anómala (sin estado de salida), sin devolver silenciosamente éxito.
• Si el comando inicia un proceso en segundo plano al final sin redirigir stdout, el remoto no cerrará el canal y el comando esperará hasta el tiempo de espera total; para ejecución en segundo plano, redirija stdout/stderr a un archivo (por ejemplo, > /tmp/x.log 2>&1 < /dev/null &).
• Los comandos deben ir entre comillas (por ejemplo, --command "<comando>" o argumento posicional "<comando>"): tokens como --json o --timeout dentro del contenido del comando se analizarán como parámetros del CLI y, si no están entre comillas, pueden ser malinterpretados o provocar errores.

upload

Sube archivos locales al remoto.

Forma de argumentos posicionales:

agentsshcli upload "<nombreConexion>" "<rutaLocal>" "<rutaRemota>"
agentsshcli upload --no-cache "<nombreConexion>" "<rutaLocal>" "<rutaRemota>"

Forma de parámetros con nombre:

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

Parámetros:

• <nombreConexion>: Nombre de la conexión
• <rutaLocal>: Ruta del archivo local
• <rutaRemota>: Ruta del archivo remoto de destino
• --connection <nombre>, -c <nombre>: Nombre de la conexión
• --local <ruta>, -l <ruta>: Ruta del archivo local
• --remote <ruta>, -r <ruta>: Ruta del archivo remoto de destino
• --timeout <ms>: Tiempo de espera total en milisegundos; por defecto sin límite (permite ejecución prolongada para archivos grandes), diferente del valor predeterminado de 30s de exec
• --recursive: Sube directorios de forma recursiva, manteniendo rutas relativas; no sigue enlaces simbólicos: salta enlaces a directorios (evita bucles), sube el contenido de enlaces a archivos
• --json: Salida JSON estructurada
• --no-cache: No reutiliza la conexión; debe colocarse antes del nombre de la conexión o de --connection
• --cache-ttl <ms>: Milisegundos de inactividad de la caché de conexiones; debe colocarse antes del nombre de la conexión o de --connection

Estabilidad de subida:

• La subida primero escribe en un archivo temporal <rutaRemota>.part en el remoto; una vez completada la verificación, se renombra al archivo de destino final.
• También escribe metadatos de reanudación en <rutaRemota>.part.meta; si el tamaño del archivo local, la fecha de modificación o el tamaño del bloque cambian, se elimina el archivo temporal antiguo y se vuelve a subir, evitando concatenaciones incorrectas.
• Si la subida se interrumpe, la próxima vez que se suba el mismo archivo local a la misma ruta remota, se reanudará desde el tamaño existente de .part.
• En modo --no-cache, se puede usar Ctrl+C para detener la subida actual; en modo daemon, se puede usar stop-daemon para detener bruscamente el pool de conexiones, pero esto afecta a otras tareas dentro del mismo daemon, no es una cancelación precisa de una sola subida.

Valores de retorno:

• En caso de éxito, stdout muestra File uploaded successfully
• Código de salida 0
• Si el directorio remoto no existe (o una ruta con el mismo nombre es un archivo), se muestra directamente El directorio remoto no existe o no es accesible: <dir>; debe crear primero el directorio o usar --recursive para subir todo el directorio (el modo recursivo crea directorios automáticamente)
• Si el archivo local no existe, falla la escritura remota o falla la conexión, stderr muestra el mensaje de error y el código de salida es 1
• En modo --json, en caso de éxito, stdout es {"exitCode":0,"stdout":"File uploaded successfully","stderr":""}; en caso de fallo, exitCode es 1

download

Descarga archivos remotos al local.

Forma de argumentos posicionales:

agentsshcli download "<nombreConexion>" "<rutaRemota>" "<rutaLocal>"
agentsshcli download --no-cache "<nombreConexion>" "<rutaRemota>" "<rutaLocal>"

Forma de parámetros con nombre:

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

• <nombreConexion>: Nombre de la conexión
• <rutaRemota>: Ruta del archivo remoto
• <rutaLocal>: Ruta del archivo local de destino
• --connection <nombre>, -c <nombre>: Nombre de la conexión
• --remote <ruta>, -r <ruta>: Ruta del archivo remoto
• --local <ruta>, -l <ruta>: Ruta del archivo local de destino
• --timeout <ms>: Tiempo de espera total en milisegundos; por defecto sin límite (permite ejecución prolongada para archivos grandes), diferente del valor predeterminado de 30s de exec
• --recursive: Descarga directorios de forma recursiva, manteniendo rutas relativas; salta enlaces simbólicos remotos
• --json: Salida JSON estructurada
• --no-cache: No reutiliza la conexión; debe colocarse antes del nombre de la conexión o de --connection
• --cache-ttl <ms>: Milisegundos de inactividad de la caché de conexiones; debe colocarse antes del nombre de la conexión o de --connection

Estabilidad de descarga:

• La descarga primero escribe en un archivo temporal <rutaLocal>.part en el local, y también escribe metadatos de reanudación en <rutaLocal>.part.meta; una vez completada, verifica el tamaño y renombra al archivo final.
• Si la descarga se interrumpe, la próxima vez que se descargue el mismo archivo remoto a la misma ruta local, se reanudará desde el tamaño existente de .part; si las características del archivo remoto cambian, se elimina automáticamente el .part antiguo y se descarga de nuevo.

Valores de retorno:

• En caso de éxito, stdout muestra File downloaded successfully
• Código de salida 0
• Si falla la escritura local, la lectura remota o la conexión, stderr muestra el mensaje de error y el código de salida es 1
• En modo --json, en caso de éxito, stdout es {"exitCode":0,"stdout":"File downloaded successfully","stderr":""}; en caso de fallo, exitCode es 1

stop-daemon

Detiene el proceso de caché SSH (pool de conexiones) correspondiente al archivo de configuración actual. Es un comando de mantenimiento del pool de conexiones, no una cancelación precisa de una sola tarea de subida; afecta a otras tareas dentro del mismo daemon:

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

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

Valores de retorno:

• En caso de éxito con help, stdout muestra el texto de ayuda, código de salida 0
• En caso de éxito con version, stdout muestra el número de versión, código de salida 0

Reglas de error

… [truncado para traducción]