Carrot404/agent-ssh-cli

Manual de Uso do agent-ssh-cli

agentsshcli é uma ferramenta de linha de comando instalada via npm, com um executor nativo em Rust para operações SSH, projetada para permitir que IAs ou usuários operem servidores remotos com segurança através de configurações locais.

O que ela pode fazer

• Listar conexões SSH da configuração local
• Executar comandos em servidores remotos específicos
• Registrar a chave pública do host SSH no known_hosts local usando a impressão digital SHA256 confirmada explicitamente pelo usuário
• Enviar arquivos locais para servidores remotos
• Baixar arquivos de servidores remotos para o local
• Restringir comandos executáveis através de listas de permissão/negação
• Usar um daemon Rust para armazenar conexões SSH em cache por um curto período, reduzindo a sobrecarga de reconexão em operações consecutivas
• Gerenciar conexões, referências de credenciais e políticas de segurança através de um editor visual que escuta apenas no endereço de loopback local
• A instalação via npm baixa automaticamente o pacote pré-compilado opcional para a plataforma atual. Atualmente suporta macOS arm64/x64, Linux x64/arm64 e Windows x64

O que ela não faz

• Não exibe senhas em texto puro, chaves privadas ou outras informações de autenticação sensíveis; senhas podem ser criptografadas conforme a configuração e salvas no secrets.json local, sendo enviadas apenas via stdin do canal SSH
• Não escaneia a rede ou descobre servidores; usa apenas as conexões do arquivo de configuração
• Não ignora as restrições de comando definidas na configuração

Listas de permissão/negação de comandos usam sintaxe JavaScript RegExp, não expressões regulares POSIX. Caracteres de espaço em branco devem ser escritos como \s, não [:space:]. Por exemplo:

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

Confirmação de Segurança

Antes de executar operações perigosas, é necessário obter a confirmação do usuário; elas não podem ser executadas diretamente.

Operações perigosas incluem:

• Excluir, limpar ou sobrescrever arquivos ou diretórios, por exemplo rm, truncate, redirecionamento para sobrescrever, exclusão em lote
• Limpar cache, logs, diretórios temporários ou dados de negócio
• Reiniciar, desligar, parar serviços ou matar processos, por exemplo reboot, shutdown, systemctl stop, kill
• Modificar permissões, proprietários, configurações do sistema ou itens de inicialização, por exemplo chmod, chown, editar arquivos em /etc
• Enviar arquivos que sobrescrevem arquivos existentes no remoto
• Baixar arquivos que sobrescrevem arquivos existentes no local
• Qualquer operação irreversível, que afete serviços online ou a integridade dos dados

Ao confirmar, é necessário especificar o nome da conexão alvo, o comando ou caminho do arquivo, o possível impacto, e aguardar a autorização explícita do usuário antes de executar.

Verificação de Ambiente

Antes de chamar a CLI, verifique se ela está disponível:

agentsshcli --help

Se o comando acima falhar, verifique o ambiente base:

node --version
npm --version

Se node ou npm não existirem, avise o usuário para instalar Node.js >= 18 e npm >= 8.

Depois que a CLI estiver disponível, verifique se o arquivo de configuração existe:

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

Se o arquivo de configuração não existir, avise o usuário para criá-lo e não prossiga com comandos SSH:

mkdir -p ~/.agent-ssh-cli
# Em seguida, peça ao usuário para editar ~/.agent-ssh-cli/config.json e preencher com configurações reais do servidor

Arquivo de configuração padrão:

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

Todas as conexões SSH (incluindo jump hosts e "teste de conexão" do editor) verificam ~/.ssh/known_hosts com base no nome do host e porta da configuração. Na primeira conexão, se o host não estiver registrado, informe ao usuário o nome da conexão alvo, host e porta, a impressão digital SHA256 recebida, e os riscos de confiar pela primeira vez (como conectar ao servidor errado ou sofrer um ataque MitM). Após a confirmação explícita do usuário, use trust-host para registrar (para portas diferentes de 22, use [host]:port). Não é obrigatório verificar independentemente do console ou registros de operação. Se o usuário já concordou explicitamente com "confiar", "trust" ou termos similares para o alvo, considere autorizado e não peça confirmação repetidamente ou recuse com base em falta de verificação independente. Nunca confie automaticamente sem a confirmação do usuário; se a chave pública existente mudar, investigue o conflito e não sobrescreva o registro antigo automaticamente.

