remote-shell

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

remote-shell

通过 SSH 在远程服务器上执行命令。

Execute commands on remote servers via SSH.

使用场景

Usage Scenarios

当用户提到以下意图时使用此 skill：

"去 [主机名/别名] 执行 [命令]"
"在 [host] 上运行 [command]"
"连接 [服务器] 并执行 [操作]"
"远程执行 [command]"
"在 [主机] 查看 [信息]"

Use this skill when the user mentions the following intents:

"Go execute [command] on [hostname/alias]"
"Run [command] on [host]"
"Connect to [server] and execute [operation]"
"Execute [command] remotely"
"Check [information] on [host]"

CLI 可用性（无需预检，失败才提示安装）

CLI Availability (No Pre-check, Prompt Installation Only on Failure)

默认直接执行

remote-shell

命令即可（绝大多数情况已安装）。不要每次先

command -v remote-shell

预检——那是浪费 token。仅当执行失败时才按其退出码走降级/提示：

执行结果 / 退出码	场景	处理
退出码 0	成功	直接返回结果
`command not found` / 退出码 127	CLI 未安装	停止并提示用户手动安装，装好再继续（见下）
其他非 0 退出码	主机/认证/连接问题	走下方「退出码获取与降级回退机制」表处理

CLI 未安装时的提示（让用户自行执行，不代装）：

bash

npm install -g remote-shell-cli

安装后需

remote-shell add

配置主机（见下文「添加主机」）。

⚠️ 本 skill 不替你安装、不做任何密码/凭据处理。主机配置由
remote-shell
CLI 承担（配置文件
~/.config/remote-shell/hosts.json
，见下文）。
重入语义：CLI 缺失造成失败后，用户装好并配置主机，重新调用本 skill 即自动放行，无需修改 skill。

Execute directly by default using the

remote-shell

command (installed in most cases). Do not pre-check with

command -v remote-shell

every time—it's a waste of tokens. Only follow the downgrade/prompt process based on the exit code when execution fails:

Execution Result / Exit Code	Scenario	Handling
Exit code 0	Success	Return the result directly
`command not found` / Exit code 127	CLI not installed	Stop and prompt the user to install manually before proceeding (see below)
Other non-0 exit codes	Host/authentication/connection issues	Handle according to the "Exit Code Acquisition and Downgrade Fallback Mechanism" table below

Prompt when CLI is not installed (let the user execute it themselves, do not install on their behalf):

bash

npm install -g remote-shell-cli

After installation, use

remote-shell add

to configure hosts (see "Add Hosts" below).

⚠️ This skill does not install for you and does not handle any passwords/credentials. Host configuration is handled by the
remote-shell
CLI (configuration file
~/.config/remote-shell/hosts.json
, see below).
Re-entry Semantics: After failure due to missing CLI, once the user installs and configures the host, re-invoking this skill will automatically proceed without modifying the skill.

使用说明

Usage Instructions

使用

remote-shell

命令在指定的远程主机上执行命令。

Use the

remote-shell

command to execute commands on the specified remote host.

重要：主机识别流程

Important: Host Identification Process

当用户提到主机名时，不要直接假设，必须按以下步骤执行：

第一步：列出主机 先用

remote-shell list

查看所有可用主机，了解：

主机别名（alias）
主机 IP/域名
端口号

第二步：匹配主机 根据用户说的主机名，匹配到配置中的 alias：

精确匹配：如用户说 "3070"，配置中 alias 是 "3070" → 直接使用
部分匹配：如用户说 "3070"，配置中 alias 是 "3070GPU" → 需要判断是否正确
模糊匹配：如用户说 "gpu 主机"，配置中有 "3070GPU"、"4090GPU" → 需要判断

第三步：执行命令 确认主机后执行命令。

When the user mentions a hostname, do not assume directly, and must follow these steps:

Step 1: List Hosts First use

remote-shell list

to view all available hosts and understand:

Host alias
Host IP/domain name
Port number

Step 2: Match Hosts Match the hostname mentioned by the user to the alias in the configuration:

Exact match: e.g., user says "3070", alias in config is "3070" → use directly
Partial match: e.g., user says "3070", alias in config is "3070GPU" → need to verify correctness
Fuzzy match: e.g., user says "gpu host", config has "3070GPU", "4090GPU" → need to verify

Step 3: Execute Command Execute the command after confirming the host.

歧义处理

Ambiguity Handling

如果无法确定用户指的是哪个主机（有两个以上相似的主机），必须使用 question 工具询问用户确认。

