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 正規表現ではありません。空白文字は [:space:] ではなく \\s と記述します。例：

{
  "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 のみをリッスンし、起動後に自動的にブラウザを開きます。同じ設定パスでは1つのインスタンスのみが実行されます。繰り返し実行すると、既存のインスタンスが開かれます。
• CLI が出力するローカル URL フラグメントには一時的なトークンが含まれているため、資格情報として扱い、ログ、チケット、対外メッセージに書き込んではいけません。ユーザーが手動でアドレスにアクセスする必要があると明示した場合にのみ、現在のローカルセッションで提供します。
• 認証された有効な API または実際の pointerdown、keydown、input が10分間連続してない場合、エディターは自動的に終了し、状態ファイルを削除します。ページが無効になった後は、edit-config を再実行します。
• stop-editor はその設定に対応するローカルエディターのみを停止し、SSH デーモン、キャッシュ接続、リモートタスクは停止しません。
• ユーザーが保存していないページの変更をまだ持っている可能性がある場合、自分で stop-editor を実行しないでください。ユーザーが明示的に停止を要求した場合、または保存されていないコンテンツを破棄してもよいことを確認した場合にのみ呼び出します。
• edit-config / stop-editor は --config、--help、--version をサポートし、--no-cache、--cache-ttl、位置パラメーターは受け付けません。
• 設定ファイルは他のプロセスによって変更される可能性があります。保存時に競合が返された場合は、まず再読み込みし、ハッシュチェックをバイパスしたり直接上書きしたりしてはいけません。
• JSON パネルは「グローバル / 現在の接続」と「プレビュー / ソース」をサポートします。バックエンドの検証が最終的な設定契約であり、フロントエンドのヒントが保存結果に代わるものではありません。
• ページの「接続テスト」は、現在のドラフトと関連する踏み台サーバーを使用して SSH 接続と認証を1回実行し（未保存のパスワードドラフトを含む）、完了後に切断します。設定は保存されず、コマンドも実行されません。同時に実行できるテストは1つのみです。
• パスワードの表示はローカルバックエンドで復号化され、平文はページに一時的に表示され、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: 認証方式。これら3つのうち1つだけを保持できます。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 も含まれます。一致するものがない場合は [] を出力します。
• パスワード、秘密鍵、パスフレーズ、ブラックリスト/ホワイトリストなどの機密または制御フィールドは出力しません。
• 終了コードは 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 権限昇格ルール

ユーザーが既存の非 root 接続を介して sudo、su、root 権限、またはターゲットユーザーを切り替えてコマンドを実行するよう要求した場合、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 ファイルは \r をリモートの 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 です。
• リモートコマンドが非ゼロで終了した場合、タイムアウト、ブラックリストにヒット、ホワイトリストにヒットしない、または接続に失敗した場合、stderr にエラー情報を出力し、終了コードは 1 です。
• --json モードでは JSON を出力します。exitCode はリモートコマンドの実際の終了コード（非ゼロはコマンド失敗を示します）、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 一時ファイルに書き込み、完了後に検証してから正式なターゲットファイルにリネームします。
• 同時に <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 再開メタデータも書き込みます。完了後にサイズを検証してから正式なターゲットファイルにリネームします。
• ダウンロードが中断された場合、次回同じリモートファイルを同じローカルパスにダウンロードするときに、既存の .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 です。

エラールール

• ...

（翻訳のため一部省略）