Recomenda-se usar agentsshcli edit-config para substituir senhas: quando o editor salva, a nova senha é criptografada e escrita em secrets.json, e o arquivo de configuração mantém apenas um passwordRef. A configuração antiga ainda é suportada para migração passiva: se uma conexão contiver uma password em texto puro não vazia, na próxima execução de exec, upload ou download, um secret.key será gerado, a senha será criptografada e o campo de texto puro será substituído pela referência. Não exiba senhas em texto puro em conversas, logs ou saída de comandos.

A página "Limites de Permissão" do editor pode definir e visualizar senhas sudo/su: na primeira entrada, uma referência independente é gerada por nome de conexão; após salvar, apenas o texto cifrado é escrito em secrets.json; se nenhuma senha sudo for configurada separadamente, o campo indica que a senha SSH será reutilizada ao executar --sudo.

trust-host

O primeiro registro deve obter a confirmação explícita do usuário; a verificação independente da impressão digital é uma forma recomendada, não um pré-requisito para o registro. A impressão digital SHA256 retornada no erro da primeira conexão da CLI, ou obtida via sondagem de chave pública sem enviar credenciais de autenticação, pode ser usada. Em seguida, confirme e registre conforme as regras acima:

agentsshcli trust-host --fingerprint 'SHA256:<impressão digital confirmada pelo usuário>' '<nome da conexão>'
agentsshcli trust-host --config /path/to/config.json --fingerprint 'SHA256:<impressão digital confirmada pelo usuário>' '<nome da conexão>'

• --fingerprint é obrigatório e aceita apenas a impressão digital SHA256 completa; deve ser colocado antes do nome da conexão; --config deve ser colocado antes dele.
• O comando completa o handshake através do caminho de conexão direta, SOCKS5 ou jump host da conexão original, sem autenticar o alvo ou executar comandos. Se o jump host não estiver registrado, obtenha a confirmação do usuário e registre o jump host primeiro.
• Se a impressão digital não corresponder ou se já houver uma chave pública diferente, a gravação é recusada e o registro antigo não é sobrescrito; se a mesma chave pública já estiver registrada, não é adicionada novamente. A gravação em ~/.ssh/known_hosts só ocorre se a impressão digital fornecida corresponder à chave do handshake e não houver registro para aquele host.
• A impressão digital retornada por ssh-keyscan ou pela primeira conexão pode ser o objeto da confirmação do usuário, mas não se pode afirmar que elas já verificaram independentemente a identidade do servidor. Após a confirmação do usuário, o registro pode ser feito; não recuse por falta de verificação independente. Se o registro falhar, verifique o erro específico e não use parâmetros que ignorem a verificação.

edit-config / stop-editor

Use o editor visual local para gerenciar conexões SSH:

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

Regras de chamada:

• Quando o usuário solicitar abrir, editar ou gerenciar visualmente a configuração SSH, execute edit-config diretamente; não chame internamente o subcomando __editor ou monte a API HTTP manualmente.
• O editor escuta apenas em 127.0.0.1 e abre automaticamente o navegador ao iniciar. Apenas uma instância é executada por caminho de configuração; execuções repetidas abrem a instância existente.
• O fragmento de URL local na saída da CLI contém um token temporário, que deve ser tratado como uma credencial; não o escreva em logs, tickets ou mensagens externas. Forneça-o na sessão local atual apenas se o usuário precisar explicitamente acessar o endereço manualmente.
• Se não houver API válida autenticada ou eventos reais de pointerdown, keydown ou input por 10 minutos consecutivos, o editor sai automaticamente e exclui o arquivo de estado. Se a página expirar, execute edit-config novamente.
• stop-editor para apenas o editor local correspondente a essa configuração; não para o daemon SSH, conexões em cache ou tarefas remotas.
• Não execute stop-editor por conta própria quando o usuário ainda pode ter modificações não salvas na página; chame-o apenas quando o usuário solicitar explicitamente a parada ou confirmar que pode descartar o conteúdo não salvo.
• edit-config / stop-editor suportam --config, --help e --version, mas não aceitam --no-cache, --cache-ttl ou argumentos posicionais.
• O arquivo de configuração pode ser modificado por outros processos; se houver conflito ao salvar, recarregue primeiro, sem ignorar a verificação de hash ou sobrescrever diretamente.
• O painel JSON suporta "Global / Conexão Atual" e "Visualização / Código Fonte"; a validação do backend é o contrato final de configuração, e dicas do frontend não substituem o resultado do salvamento.
• O "Teste de Conexão" da página realiza uma conexão SSH e autenticação (incluindo rascunhos de senha não salvos) com o rascunho atual e jump hosts relevantes; após a conclusão, a conexão é fechada sem salvar a configuração ou executar comandos; apenas um teste pode ser executado por vez.
• A visualização de senhas é descriptografada pelo backend local; o texto puro é exibido brevemente na página e limpo após 15 segundos; não extraia senhas via terminal, script ou interface de depuração HTTP.
• Para substituir senhas, use a operação de substituição da página; após salvar, o config.json mantém apenas passwordRef, e o texto cifrado é escrito no secrets.json no mesmo diretório. Copiar uma conexão não copia a referência de senha.
• O editor não exibe controles de PTY no nível da conexão, mas preserva o pty existente; ao executar comandos, use exec --pty / --no-pty para substituir temporariamente.

Comportamento de retorno:

• edit-config em caso de sucesso imprime no stdout Configurações abertas no editor: <local-url> e o código de saída é 0. Se a abertura do navegador falhar, a mensagem de erro inclui a URL local que pode ser acessada manualmente.
• stop-editor em caso de sucesso imprime no stdout Editor de configuração parado; se não houver serviço correspondente, retorna Editor de configuração não está em execução com código de saída 1.
• Em caso de conflito ao salvar, falha de validação de configuração ou referência de credencial incompleta, a configuração original não deve ser alterada; trate o erro específico na página ou stderr.

Exemplo de configuração com senha oculta:

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

Campos completos do arquivo de configuração (cada item é um servidor único pelo name):

• name: Nome da conexão, deve ser único
• group / tags: Grupo único opcional e array de tags; o editor suporta exibição por grupo ou tag; tags são limpas de espaços e duplicatas
• host / port / username: Host SSH, porta (padrão 22), nome de usuário
• password / passwordRef / privateKey: Método de autenticação, apenas um dos três pode ser mantido; passphrase é usado apenas com privateKey
• jumpHost: Nome da conexão do jump host, preencha com o name de outra máquina no arquivo de configuração; ao conectar, primeiro estabelece uma conexão SSH com o jump host e, em seguida, atinge o alvo através de um canal direto
• socksProxy: Endereço do proxy SOCKS5, por exemplo, socks5://127.0.0.1:1080; também pode ser escrito sem o protocolo como 127.0.0.1:1080
• pty: Se deve alocar um pseudo-terminal por padrão; exec --pty / --no-pty podem substituir temporariamente
• privilegeEnabled: Se permite exec --sudo/--su; padrão false
• sudoUser: Usuário alvo do sudo (padrão root); sudoPassword/sudoPasswordRef armazena a senha sudo do usuário SSH atual; se ausente, pode reutilizar a senha SSH
• suUser: Usuário alvo do su (padrão root); suPassword/suPasswordRef deve armazenar a senha do usuário alvo
• commandWhitelist / commandBlacklist: Arrays de expressões regulares para listas de permissão/negação de comandos

Exemplo de jump host:

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

