适用场景

xxssh 0.5.0 的命令行专为脚本与 AI Agent 设计：服务器信息由 TUI 保存（~/.xxssh/servers.json），所有 CLI 命令用 --profile 名称 直接调用，无需重复输入主机与凭据。

命令执行

xxssh --run "cmd" --profile 名字       # 执行并透传退出码
xxssh 名字 --run "cmd"                 # 服务器名放前面也行
xxssh --run "a" --run "b" --profile 名字   # 多条命令同一连接顺序执行
xxssh --runfile 文件 --profile 名字    # 逐行执行（忽略 # 注释与空行）

注意：每条 --run 是独立的 shell，cd / 环境变量不跨命令延续；有状态操作写在同一条命令里（cd /x && make）。

文件操作（全部支持 --json）

ls（-r 递归）、stat、exists（退出码 0/1）、mkdir（自动建父目录）、touch（不截断）、cp（-r）、mv / rename、rm（目录需 -r）、chmod、ln TARGET LINK、du、df。

上传下载

xxssh put 本地 名字:/远程 [-r] [--atomic]    # --atomic：安全替换已存在文件
xxssh get 名字:/远程 本地 [-r]
xxssh --profile 名字 put 本地 /远程路径      # --profile 写法

mtime 自动保留；替换已存在文件建议总是加 --atomic。

目录同步

xxssh --profile p sync 本地 远端 [--direction push|pull|both] [--delete]
      [--dry-run] [--conflict fail|newer|local|remote] [--include glob] [--exclude glob] [--json]

增量：大小相同且 mtime 差 <=1 秒即跳过。--delete 只删受管文件，目录仅空时移除。

AI Agent 要点

• 密码 / 口令：--password / --passphrase（也可 user@host 一次性直连）
• HEX_ 编码：密码、命令、路径都可用十六进制传递，规避一切引号问题：

printf '%s' "值" | xxd -p -> --password HEX_<结果>

• 超时：--timeout 秒（连接，默认 30）、--cmd-timeout 秒（每条命令）
• 退出码：0 成功 / 1 失败 / 2 用法错误 / 124 命令超时
• stdout 只有数据（命令输出或 JSON），状态信息在 stderr
• 帮助：--help agents 上手，--help all 一次性完整文档

主机指纹校验

xxssh --profile p exists / --known-hosts-add ~/.ssh/known_hosts  # 首次学习
xxssh --profile p exists / --known-hosts ~/.ssh/known_hosts      # 之后严格校验

Git Bash (MSYS) 注意

Windows 上用 Git Bash 时，/ 开头的参数会被 MSYS 改写成本地路径（加引号也无法避免）。

xxssh --profile p ls /var/log        # 坏：被改写成 C:/.../var/log
xxssh --profile p ls //var/log       # 好：双斜杠（Linux 视作 /var/log）
MSYS_NO_PATHCONV=1 xxssh --profile p ls /var/log   # 好：禁用转换

PowerShell 与 cmd 无此问题，示例原样可用。详见 xxssh --help shells。

分离执行与 JSON 报告（0.5.1）

远端 nohup ... & 会让 SSH 会话挂起（协议要等所有持有输出流的进程结束）。用 --run-bg 解决：

xxssh --profile p --run-bg "./server -port=:8080" --bg-log /srv/server.log
# stdout 输出远端 PID（原始数据），stderr 提示启动信息，立即返回
xxssh --profile p --run "ps -p <PID>"        # 用 PID 确认存活

• --bg-log 缺省 /dev/null，追加写入；命令启动失败会写进日志
• 与 --run 按命令行顺序交错：--run-bg ./server --run "sleep 1 && curl health"
• 长期服务仍建议 systemd；--run-bg 适合脚本/Agent 的临时启动与重启

--run-json 把命令执行变成结构化数据：

xxssh --profile p --run "uname -a" --run-bg "sleep 30" --run-json
# {"op":"run","results":[{"cmd":"uname -a","bg":false,"rc":0,"out":"...","err":""},
#                        {"cmd":"sleep 30","bg":true,"rc":0,"pid":1234,"out":"1234\n","err":""}]}

超时（--cmd-timeout）时保留已完成的部分结果并以 timed_out 标记，进程退出码 124。