Carrot404/agent-ssh-cli

agent-ssh-cli 사용 설명서

agentsshcli는 npm을 통해 설치되고 Rust 네이티브 실행기로 SSH 작업을 수행하는 명령줄 도구입니다. AI 또는 사용자가 로컬 구성을 통해 원격 서버를 안전하게 조작할 수 있도록 해줍니다.

할 수 있는 일:

• 로컬 구성에 있는 SSH 서버 연결 목록 조회
• 지정된 원격 서버에서 명령 실행
• 사용자가 명시적으로 확인한 SHA256 지문을 사용하여 SSH 호스트 공개 키를 로컬 known_hosts에 등록
• 로컬 파일을 원격 서버에 업로드
• 원격 서버에서 로컬로 파일 다운로드
• 명령 블랙리스트/화이트리스트를 통해 실행 가능한 명령 제한
• Rust 데몬을 통해 SSH 연결을 짧은 시간 동안 캐싱하여 연속 작업 시 반복 연결 오버헤드 감소
• 로컬 루프백 주소만 수신하는 시각적 편집기를 통해 연결, 자격 증명 참조 및 보안 정책 관리
• npm 설치 시 현재 시스템에 맞는 optional 사전 컴파일 패키지를 자동으로 가져옴. 현재 macOS arm64/x64, Linux x64/arm64, Windows x64 지원

하지 않는 일:

• 비밀번호, 개인 키 등 민감한 인증 정보를 평문으로 출력하지 않음. 비밀번호는 설정에 따라 로컬 secrets.json에 암호화되어 저장되며 SSH 채널 stdin을 통해서만 전송
• 네트워크 스캔이나 서버 검색을 수행하지 않으며 구성 파일의 연결만 사용
• 구성의 명령 제한을 우회하지 않음

명령 블랙리스트/화이트리스트는 JavaScript RegExp 구문을 사용하며 POSIX 정규 표현식이 아닙니다. 공백 문자는 \s로 작성하고 [:space:]는 사용하지 마십시오. 예:

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

안전 확인

위험한 작업을 실행하기 전에 반드시 사용자에게 확인을 받아야 하며 직접 실행해서는 안 됩니다.

위험한 작업에는 다음이 포함됩니다:

• 파일이나 디렉터리 삭제, 비우기, 덮어쓰기 (예: rm, truncate, 리다이렉션 덮어쓰기, 일괄 삭제)
• 캐시, 로그, 임시 디렉터리 또는 비즈니스 데이터 정리
• 재시작, 종료, 서비스 중지 또는 프로세스 종료 (예: reboot, shutdown, systemctl stop, kill)
• 권한, 소유자, 시스템 구성 또는 시작 항목 수정 (예: chmod, chown, /etc 아래 파일 편집)
• 원격에 이미 존재하는 파일을 덮어쓰는 업로드
• 로컬에 이미 존재하는 파일을 덮어쓰는 다운로드
• 되돌릴 수 없거나, 온라인 서비스에 영향을 주거나, 데이터 무결성에 영향을 미치는 모든 작업

확인 시에는 대상 연결 이름, 명령 또는 파일 경로, 잠재적 영향을 설명하고 사용자가 명시적으로 동의할 때까지 기다려야 합니다.

환경 검증

호출 전에 먼저 CLI 자체가 사용 가능한지 확인하십시오:

agentsshcli --help

위 명령이 실패하면 기본 환경을 확인하십시오:

node --version
npm --version

node 또는 npm이 없으면 사용자에게 Node.js >= 18 및 npm >= 8을 설치하도록 안내하십시오.

CLI가 사용 가능한지 확인한 후 구성 파일이 존재하는지 확인하십시오:

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

구성 파일이 없으면 사용자에게 구성 파일을 생성하도록 안내하고 SSH 명령을 계속 실행하지 마십시오:

mkdir -p ~/.agent-ssh-cli
# 그런 다음 사용자가 ~/.agent-ssh-cli/config.json을 편집하여 실제 서버 구성을 입력하도록 함

기본 구성 파일:

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

