remote-shell
Execute commands on remote servers via SSH.
Usage Scenarios
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 Availability (No Pre-check, Prompt Installation Only on Failure)
Execute directly by default using the
command (installed in most cases).
Do not pre-check with
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 |
| / 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
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
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
Use the
command to execute commands on the specified remote host.
Important: Host Identification Process
When the user mentions a hostname, do not assume directly, and must follow these steps:
Step 1: List Hosts
First use
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
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
Execute Command
bash
remote-shell <alias> '<command>'
⚠️ The example aliases (such as
,
below) are for illustration only.
Actual available aliases are subject to the output of , do not hardcode or assume specific hostnames.
Important: Must wrap the command in single quotes
Reason: If the command contains
variable references (such as
,
), double quotes will cause the local shell to expand the variable first, which may lead to unexpected behavior.
bash
# Correct: Single quotes, $PATH is passed to the remote as-is
remote-shell <alias> 'echo $PATH'
# Incorrect: Double quotes, local $PATH will be expanded
remote-shell <alias> "echo $PATH"
Show Help
Add Hosts
Supports both interactive and parameterized addition:
bash
# Interactive addition (enter information as prompted)
remote-shell add
# Parameterized addition (parameters can be combined)
remote-shell add --alias <alias> --host <host> --username <username> --password <password>
Parameter Description:
| Parameter | Description |
|---|
| Host alias (required) |
| Host IP or domain name (required) |
| SSH port (default 22) |
| SSH username (required) |
| SSH password (choose either this or private key) |
| SSH private key path (choose either this or password) |
| SSH handshake timeout in milliseconds (default 5000) |
⚠️ Note: Either
/
is required, and
it is forbidden to write real passwords in skill content or conversations in plain text.
Delete Hosts
bash
# Delete by alias
remote-shell delete <alias>
# Interactive selection for deletion
remote-shell delete
Specify Configuration File
bash
remote-shell --config <path> <alias> <command>
Error Handling
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
content above is for illustration only, actual content is subject to the output of
.
Configuration File
Configuration File Location
Default:
~/.config/remote-shell/hosts.json
(XDG standard)
Can be overridden via
or setting the
environment variable.
Configuration File Format
is a JSON object containing a
map, where each key is the host alias and the value is the host configuration object:
| Field | Type | Description |
|---|
| string | Host alias, used for reference in commands |
| string | Host IP or domain name |
| number | SSH port, default 22 |
| string | SSH username (note it's not ) |
| string | SSH password (choose either this or ) |
| string | SSH private key path (choose either this or ) |
| number | SSH handshake timeout in milliseconds, default 5000 |
Example (structure only, actual hosts are subject to
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
Check the exit code immediately after each 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 ( 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
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>'
- 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 again, skipping it is not allowed even if sshpass succeeded last time
- If both and sshpass fail, stop attempting, show both failure messages to the user and provide troubleshooting suggestions (①Manually verify connectivity with ; ②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 , e.g., |
| Host key changed | Output similar to WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED
| Prompt user to clean old keys with |
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
is unavailable (126/127) or when the user actively requests to exit.
Examples
⚠️ The aliases (
,
) in the following examples are for illustration only.
Actual available aliases are subject to the output of .
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'