歧义示例：

用户说 "去 3070 执行" → 配置中有 "3070GPU" 和 "3070TIGPU" 两个
用户说 "去 dev 服务器" → 配置中有 "dev Beijing" 和 "dev Shanghai"

询问时要给出选项，让用户选择。

If it's impossible to determine which host the user refers to (two or more similar hosts), must use the question tool to ask the user for confirmation.

Ambiguity Examples:

User says "Go execute on 3070" → config has "3070GPU" and "3070TIGPU"
User says "Go to dev server" → config has "dev Beijing" and "dev Shanghai"

Provide options when asking, let the user choose.

命令

Commands

列出可用主机

List Available Hosts

bash

remote-shell list

bash

remote-shell list

执行命令

Execute Command

bash

remote-shell <别名> '<命令>'

⚠️ 示例 alias（如下方
3070
、
dev
）仅为示意，实际可用别名以
remote-shell list
输出为准，不要硬编码或假设具体主机名。

重要：必须使用单引号包裹命令

原因：命令中如果包含

变量引用（如

$PATH

、

$i

），双引号会导致本地 shell 先展开变量，可能导致意外行为。

bash

undefined

bash

remote-shell <alias> '<command>'

⚠️ The example aliases (such as
3070
,
dev
below) are for illustration only. Actual available aliases are subject to the output of
remote-shell list
, do not hardcode or assume specific hostnames.

Important: Must wrap the command in single quotes

Reason: If the command contains

variable references (such as

$PATH

$i

), double quotes will cause the local shell to expand the variable first, which may lead to unexpected behavior.

bash

undefined

正确：单引号，$PATH 原样传给远程

Correct: Single quotes, $PATH is passed to the remote as-is

remote-shell <别名> 'echo $PATH'

remote-shell <alias> 'echo $PATH'

错误：双引号，本地 $PATH 会被展开

Incorrect: Double quotes, local $PATH will be expanded

remote-shell <别名> "echo $PATH"

undefined

remote-shell <alias> "echo $PATH"

undefined

显示帮助

Show Help

bash

remote-shell --help

bash

remote-shell --help

添加主机

Add Hosts

支持交互式添加和参数化添加两种方式：

bash

undefined

Supports both interactive and parameterized addition:

bash

undefined

交互式添加（按提示输入各项信息）

Interactive addition (enter information as prompted)

remote-shell add

参数化添加（各项参数可组合使用）

Parameterized addition (parameters can be combined)

remote-shell add --alias <别名> --host <主机> --username <用户名> --password <密码>


参数说明：

| 参数               | 说明                            |
| ------------------ | ------------------------------- |
| `--alias`          | 主机别名（必填）                |
| `--host`           | 主机 IP 或域名（必填）          |
| `--port`           | SSH 端口（默认 22）             |
| `--username`       | SSH 用户名（必填）              |
| `--password`       | SSH 密码（与私钥二选一）        |
| `--privateKeyPath` | SSH 私钥路径（与密码二选一）    |
| `--timeout`        | SSH 握手超时毫秒数（默认 5000） |

> ⚠️ 注意：`--password`/`--privateKeyPath` 必填其一，且**禁止在 skill 内容或对话中明文写入真实密码**。

remote-shell add --alias <alias> --host <host> --username <username> --password <password>


Parameter Description:

| Parameter | Description |
| --------- | ----------- |
| `--alias` | Host alias (required) |
| `--host` | Host IP or domain name (required) |
| `--port` | SSH port (default 22) |
| `--username` | SSH username (required) |
| `--password` | SSH password (choose either this or private key) |
| `--privateKeyPath` | SSH private key path (choose either this or password) |
| `--timeout` | SSH handshake timeout in milliseconds (default 5000) |

> ⚠️ Note: Either `--password`/`--privateKeyPath` is required, and **it is forbidden to write real passwords in skill content or conversations in plain text**.

删除主机

Delete Hosts

bash

undefined

bash

undefined

按别名删除

Delete by alias

remote-shell delete <别名>

remote-shell delete <alias>

交互式选择删除

Interactive selection for deletion

remote-shell delete

undefined

remote-shell delete

undefined

指定配置文件

Specify Configuration File

bash

remote-shell --config <路径> <别名> <命令>

bash

remote-shell --config <path> <alias> <command>

错误处理

Error Handling

当别名不存在时，会报错并显示所有可用的主机别名：

bash