모든 SSH 연결 설정(배스천 호스트 및 편집기 "연결 테스트" 포함)은 구성의 호스트 이름과 포트를 사용하여 ~/.ssh/known_hosts를 검증합니다. 처음 연결하여 등록되지 않은 경우 사용자에게 대상 연결 이름, 호스트 및 포트, 수신된 SHA256 지문, 그리고 첫 번째 신뢰 시 잘못된 서버에 연결하거나 중간자 공격을 받을 위험이 있음을 설명합니다. 사용자가 명시적으로 확인하면 trust-host를 사용하여 등록할 수 있습니다(포트 22가 아닌 경우 [host]:port). 콘솔이나 운영 기록에서 독립적으로 확인할 것을 강요하지 않습니다. 사용자가 현재 대상에 대해 "신뢰", "직접 trust" 등 동의를 명시적으로 표시한 경우 승인된 것으로 간주하며 반복적인 확인을 요구하거나 독립적인 확인 부족을 이유로 거부하지 마십시오. 사용자 확인 없이 자동으로 신뢰해서는 안 됩니다. 기존 공개 키가 변경된 경우에도 충돌을 조사해야 하며 이전 기록을 자동으로 덮어쓰지 않습니다.

비밀번호는 agentsshcli edit-config를 통해 교체하는 것이 좋습니다. 편집기가 저장할 때 새 비밀번호를 암호화하여 secrets.json에 쓰고 구성 파일에는 passwordRef만 유지합니다. 이전 구성은 여전히 수동 마이그레이션을 지원합니다. 연결에 비어 있지 않은 평문 password가 포함된 경우 다음 exec, upload 또는 download 실행 시 secret.key를 생성하고 비밀번호를 암호화하여 저장한 후 평문 필드를 참조로 바꿉니다. 대화, 로그 또는 명령 출력에서 평문 비밀번호를 표시하지 마십시오.

편집기의 "권한 경계" 페이지에서 sudo/su 비밀번호를 설정하고 볼 수 있습니다. 처음 입력 시 연결 이름별로 독립적인 참조를 생성하고 저장 후 secrets.json에 암호문만 씁니다. sudo 비밀번호가 별도로 구성되지 않은 경우 해당 필드는 --sudo 실행 시 SSH 비밀번호를 재사용함을 알립니다.

trust-host

처음 등록하려면 사용자의 명시적인 확인을 받아야 합니다. 지문을 독립적으로 확인하는 것은 권장되는 방법이지 등록의 전제 조건이 아닙니다. CLI 첫 연결 오류에서 반환된 SHA256 지문을 사용하거나 인증 자격 증명을 보내지 않고 공개 키를 탐지하여 지문을 얻은 후 위 규칙에 따라 확인하고 등록할 수 있습니다:

agentsshcli trust-host --fingerprint 'SHA256:<사용자가 확인한 지문>' '<connectionName>'
agentsshcli trust-host --config /path/to/config.json --fingerprint 'SHA256:<사용자가 확인한 지문>' '<connectionName>'

• --fingerprint는 필수이며 완전한 SHA256 지문만 허용하고 연결 이름 앞에 위치해야 합니다. --config는 그 앞에 위치합니다.
• 명령은 해당 연결의 기존 직접 연결, SOCKS5 또는 배스천 호스트 경로를 통해 핸드셰이크를 완료하며 대상 시스템을 인증하지 않고 명령을 실행하지 않습니다. 배스천 호스트가 등록되지 않은 경우 사용자 확인을 받고 배스천 호스트를 먼저 등록합니다.
• 지문이 일치하지 않거나 다른 공개 키가 이미 있는 경우 쓰기를 거부하고 이전 기록을 덮어쓰지 않습니다. 동일한 공개 키가 이미 등록된 경우 중복 추가하지 않습니다. 입력된 지문이 핸드셰이크 공개 키와 일치하고 해당 호스트에 대한 레코드가 없는 경우에만 ~/.ssh/known_hosts에 씁니다.
• ssh-keyscan 또는 첫 연결에서 반환된 지문은 사용자 확인 대상이 될 수 있지만 독립적으로 서버 ID를 확인했다고 주장할 수 없습니다. 사용자 확인 후 등록할 수 있으며 독립적인 확인 부족을 이유로 거부해서는 안 됩니다. 등록 실패 시 구체적인 오류를 확인하고 검증을 건너뛰는 매개변수를 사용하지 마십시오.

edit-config / stop-editor

로컬 시각적 편집기를 사용하여 SSH 연결을 관리합니다:

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