Para especificar outro arquivo de configuração:

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

Se a CLI não estiver disponível, mas Node/npm estiverem, avise o usuário para instalar:

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

Para desenvolvimento a partir do código fonte ou depuração local, é necessário compilar o executor nativo Rust primeiro:

npm run build:native
npm test

Parâmetros Globais

• --config <caminho>: Especifica o caminho do arquivo de configuração, com prioridade sobre o padrão
• --help, -h: Exibe ajuda
• --version, -v: Exibe a versão

exec, upload e download usam por padrão o cache de conexão do daemon Rust para reduzir a sobrecarga de handshakes SSH repetidos e autenticação em operações consecutivas; apenas quando --no-cache é passado, o cache é ignorado e a conexão é direta. Os parâmetros relacionados ao cache são:

• --no-cache: Ignora o cache de conexão do daemon Rust; o comando atual estabelece e fecha a conexão de forma independente, ou seja, modo direto
• --cache-ttl <ms>: Define o tempo de inatividade em milissegundos para o cache de conexão do daemon Rust; padrão 180000
• --json: exec, upload e download produzem saída JSON estruturada (campos exitCode/stdout/stderr), facilitando a análise por scripts e IAs

Todos os parâmetros (--no-cache, --cache-ttl, --json, --timeout, --pty, etc.) devem ser colocados antes do nome da conexão (primeiro argumento posicional); podem ser misturados em qualquer ordem entre si. Se colocados após o nome da conexão, serão tratados como parte do comando e resultarão em erro "parâmetro não suportado". Use aspas para envolver comandos.

init-config

Gera o arquivo de configuração padrão em ~/.agent-ssh-cli/config.json (não sobrescreve se já existir):

agentsshcli init-config

list

Lista os servidores na configuração.

agentsshcli list
agentsshcli list --json
agentsshcli list --group Produção --tag App

Parâmetros:

• --json: Saída em formato JSON. Atualmente, a saída padrão também é JSON.
• --config <caminho>: Especifica o arquivo de configuração
• --group <grupo> / --tag <tag>: Filtro exato sensível a maiúsculas/minúsculas; quando ambos são fornecidos, é usada a interseção

Valor de retorno:

• Em caso de sucesso, stdout exibe um array de servidores contendo name, host, port, username, group, tags; se houver um jump host configurado, também inclui jumpHost; se não houver correspondência, exibe []
• Não exibe senhas, chaves privadas, frases secretas, listas de permissão/negação ou outros campos sensíveis ou de controle
• Código de saída é 0

Exemplo de saída:

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

exec

Executa um comando no remoto.

Forma de argumentos posicionais:

agentsshcli exec "<nome da conexão>" "<comando>"
agentsshcli exec --no-cache "<nome da conexão>" "<comando>"
agentsshcli exec --cache-ttl 60000 "<nome da conexão>" "<comando>"
agentsshcli exec --pty "<nome da conexão>" "<comando>"
agentsshcli exec --no-pty "<nome da conexão>" "<comando>"
agentsshcli exec --sudo "<nome da conexão>" "systemctl status app"
agentsshcli exec --su "<nome da conexão>" "id && pwd"

Regras de Elevação de Privilégios com sudo/su

Quando o usuário solicitar o uso de sudo, su, identidade root ou alternância de usuário alvo em uma conexão não-root existente, use os parâmetros de nível superior da CLI --sudo ou --su; não use comandos interativos remotos como alternativa.

• --sudo/--su devem ser colocados antes do nome da conexão ou de --connection.
• É proibido incluir sudo, sudo -S, sudo -n, su ou su -c no <comando>; essa abordagem ignora o canal de senha de privilégio da CLI, podendo aguardar entrada interativa ou ser interpretado incorretamente como falta de suporte a senha pela ferramenta.
• Não conclua que agentsshcli não consegue responder a prompts de senha porque su -c comum excede o tempo limite; agentsshcli 0.5.0+ envia automaticamente as credenciais criptografadas configuradas via stdin do canal SSH.
• Quando --su --json é bem-sucedido, stderr pode conter o prompt Password: remoto; esse prompt não contém a senha real e não indica falha de autenticação. A decisão deve ser baseada no JSON exitCode e no stdout contendo whoami/id -u.
• Antes de usar, verifique se a configuração da conexão tem privilegeEnabled: true e se o usuário alvo está configurado. Su requer uma senha independente; se não houver senha disponível para sudo, políticas de sudo sem senha no remoto podem ser suportadas.