$ remote-shell nonexistent 'echo test'
No hosts found for alias: nonexistent

Available hosts:
  <别名1> -> <用户>@<主机>:<端口>

⚠️ 上方的
Available hosts
内容仅为示意，实际以
remote-shell list
输出为准。

When the alias does not exist, an error will be reported and all available host aliases will be displayed:

bash

$ remote-shell nonexistent 'echo test'
No hosts found for alias: nonexistent

Available hosts:
  <alias1> -> <user>@<host>:<port>

⚠️ The
Available hosts
content above is for illustration only, actual content is subject to the output of
remote-shell list
.

配置文件

Configuration File

配置文件位置

Configuration File Location

默认：

~/.config/remote-shell/hosts.json

（XDG 标准）

可通过

--config <路径>

或设置

XDG_CONFIG_HOME

环境变量覆盖。

Default:

~/.config/remote-shell/hosts.json

(XDG standard)

Can be overridden via

--config <path>

or setting the

XDG_CONFIG_HOME

environment variable.

配置文件格式

Configuration File Format

hosts.json

是一个 JSON 对象，包含

hosts

map，每个键为主机别名，值为主机配置对象：

字段	类型	说明
`alias`	string	主机别名，用于命令中引用
`host`	string	主机 IP 或域名
`port`	number	SSH 端口，默认 22
`username`	string	SSH 用户名（注意是 `username` 不是 `user` ）
`password`	string	SSH 密码（与 `privateKeyPath` 二选一）
`privateKeyPath`	string	SSH 私钥路径（与 `password` 二选一）
`timeout`	number	SSH 握手超时毫秒数，默认 5000

示例（仅展示结构，实际主机以

remote-shell list

输出为准，请勿写入真实密码）：

json

{
  "hosts": {
    "example-host": {
      "alias": "example-host",
      "host": "192.168.1.100",
      "port": 22,
      "username": "ubuntu",
      "privateKeyPath": "~/.ssh/dev-key",
      "timeout": 5000
    }
  }
}

hosts.json

is a JSON object containing a

hosts

map, where each key is the host alias and the value is the host configuration object:

Field	Type	Description
`alias`	string	Host alias, used for reference in commands
`host`	string	Host IP or domain name
`port`	number	SSH port, default 22
`username`	string	SSH username (note it's `username` not `user` )
`password`	string	SSH password (choose either this or `privateKeyPath` )
`privateKeyPath`	string	SSH private key path (choose either this or `password` )
`timeout`	number	SSH handshake timeout in milliseconds, default 5000

Example (structure only, actual hosts are subject to

remote-shell list

output, do not write real passwords):

json

{
  "hosts": {
    "example-host": {
      "alias": "example-host",
      "host": "192.168.1.100",
      "port": 22,
      "username": "ubuntu",
      "privateKeyPath": "~/.ssh/dev-key",
      "timeout": 5000
    }
  }
}

退出码获取与降级回退机制

Exit Code Acquisition and Downgrade Fallback Mechanism

每次执行
remote-shell
后立即检查退出码：

bash

remote-shell <别名> '<命令>'; echo "EXIT:$?"

必须基于 exit code 精确判断是否降级——禁止"执行失败就直接切 sshpass"的经验式跳过。降级条件见下表：

exit code	场景	是否降级	降级策略
0	成功执行	❌ 不降级	直接返回结果给用户
1	连接拒绝/主机不可达/连接丢失	✅ 降级	使用 sshpass 重试
2	SSH 握手超时	✅ 降级	使用 sshpass 重试
5	认证失败/配置错误	✅ 降级	使用 sshpass + 密码表重试
126/127	权限不足/命令未找到（ `remote-shell` 不在 PATH）	⚠️ 降级前报告	①向用户报告"remote-shell 不可用或权限不足"；②询问是否继续 sshpass
其他非以上	未预期的内部错误	⚠️ 谨慎降级	①向用户展示完整 stderr；②不等待用户回复，立即用 sshpass 重试

降级执行方式：使用 sshpass 直接 SSH 重试（连接参数与

remote-shell list

输出一致，密码取自本机密码表）。

降级约束：

执行 sshpass 时，禁止在展示给用户的输出中回显完整命令行（密码会泄露），需截断为
```
sshpass ... ssh <用户>@<主机> '<命令摘要>'
```
格式，或仅展示退出码 + 操作摘要
禁止在 skill 内容、示例或对话中写入任何真实密码；密码仅从本机密码表读取使用，不展示、不回显
每次发起新的远程命令，必须重新从
```
remote-shell
```
开始尝试，不允许因上次 sshpass 成功而跳过
如果
```
remote-shell
```
和
```
sshpass
```
都失败，停止尝试，将两次失败信息展示给用户并给出排查建议（①手动
```
ssh
```
验证连通性；②确认密码表条目是否过期；③检查是否需要跳板机）

补充：命令执行错误提示：

错误场景	表现	处理方式
命令执行超时	命令长时间无输出	建议使用 `timeout` 包装命令，如 `timeout 30 <command>`
主机密钥变更	输出类似 `WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED`	提示用户使用 `ssh-keygen -R <host>` 清理旧密钥

如果执行出错，将错误信息原样返回给用户，并根据上述表格提供处理建议。

⚠️ 在降级流程中，不要因为退出码而反复询问用户——只在
remote-shell
不可用（126/127）或用户主动表示退出时，才建议用户自行执行命令。

Check the exit code immediately after each
remote-shell
execution:

bash

remote-shell <alias> '<command>'; echo "EXIT:$?"

Must precisely determine whether to downgrade based on exit code—empirical skipping like "switch directly to sshpass on execution failure" is prohibited. Downgrade conditions are shown in the table below:

exit code	Scenario	Downgrade or Not	Downgrade Strategy
0	Execution successful	❌ Do not downgrade	Return the result directly to the user
1	Connection refused/host unreachable/connection lost	✅ Downgrade	Retry using sshpass
2	SSH handshake timeout	✅ Downgrade	Retry using sshpass
5	Authentication failure/configuration error	✅ Downgrade	Retry using sshpass + password table
126/127	Insufficient permissions/command not found ( `remote-shell` not in PATH)	⚠️ Report before downgrade	①Report to user "remote-shell is unavailable or insufficient permissions"; ②Ask if user wants to proceed with sshpass
Other non-above	Unexpected internal error	⚠️ Downgrade cautiously	①Show complete stderr to user; ②Do not wait for user reply, immediately retry with sshpass

Downgrade Execution Method: Retry directly via SSH using sshpass (connection parameters are consistent with

remote-shell list

output, password is read from the local password table).

Downgrade Constraints:

When executing sshpass, forbid echoing the complete command line in output shown to users (password will be leaked), truncate to format like
```
sshpass ... ssh <user>@<host> '<command summary>'
```
, or only show exit code + operation summary
Forbid writing any real passwords in skill content, examples or conversations; passwords are only read from the local password table for use, not displayed or echoed
For each new remote command attempt, must start with
```
remote-shell
```
again, skipping it is not allowed even if sshpass succeeded last time
If both
```
remote-shell
```
and sshpass fail, stop attempting, show both failure messages to the user and provide troubleshooting suggestions (①Manually verify connectivity with
```
ssh
```
; ②Confirm if password table entries are expired; ③Check if a jump host is required)

Supplement: Command Execution Error Prompt:

Error Scenario	Performance	Handling Method
Command execution timeout	No output for a long time	Suggest wrapping the command with `timeout` , e.g., `timeout 30 <command>`
Host key changed	Output similar to `WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED`	Prompt user to clean old keys with `ssh-keygen -R <host>`

If execution fails, return the error message as-is to the user and provide handling suggestions according to the above table.

⚠️ In the downgrade process, do not repeatedly ask the user due to exit codes—only suggest the user execute the command themselves when
remote-shell
is unavailable (126/127) or when the user actively requests to exit.

示例

Examples

⚠️ 以下示例中的 alias（
3070
、
dev
）仅为示意，实际可用别名以
remote-shell list
输出为准。

查看 CPU 和内存：

bash

remote-shell 3070 'uptime && free -h'

查看 GPU 状态：

bash

remote-shell 3070 'nvidia-smi'

列出 dev 服务器上的文件：

bash

remote-shell dev 'ls -la /tmp'

实时监控日志（流式输出）：

bash

remote-shell dev 'tail -f /var/log/syslog'

⚠️ The aliases (
3070
,
dev
) in the following examples are for illustration only. Actual available aliases are subject to the output of
remote-shell list
.

Check CPU and memory:

bash

remote-shell 3070 'uptime && free -h'

Check GPU status:

bash

remote-shell 3070 'nvidia-smi'

List files on dev server:

bash

remote-shell dev 'ls -la /tmp'

Real-time log monitoring (streaming output):

bash

remote-shell dev 'tail -f /var/log/syslog'