호출 규칙:

• 사용자가 SSH 구성을 열거나 편집하거나 시각적으로 관리하도록 요청하면 직접 edit-config를 실행하십시오. 내부 __editor 하위 명령을 직접 호출하거나 HTTP API를 조립하지 마십시오.
• 편집기는 127.0.0.1만 수신하며 시작 시 자동으로 브라우저를 엽니다. 동일한 구성 경로에 대해 하나의 인스턴스만 실행됩니다. 반복 실행 시 기존 인스턴스를 엽니다.
• CLI가 출력하는 로컬 URL fragment에는 임시 토큰이 포함되어 있으므로 자격 증명처럼 취급해야 하며 로그, 티켓 또는 외부 메시지에 기록하지 마십시오. 사용자가 명시적으로 주소에 수동으로 액세스해야 하는 경우에만 현재 로컬 세션에서 제공하십시오.
• 10분 동안 인증된 유효한 API 또는 실제 pointerdown, keydown, input이 없으면 편집기가 자동으로 종료되고 상태 파일을 삭제합니다. 페이지가 만료된 후 edit-config를 다시 실행하십시오.
• stop-editor는 해당 구성에 해당하는 로컬 편집기만 중지하며 SSH 데몬, 캐시된 연결 또는 원격 작업을 중지하지 않습니다.
• 사용자가 저장되지 않은 페이지 수정 사항을 가지고 있을 수 있는 경우 stop-editor를 스스로 실행하지 마십시오. 사용자가 명시적으로 중지를 요청하거나 저장되지 않은 콘텐츠를 포기할 수 있음을 확인한 경우에만 호출하십시오.
• edit-config / stop-editor는 --config, --help 및 --version을 지원하며 --no-cache, --cache-ttl 또는 위치 매개변수를 허용하지 않습니다.
• 구성 파일은 다른 프로세스에 의해 수정될 수 있습니다. 저장 시 충돌이 발생하면 먼저 다시 로드하고 해시 검사를 우회하거나 직접 덮어쓰지 마십시오.
• JSON 패널은 "전역 / 현재 연결" 및 "미리보기 / 소스"를 지원합니다. 백엔드 검증이 최종 구성 계약이며 프론트엔드 힌트가 저장 결과를 대체할 수 없습니다.
• 페이지의 "연결 테스트"는 현재 초안과 관련 배스천 호스트를 사용하여 한 번의 SSH 연결 설정 및 인증(저장되지 않은 비밀번호 초안 포함)을 수행하고 완료 후 연결을 끊으며 구성을 저장하거나 명령을 실행하지 않습니다. 동시에 하나의 테스트만 가능합니다.
• 비밀번호 보기는 로컬 백엔드에서 해독되며 평문은 페이지에 잠시만 표시되고 15초 후에 지워집니다. 터미널, 스크립트 또는 HTTP 디버그 인터페이스를 통해 비밀번호를 추출하지 마십시오.
• 비밀번호 교체는 페이지의 교체 작업을 사용하십시오. 저장 후 config.json에는 passwordRef만 남고 암호문은 같은 디렉터리의 secrets.json에 기록됩니다. 연결 복사 시 비밀번호 참조는 복사되지 않습니다.
• 편집기는 연결 수준의 PTY 컨트롤을 표시하지 않지만 기존 pty는 투과적으로 전달합니다. 명령 실행 시 계속 exec --pty / --no-pty를 사용하여 임시로 재정의합니다.

반환 동작:

• edit-config 성공 시 stdout에 구성 편집기가 열렸습니다: <local-url>을 출력하고 종료 코드는 0입니다. 브라우저 열기 실패 시 오류 메시지에 수동으로 액세스할 수 있는 로컬 URL이 포함됩니다.
• stop-editor 성공 시 stdout에 구성 편집기가 중지되었습니다를 출력합니다. 해당 서비스가 없으면 구성 편집기가 실행되고 있지 않습니다를 반환하고 종료 코드는 1입니다.
• 편집기 저장 충돌, 구성 검증 실패 또는 자격 증명 참조 불완전 시 원래 구성을 변경하지 않아야 합니다. 페이지나 stderr의 구체적인 오류에 따라 처리하십시오.

숨겨진 비밀번호 구성 예시:

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