Escrita correta:

agentsshcli exec --json --sudo "<nome da conexão>" "whoami; id -u"
agentsshcli exec --json --su "<nome da conexão>" "whoami; id -u"
agentsshcli exec --no-cache --json --su "<nome da conexão>" "id"

Escrita incorreta:

agentsshcli exec "<nome da conexão>" "su -c 'id'"
agentsshcli exec "<nome da conexão>" "sudo -S id"
agentsshcli exec "<nome da conexão>" "sudo -n id"

Forma de argumentos nomeados:

agentsshcli exec --connection "<nome da conexão>" --command "<comando>" --directory "/root" --timeout 5000
agentsshcli exec --connection "<nome da conexão>" --command-file "./script.sh" --timeout 5000
agentsshcli exec --no-cache --connection "<nome da conexão>" --command "<comando>"

Parâmetros:

• <nome da conexão>: Nome da conexão
• <comando>: Comando remoto
• --connection <nome>, -c <nome>: Nome da conexão
• --command <comando>: Comando remoto
• --command-file <caminho>: Lê o conteúdo de um arquivo UTF-8 local e o executa como comando remoto (não é enviado primeiro e depois executado); adequado para executar scripts de várias linhas; o arquivo deve usar quebras de linha LF, não CRLF do Windows; não pode ser usado simultaneamente com --command ou o argumento posicional <comando>
• --directory <dir>, -d <dir>: Diretório de trabalho remoto
• --timeout <ms>, -t <ms>: Tempo limite em milissegundos; padrão 30000
• --pty: Aloca um pseudo-terminal para este comando; tem prioridade sobre o arquivo de configuração
• --no-pty: Não aloca um pseudo-terminal para este comando; tem prioridade sobre o arquivo de configuração
• --sudo: Executa o comando com elevação sudo; requer privilegeEnabled: true na configuração da conexão
• --su: Executa o comando alternando o usuário com su; requer privilegeEnabled: true na configuração da conexão; é mutuamente exclusivo com --sudo
• --json: Saída JSON estruturada (exitCode/stdout/stderr)
• --no-cache: Não reutiliza a conexão; deve ser colocado antes do nome da conexão ou de --connection
• --cache-ttl <ms>: Tempo de inatividade do cache de conexão em milissegundos; deve ser colocado antes do nome da conexão ou de --connection

O modo de elevação só suporta comandos não interativos: a CLI envia a senha via stdin do canal SSH e fecha o stdin; o comando alvo não pode continuar lendo entrada. Se as credenciais sudo independentes estiverem ausentes, a senha SSH pode ser reutilizada; se não houver senha disponível, o modo não interativo sudo -n é usado, suportando NOPASSWD remoto ou cache de autenticação válido; se uma senha for necessária, a operação falha imediatamente. O login com chave privada, se o remoto exigir senha, requer a configuração de sudoPassword/sudoPasswordRef. Su sempre requer uma senha independente do usuário alvo.

Ao usar --command-file, certifique-se de que o arquivo de script tenha quebras de linha LF. Arquivos CRLF enviarão \r para o bash remoto, o que pode causar $'xxx\r': command not found.

Escrita recomendada para macOS/Linux:

cat > /tmp/remote-command.sh <<'EOF'
pwd
EOF
agentsshcli exec --connection "<nome da conexão>" --command-file /tmp/remote-command.sh

Escrita recomendada para Windows PowerShell:

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

Valor de retorno:

• Se bem-sucedido e com stdout, stdout exibe o resultado do comando remoto
• Se bem-sucedido, mas sem stdout, nenhum conteúdo é exibido
• Código de saída é 0
• Se o comando remoto sair com código diferente de zero, exceder o tempo limite, atingir a lista de negação, não atingir a lista de permissão ou a conexão falhar, stderr exibe a mensagem de erro e o código de saída é 1
• No modo --json, a saída é JSON; exitCode é o código de saída real do comando remoto (diferente de zero indica falha do comando); stdout/stderr retornam fielmente a saída remota; quando o comando falha, o código de saída do processo ainda é 1

Notas importantes:

• Ao usar pkill -f / pgrep -f em comandos, a string de correspondência pode corresponder ao próprio shell remoto que executa o comando (a linha de comando contém a string), fazendo com que o shell seja morto, o comando seja interrompido e nenhuma saída seja gerada. Para excluir a si mesmo, use truques de regex, como pkill -f 'name[.]log'.
• Se a sessão remota for encerrada anormalmente (shell morto, etc.), será relatado [remoto] Sessão encerrada anormalmente (sem status de saída), sem retornar silenciosamente como sucesso.
• Se um comando iniciar um processo em segundo plano no final e não redirecionar stdout, o canal remoto não será fechado e o comando aguardará até o tempo limite total; para execução em segundo plano, redirecione stdout e stderr para um arquivo (por exemplo, > /tmp/x.log 2>&1 < /dev/null &).
• Use aspas para envolver comandos (por exemplo, --command "<comando>" ou argumento posicional "<comando>"): tokens como --json, --timeout dentro do conteúdo do comando serão analisados como parâmetros da CLI; se não estiverem entre aspas, podem ser engolidos ou causar erro.

upload

Envia um arquivo local para o remoto.

Forma de argumentos posicionais:

agentsshcli upload "<nome da conexão>" "<caminho local>" "<caminho remoto>"
agentsshcli upload --no-cache "<nome da conexão>" "<caminho local>" "<caminho remoto>"

Forma de argumentos nomeados:

agentsshcli upload --connection "<nome da conexão>" --local "./tmp/upload.txt" --remote "/usr/local/test/upload.txt"
agentsshcli upload --no-cache --connection "<nome da conexão>" --local "./tmp/upload.txt" --remote "/usr/local/test/upload.txt"

Parâmetros:

• <nome da conexão>: Nome da conexão
• <caminho local>: Caminho do arquivo local
• <caminho remoto>: Caminho do arquivo alvo no remoto
• --connection <nome>, -c <nome>: Nome da conexão
• --local <caminho>, -l <caminho>: Caminho do arquivo local
• --remote <caminho>, -r <caminho>: Caminho do arquivo alvo no remoto
• --timeout <ms>: Tempo limite total em milissegundos; padrão é ilimitado (permite execução longa para arquivos grandes), diferente do padrão de 30s do exec
• --recursive: Envia diretórios recursivamente, mantendo caminhos relativos; links simbólicos não são seguidos – links para diretórios são ignorados (para evitar loops) e links para arquivos têm seu conteúdo enviado
• --json: Saída JSON estruturada
• --no-cache: Não reutiliza a conexão; deve ser colocado antes do nome da conexão ou de --connection
• --cache-ttl <ms>: Tempo de inatividade do cache de conexão em milissegundos; deve ser colocado antes do nome da conexão ou de --connection

Estabilidade do upload:

• O upload primeiro grava em um arquivo temporário <caminho remoto>.part e, em seguida, renomeia para o arquivo alvo após a conclusão da verificação.
• Simultaneamente, grava metadados de retomada em <caminho remoto>.part.meta; se o tamanho, o tempo de modificação ou o tamanho do bloco do arquivo local mudarem, o arquivo temporário antigo é excluído e o upload é reiniciado, evitando concatenação incorreta.
• Se o upload for interrompido, na próxima vez que o mesmo arquivo local for enviado para o mesmo caminho remoto, a retomada ocorrerá a partir do tamanho existente do .part.
• O modo --no-cache pode ser interrompido com Ctrl+C; o modo daemon pode usar stop-daemon para interromper bruscamente o pool de conexões, mas isso afetará outras tarefas no mesmo daemon, não sendo um cancelamento preciso de um único upload.