구성 파일 전체 필드(각 항목은 name이 고유한 서버):

• name: 연결 이름, 고유해야 함
• group / tags: 선택적 단일 계층 그룹 및 태그 배열, 편집기는 그룹 또는 태그별 표시 지원; 태그는 공백 제거, 중복 제거
• host / port / username: SSH 호스트, 포트(기본 22), 사용자 이름
• password / passwordRef / privateKey: 인증 방식, 세 가지 중 하나만 유지해야 함; passphrase는 privateKey와 함께만 사용
• jumpHost: 배스천 호스트 연결 이름, 구성 파일에 있는 다른 머신의 name을 입력; 연결 시 먼저 배스천 호스트로 SSH를 설정한 후 직접 채널을 통해 대상 머신에 도달
• socksProxy: SOCKS5 프록시 주소, 예: socks5://127.0.0.1:1080; 프로토콜을 생략하고 127.0.0.1:1080으로도 작성 가능
• pty: 기본적으로 의사 터미널을 할당할지 여부, exec --pty / --no-pty로 임시 재정의 가능
• privilegeEnabled: exec --sudo/--su를 허용할지 여부, 기본값 false
• sudoUser: sudo 대상 사용자, 기본값 root; sudoPassword/sudoPasswordRef는 현재 SSH 사용자의 sudo 비밀번호를 저장, 없으면 SSH 비밀번호 재사용 가능
• suUser: su 대상 사용자, 기본값 root; suPassword/suPasswordRef는 대상 사용자의 비밀번호를 저장해야 함
• commandWhitelist / commandBlacklist: 명령 화이트리스트/블랙리스트 정규식 배열

배스천 호스트 예시:

[
  {
    "name": "대상기",
    "host": "10.0.0.5",
    "username": "root",
    "passwordRef": "agentsshcli:대상기",
    "jumpHost": "배스천호스트"
  },
  {
    "name": "배스천호스트",
    "host": "203.0.113.10",
    "port": 22,
    "username": "ubuntu",
    "privateKey": "/path/to/jump_key"
  }
]

다른 구성 파일 지정:

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

CLI를 사용할 수 없지만 Node/npm이 정상이면 사용자에게 설치를 안내하십시오:

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

소스에서 개발하거나 로컬에서 디버그할 때는 먼저 Rust 네이티브 실행기를 빌드해야 합니다:

npm run build:native
npm test

전역 매개변수

• --config <path>: 구성 파일 경로 지정, 기본 구성보다 우선 순위 높음
• --help, -h: 도움말 출력
• --version, -v: 버전 출력

exec, upload, download는 기본적으로 Rust 데몬 연결 캐시를 사용하여 연속 작업 시 반복 SSH 핸드셰이크 및 인증 오버헤드를 줄입니다. --no-cache를 전달한 경우에만 캐시를 건너뛰고 직접 연결합니다. 캐시 관련 매개변수는 다음과 같습니다:

• --no-cache: Rust 데몬 연결 캐시 건너뛰기, 이 명령은 연결을 독립적으로 설정하고 종료, 즉 직접 연결 모드
• --cache-ttl <ms>: Rust 데몬 연결 캐시 유휴 시간(밀리초) 설정, 기본값 180000
• --json: exec, upload, download가 구조화된 JSON(필드 exitCode/stdout/stderr)을 출력하여 스크립트 및 AI가 쉽게 구문 분석할 수 있도록 함

모든 매개변수(--no-cache, --cache-ttl, --json, --timeout, --pty 등)는 연결 이름(첫 번째 위치 매개변수) 앞에 위치해야 하며 서로 간에 순서는 상관없습니다. 연결 이름 뒤에 배치하면 명령 내용의 일부로 간주되어 "지원되지 않는 매개변수" 오류가 발생하므로 명령을 따옴표로 묶으십시오.

init-config

기본 구성 파일을 ~/.agent-ssh-cli/config.json에 생성합니다(이미 존재하면 덮어쓰지 않음):

agentsshcli init-config

list

구성에 있는 서버를 나열합니다.

agentsshcli list
agentsshcli list --json
agentsshcli list --group 프로덕션 --tag 앱

매개변수:

• --json: JSON 형식으로 출력. 현재 기본 출력도 JSON입니다.
• --config <path>: 구성 파일 지정
• --group <group> / --tag <tag>: 대소문자 구분 정확한 필터링, 동시에 전달 시 교집합

반환 값:

• 성공 시 stdout에 서버 배열을 출력하며 name, host, port, username, group, tags를 포함합니다. 배스천 호스트가 구성된 경우 jumpHost도 포함됩니다. 일치하는 항목이 없으면 [] 출력
• 비밀번호, 개인 키, passphrase, 블랙리스트/화이트리스트 등 민감하거나 제어 필드는 출력하지 않음
• 종료 코드는 0

예시 출력:

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

exec

원격에서 명령을 실행합니다.

위치 매개변수 형식:

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"

sudo/su 권한 상승 규칙

사용자가 기존 비루트 연결을 통해 sudo, su, root ID 또는 대상 사용자로 명령을 실행하도록 요청하는 경우 CLI 최상위 매개변수 --sudo 또는 --su를 사용해야 하며 원격 대화형 명령을 직접 사용해서는 안 됩니다.

• --sudo/--su는 연결 이름 또는 --connection 앞에 위치해야 합니다.
• sudo, sudo -S, sudo -n, su 또는 su -c를 <command>에 직접 포함시키는 것은 금지됩니다. 이렇게 작성하면 CLI의 권한 상승 비밀번호 채널을 우회하고 대화형 입력을 기다리거나 도구가 비밀번호를 지원하지 않는다고 잘못 판단할 수 있습니다.
• 일반 su -c가 시간 초과되었다고 해서 agentsshcli가 비밀번호 프롬프트에 응답할 수 없다고 판단하지 마십시오. agentsshcli 0.5.0+는 SSH 채널 stdin을 통해 구성된 암호화된 자격 증명을 자동으로 전송합니다.
• --su --json 성공 시 stderr에 여전히 원격 Password: 프롬프트 텍스트가 포함될 수 있습니다. 이 프롬프트에는 실제 비밀번호가 포함되어 있지 않으며 인증 실패를 의미하지 않습니다. JSON exitCode 및 stdout의 whoami/id -u와 결합하여 결과를 판단해야 합니다.
• 사용 전 연결 구성 privilegeEnabled: true 및 대상 사용자가 구성되었는지 확인하십시오. su는 독립적인 비밀번호가 필요하며 sudo는 사용 가능한 비밀번호가 없는 경우 원격 비밀번호 없는 정책을 지원합니다.

올바른 작성법:

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

잘못된 작성법:

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

명명된 매개변수 형식:

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>"

매개변수:

• <connectionName>: 연결 이름
• <command>: 원격 명령
• --connection <name>, -c <name>: 연결 이름
• --command <command>: 원격 명령
• --command-file <path>: 로컬 UTF-8 파일에서 내용을 읽어 원격 명령으로 실행(먼저 업로드한 다음 실행하는 것이 아님), 여러 줄 스크립트 실행에 적합; 파일은 LF 줄 바꿈을 사용해야 하며 Windows CRLF 줄 바꿈을 사용할 수 없음; --command 또는 위치 매개변수 <command>와 동시에 사용할 수 없음
• --directory <dir>, -d <dir>: 원격 작업 디렉터리
• --timeout <ms>, -t <ms>: 시간 초과 밀리초 값, 기본값 30000
• --pty: 이 명령에 의사 터미널 할당, 구성 파일보다 우선 순위 높음
• --no-pty: 이 명령에 의사 터미널 할당 안 함, 구성 파일보다 우선 순위 높음
• --sudo: sudo를 사용하여 권한 상승 실행, 연결 구성 privilegeEnabled: true 필요
• --su: su를 사용하여 사용자 전환 실행, 연결 구성 privilegeEnabled: true 필요; --sudo와 상호 배타적
• --json: 구조화된 JSON(exitCode/stdout/stderr) 출력
• --no-cache: 연결 재사용 안 함, 연결 이름 또는 --connection 앞에 위치해야 함
• --cache-ttl <ms>: 연결 캐시 유휴 시간(밀리초), 연결 이름 또는 --connection 앞에 위치해야 함