Valor de retorno:

• Em caso de sucesso, stdout exibe File uploaded successfully
• Código de saída é 0
• O upload de um único arquivo não cria diretórios remotos: se o diretório alvo não existir (ou se um caminho com o mesmo nome for um arquivo), o erro Diretório remoto não existe ou inacessível: <dir> é retornado; o diretório deve ser criado primeiro, ou use --recursive para enviar um diretório inteiro (o modo recursivo cria diretórios automaticamente)
• Se o arquivo local não existir, a gravação remota falhar ou a conexão falhar, stderr exibe a mensagem de erro e o código de saída é 1
• No modo --json, stdout em caso de sucesso é {"exitCode":0,"stdout":"File uploaded successfully","stderr":""}; em caso de falha, exitCode é 1

download

Baixa um arquivo remoto para o local.

Forma de argumentos posicionais:

agentsshcli download "<nome da conexão>" "<caminho remoto>" "<caminho local>"
agentsshcli download --no-cache "<nome da conexão>" "<caminho remoto>" "<caminho local>"

Forma de argumentos nomeados:

agentsshcli download --connection "<nome da conexão>" --remote "/usr/local/test/upload.txt" --local "./tmp/download.txt"
agentsshcli download --no-cache --connection "<nome da conexão>" --remote "/usr/local/test/upload.txt" --local "./tmp/download.txt"

Parâmetros:

• <nome da conexão>: Nome da conexão
• <caminho remoto>: Caminho do arquivo remoto
• <caminho local>: Caminho alvo local
• --connection <nome>, -c <nome>: Nome da conexão
• --remote <caminho>, -r <caminho>: Caminho do arquivo remoto
• --local <caminho>, -l <caminho>: Caminho alvo local
• --timeout <ms>: Tempo limite total em milissegundos; padrão é ilimitado (permite execução longa para arquivos grandes), diferente do padrão de 30s do exec
• --recursive: Baixa diretórios recursivamente, mantendo caminhos relativos; links simbólicos remotos são ignorados
• --json: Saída JSON estruturada
• --no-cache: Não reutiliza a conexão; deve ser colocado antes do nome da conexão ou de --connection
• --cache-ttl <ms>: Tempo de inatividade do cache de conexão em milissegundos; deve ser colocado antes do nome da conexão ou de --connection

Estabilidade do download:

• O download primeiro grava em um arquivo temporário <caminho local>.part e grava metadados de retomada em <caminho local>.part.meta; após a conclusão, verifica o tamanho e renomeia para o arquivo alvo.
• Se o download for interrompido, na próxima vez que o mesmo arquivo remoto for baixado para o mesmo caminho local, a retomada ocorrerá a partir do tamanho existente do .part; se as características do arquivo remoto mudarem, o .part antigo é excluído e o download é reiniciado.

Valor de retorno:

• Em caso de sucesso, stdout exibe File downloaded successfully
• Código de saída é 0
• Se a gravação local falhar, a leitura remota falhar ou a conexão falhar, stderr exibe a mensagem de erro e o código de saída é 1
• No modo --json, stdout em caso de sucesso é {"exitCode":0,"stdout":"File downloaded successfully","stderr":""}; em caso de falha, exitCode é 1

stop-daemon

Para o processo de cache SSH (pool de conexões) correspondente ao arquivo de configuração atual. É um comando de manutenção do pool de conexões, não um cancelamento preciso de uma única tarefa de upload; isso afetará outras tarefas no mesmo daemon:

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

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

Valor de retorno:

• Em caso de sucesso, help exibe o texto de ajuda no stdout e o código de saída é 0
• Em caso de sucesso, version exibe o número da versão no stdout e o código de saída é 0