권한 상승 모드는 비대화형 명령만 지원합니다. CLI는 SSH 채널 stdin을 통해 비밀번호를 보낸 후 stdin을 닫으며 대상 명령은 계속 입력을 읽을 수 없습니다. sudo 독립 자격 증명이 없으면 SSH 비밀번호를 재사용할 수 있습니다. 사용 가능한 비밀번호가 없으면 비대화형 sudo -n을 사용하며 원격 NOPASSWD 또는 유효한 인증 캐시를 지원합니다. 비밀번호가 필요하면 즉시 실패합니다. 개인 키 로그인 및 원격 비밀번호가 필요한 경우 sudoPassword/sudoPasswordRef를 구성해야 합니다. su는 항상 독립적인 대상 사용자 비밀번호가 필요합니다.

--command-file 사용 시 스크립트 파일이 LF 줄 바꿈인지 확인해야 합니다. CRLF 파일은 을 원격 bash로 전송하여 $'xxx\r': command not found를 발생시킬 수 있습니다.

macOS/Linux 권장 작성법:

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

Windows PowerShell 권장 명시적 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"

반환 값:

• 성공하고 stdout이 있으면 stdout에 원격 명령 결과 출력
• 성공했지만 stdout이 없으면 내용 출력 안 함
• 종료 코드는 0
• 원격 명령이 0이 아닌 종료, 시간 초과, 블랙리스트 적중, 화이트리스트 미적중 또는 연결 실패 시 stderr에 오류 정보 출력, 종료 코드는 1
• --json 모드에서는 JSON 출력, exitCode는 원격 명령의 실제 종료 코드(0이 아닌 경우 명령 실패), stdout/stderr는 원격 출력을 그대로 반환; 명령 실패 시 프로세스 종료 코드는 여전히 1

주의 사항:

• 명령에서 pkill -f / pgrep -f를 사용할 때 일치 문자열은 해당 명령을 실행하는 원격 셸 자체를 적중시켜(명령줄에 해당 문자열 포함) 셸이 종료되고 명령이 중단되며 출력이 없을 수 있습니다. 자체를 제외해야 하는 경우 pkill -f 'name[.]log'와 같은 정규식 기술을 사용하십시오.
• 원격 세션이 비정상적으로 종료(셸 종료 등)되면 [remote] 세션이 비정상적으로 종료되었습니다(종료 상태 없음)를 보고하며 자동으로 성공을 반환하지 않습니다.
• 명령 끝에서 백그라운드 프로세스를 시작하고 stdout을 리디렉션하지 않으면 원격이 채널을 닫지 않아 명령이 총 시간 초과까지 대기합니다. 백그라운드 실행이 필요한 경우 stdout/stderr을 파일로 리디렉션하십시오(예: > /tmp/x.log 2>&1 < /dev/null &).
• 명령을 따옴표로 묶으십시오(예: --command "<command>" 또는 위치 매개변수 "<command>"). 명령 내용 안에 독립적인 --json, --timeout 등의 토큰이 있으면 CLI 매개변수로 구문 분석되어 따옴표가 없으면 잘못 처리되거나 오류가 발생할 수 있습니다.

upload

로컬 파일을 원격으로 업로드합니다.

위치 매개변수 형식:

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

명명된 매개변수 형식:

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"

매개변수:

• <connectionName>: 연결 이름
• <localPath>: 로컬 파일 경로
• <remotePath>: 원격 대상 파일 경로
• --connection <name>, -c <name>: 연결 이름
• --local <path>, -l <path>: 로컬 파일 경로
• --remote <path>, -r <path>: 원격 대상 파일 경로
• --timeout <ms>: 총 시간 초과 밀리초 값, 기본값 제한 없음(대용량 파일에 긴 실행 시간 허용), exec의 기본 30초와 다름
• --recursive: 디렉터리를 재귀적으로 업로드하고 상대 경로 유지; 심볼릭 링크는 따르지 않음 — 디렉터리를 가리키는 링크는 건너뛰고(루프 방지) 파일을 가리키는 링크는 그 내용을 업로드
• --json: 구조화된 JSON 출력
• --no-cache: 연결 재사용 안 함, 연결 이름 또는 --connection 앞에 위치해야 함
• --cache-ttl <ms>: 연결 캐시 유휴 시간(밀리초), 연결 이름 또는 --connection 앞에 위치해야 함

업로드 안정성:

• 업로드는 먼저 원격 <remotePath>.part 임시 파일에 쓰고 검증을 완료한 후 rename하여 최종 대상 파일로 만듭니다.
• 동시에 <remotePath>.part.meta 이어받기 메타데이터를 씁니다. 로컬 파일 크기, 수정 시간 또는 청크 크기가 변경되면 이전 임시 파일을 삭제하고 다시 전송하여 잘못된 연결을 방지합니다.
• 업로드가 중단되면 다음에 동일한 로컬 파일을 동일한 원격 경로에 업로드할 때 .part의 기존 크기에서 이어받기가 수행됩니다.
• --no-cache 모드에서는 Ctrl+C를 사용하여 현재 업로드를 중지할 수 있습니다. 데몬 모드에서는 stop-daemon을 사용하여 연결 풀을 강제로 중지할 수 있지만 동일한 데몬 내의 다른 작업에 영향을 미치므로 단일 업로드를 정확하게 취소하는 방법이 아닙니다.

반환 값:

• 성공 시 stdout에 File uploaded successfully 출력
• 종료 코드는 0
• 단일 파일 업로드는 원격 디렉터리를 생성하지 않습니다. 대상 디렉터리가 없거나(또는 동일한 이름의 경로가 파일인 경우) 원격 디렉터리가 존재하지 않거나 액세스할 수 없음: <dir>을 직접 보고하므로 먼저 디렉터리를 만들거나 --recursive를 사용하여 전체 디렉터리를 업로드해야 합니다(재귀 모드는 디렉터리를 자동으로 생성함)
• 로컬 파일이 없거나, 원격 쓰기 실패 또는 연결 실패 시 stderr에 오류 정보 출력, 종료 코드는 1
• --json 모드에서 성공 시 stdout은 {"exitCode":0,"stdout":"File uploaded successfully","stderr":""}, 실패 시 exitCode는 1

download

원격 파일을 로컬로 다운로드합니다.

위치 매개변수 형식:

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

명명된 매개변수 형식:

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>: 연결 이름
• <remotePath>: 원격 파일 경로
• <localPath>: 로컬 대상 파일 경로
• --connection <name>, -c <name>: 연결 이름
• --remote <path>, -r <path>: 원격 파일 경로
• --local <path>, -l <path>: 로컬 대상 파일 경로
• --timeout <ms>: 총 시간 초과 밀리초 값, 기본값 제한 없음(대용량 파일에 긴 실행 시간 허용), exec의 기본 30초와 다름
• --recursive: 디렉터리를 재귀적으로 다운로드하고 상대 경로 유지; 원격 심볼릭 링크 건너뜀
• --json: 구조화된 JSON 출력
• --no-cache: 연결 재사용 안 함, 연결 이름 또는 --connection 앞에 위치해야 함
• --cache-ttl <ms>: 연결 캐시 유휴 시간(밀리초), 연결 이름 또는 --connection 앞에 위치해야 함

다운로드 안정성:

• 다운로드는 먼저 로컬 <localPath>.part 임시 파일에 쓰고 <localPath>.part.meta 이어받기 메타데이터를 기록한 후 크기를 검증한 후 rename하여 최종 대상 파일로 만듭니다.
• 다운로드가 중단되면 다음에 동일한 원격 파일을 동일한 로컬 경로에 다운로드할 때 기존 .part 크기에서 계속 진행합니다. 원격 파일 특성이 변경되면 이전 .part를 자동으로 삭제하고 다시 다운로드합니다.

반환 값:

• 성공 시 stdout에 File downloaded successfully 출력
• 종료 코드는 0
• 로컬 쓰기 실패, 원격 읽기 실패 또는 연결 실패 시 stderr에 오류 정보 출력, 종료 코드는 1
• --json 모드에서 성공 시 stdout은 {"exitCode":0,"stdout":"File downloaded successfully","stderr":""}, 실패 시 exitCode는 1

stop-daemon

현재 구성 파일에 해당하는 SSH 캐시 프로세스(연결 풀)를 중지합니다. 연결 풀 유지 관리 명령이며 단일 업로드 작업을 정확하게 취소하는 방법이 아니라 동일한 데몬 내의 다른 작업에 영향을 미칩니다:

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

반환 값:

• help 성공 시 stdout에 도움말 텍스트 출력, 종료 코드는 0
• version 성공 시 stdout에 버전 번호 출력, 종료 코드는 0

오류 규칙

• ...