sshc-operations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sshc Operations

sshc 操作

Use this skill to execute sshc-rs tasks safely and predictably.

使用该技能可安全且可预测地执行sshc-rs相关任务。

Intent Routing (First Decision)

意图路由（首要决策项）

Discover available hosts/groups:
```
sshc list
```
(or
```
sshc l
```
).
Open SSH shell on one host:
```
sshc c <name>
```
(or plain
```
sshc
```
for interactive picker).
Open SFTP/FileZilla workflow:
```
sshc f <name>
```
(or plain
```
sshc f
```
for interactive picker).
Run non-interactive command and collect output:
```
sshc run <target> -- <cmd>
```
.
Run interactive/full-screen program (
```
vim
```
,
```
top
```
,
```
less
```
, REPL):
```
sshc tty <name> -- <cmd>
```
.
Upload/download files or directories:
```
sshc up ...
```
/
```
sshc down ...
```
.
Manage saved hosts/groups:
```
sshc config ...
```
.
Script/JSON integration:
```
sshc api ...
```
only when machine-readable output is required.
Diagnose environment/network/config:
```
sshc doctor [name]
```
.
Migrate config between machines:
```
sshc export
```
/
```
sshc import
```
.

查看可用主机/主机组：
```
sshc list
```
（或
```
sshc l
```
）。
在单台主机上打开SSH shell：
```
sshc c <name>
```
（或直接输入
```
sshc
```
唤起交互式选择器）。
打开SFTP/FileZilla工作流：
```
sshc f <name>
```
（或直接输入
```
sshc f
```
唤起交互式选择器）。
运行非交互式命令并收集输出：
```
sshc run <target> -- <cmd>
```
。
运行交互式/全屏程序（
```
vim
```
、
```
top
```
、
```
less
```
、REPL）：
```
sshc tty <name> -- <cmd>
```
。
上传/下载文件或目录：
```
sshc up ...
```
/
```
sshc down ...
```
。
管理已保存的主机/主机组：
```
sshc config ...
```
。
脚本/JSON集成：仅当需要机器可读的输出时使用
```
sshc api ...
```
。
诊断环境/网络/配置问题：
```
sshc doctor [name]
```
。
在多台机器间迁移配置：
```
sshc export
```
/
```
sshc import
```
。

CRITICAL: Privilege Escalation with sudo

重要提示：使用sudo提权

Many remote operations require elevated privileges. You MUST automatically detect when a command needs sudo and use the
sudo
subcommand — never use bare
sudo
inside the remote command string.

很多远程操作需要提升权限。你必须自动识别命令何时需要sudo，并使用
sudo
子命令——绝对不要在远程命令字符串内直接使用裸
sudo
。

When to use sudo

何时使用sudo

Use

sshc run sudo

sshc tty sudo

when the remote command involves ANY of the following:

Service management:

systemctl start|stop|restart|reload|enable|disable <service>

service <name> start|stop|restart

Package management:

apt install|remove|update|upgrade

yum install|remove

dnf install|remove

pacman -S|-R

System configuration: editing files under
```
/etc/
```
,
```
/sys/
```
,
```
/proc/
```
, running
```
sysctl
```
,
```
hostnamectl
```
File operations on protected paths: reading/writing
```
/var/log/
```
,
```
/opt/
```
,
```
/usr/local/
```
,
```
/root/
```
User/group management:
```
useradd
```
,
```
usermod
```
,
```
groupadd
```
,
```
passwd
```
Network configuration:
```
iptables
```
,
```
ip route
```
,
```
ip link
```
,
```
firewall-cmd
```
,
```
ufw
```
Disk/filesystem operations:
```
mount
```
,
```
umount
```
,
```
fdisk
```
,
```
mkfs
```
,
```
fsck
```
System control:
```
reboot
```
,
```
shutdown
```
,
```
poweroff
```
,
```
init
```
Docker/container operations:
```
docker ...
```
(when Docker requires root),
```
systemctl restart docker
```
Permission changes:
```
chmod
```
,
```
chown
```
on system-owned files
Any command that would fail with "Permission denied" without root

当远程命令涉及以下任意场景时，使用

sshc run sudo

或

sshc tty sudo

：

服务管理：

systemctl start|stop|restart|reload|enable|disable <service>

、

service <name> start|stop|restart

包管理：

apt install|remove|update|upgrade

、

yum install|remove

、

dnf install|remove

、

pacman -S|-R

系统配置：编辑
```
/etc/
```
、
```
/sys/
```
、
```
/proc/
```
路径下的文件，运行
```
sysctl
```
、
```
hostnamectl
```
受保护路径的文件操作：读写
```
/var/log/
```
、
```
/opt/
```
、
```
/usr/local/
```
、
```
/root/
```
路径下的内容
用户/用户组管理：
```
useradd
```
、
```
usermod
```
、
```
groupadd
```
、
```
passwd
```
网络配置：
```
iptables
```
、
```
ip route
```
、
```
ip link
```
、
```
firewall-cmd
```
、
```
ufw
```
磁盘/文件系统操作：
```
mount
```
、
```
umount
```
、
```
fdisk
```
、
```
mkfs
```
、
```
fsck
```
系统控制：
```
reboot
```
、
```
shutdown
```
、
```
poweroff
```
、
```
init
```
Docker/容器操作：
```
docker ...
```
（当Docker需要root权限时）、
```
systemctl restart docker
```
权限修改：对系统所属文件执行
```
chmod
```
、
```
chown
```
任何非root用户执行会报“Permission denied”错误的命令

Syntax

语法

sudo

is a subcommand of

run

and

tty

, NOT a flag or prefix:

bash

undefined

sudo

是

run

和

tty

的子命令，不是参数或者前缀：

bash

undefined

Correct — sudo as subcommand

sshc run sudo prod -- systemctl restart nginx sshc run sudo @backend -p -- apt update sshc tty sudo prod -- vim /etc/nginx/nginx.conf

WRONG — never do this

sshc run prod -- sudo systemctl restart nginx # ← will NOT work sshc run prod -- systemctl restart nginx # ← will fail with permission denied

undefined

sshc run prod -- sudo systemctl restart nginx # ← will NOT work sshc run prod -- systemctl restart nginx # ← will fail with permission denied

undefined

Decision rule

决策规则

Before constructing any

sshc run

sshc tty

command, ask yourself: "Would this command fail with 'Permission denied' if executed as a non-root user?" If yes, insert

sudo

as the subcommand:

Without sudo:
```
sshc run <target> -- <cmd>
```
With sudo:
```
sshc run sudo <target> -- <cmd>
```
Without sudo:
```
sshc tty <name> -- <cmd>
```
With sudo:
```
sshc tty sudo <name> -- <cmd>
```

在构造任何

sshc run

或

sshc tty

命令前，先问自己：“如果以非root用户执行这个命令，会不会报‘Permission denied’错误？” 如果答案是是，就插入

sudo

作为子命令：

无需sudo：
```
sshc run <target> -- <cmd>
```
需要sudo：
```
sshc run sudo <target> -- <cmd>
```
无需sudo：
```
sshc tty <name> -- <cmd>
```
需要sudo：
```
sshc tty sudo <name> -- <cmd>
```

Commands that do NOT need sudo

无需使用sudo的命令

Reading public info:
```
uname -a
```
,
```
hostname
```
,
```
date
```
,
```
uptime
```
,
```
whoami
```
,
```
id
```
Listing files you own:
```
ls
```
,
```
cat
```
on user-accessible files
Checking service status (read-only):
```
systemctl status <service> --no-pager
```
Disk usage (read-only):
```
df -h
```
,
```
free -m
```
,
```
top
```
,
```
htop
```
User's own processes:
```
ps aux
```
,
```
pgrep
```

读取公开信息：
```
uname -a
```
、
```
hostname
```
、
```
date
```
、
```
uptime
```
、
```
whoami
```
、
```
id
```
列出你拥有权限的文件：对用户可访问的文件执行
```
ls
```
、
```
cat
```
查看服务状态（只读）：
```
systemctl status <service> --no-pager
```
磁盘使用情况（只读）：
```
df -h
```
、
```
free -m
```
、
```
top
```
、
```
htop
```
用户自身的进程：
```
ps aux
```
、
```
pgrep
```

Default Workflow

默认工作流

Confirm user goal: connect, command execution, transfer, config change, diagnosis, or migration.
Select the narrowest command for that goal.
For target discovery, default to
```
sshc list
```
(never
```
api/config
```
by default).
Execute directly once target is clear.
Show the exact command before destructive operations.

确认用户目标：连接、命令执行、文件传输、配置修改、诊断还是配置迁移。
选择最匹配该目标的命令。
如需查找目标，默认使用
```
sshc list
```
（默认不要使用
```
api/config
```
）。
目标明确后直接执行。
执行破坏性操作前展示确切的命令。

Command Semantics (From Runtime Behavior)

命令语义（基于运行时行为）

```
run
```
target supports:
- Exact host name:
```
prod
```
- Group:
```
@backend
```
- All hosts:
```
all
```
  or
```
*
```
- Fuzzy match: substring against host key or display name
```
tty
```
target supports only exact single host name. It rejects
```
@group
```
,
```
all
```
,
```
*
```
, and fuzzy names.
```
run
```
defaults to serial; add
```
-p/--parallel
```
for parallel execution.
```
run sudo
```
and
```
tty sudo
```
are subcommands that wrap the remote command with privilege escalation (passwordless sudo first, then falls back to saved server password). See Privilege Escalation with sudo section above for when to use them.

```
run
```
命令的目标支持：
- 精确主机名：
```
prod
```
- 主机组：
```
@backend
```
- 所有主机：
```
all
```
  或
```
*
```
- 模糊匹配：与主机key或显示名称的子串匹配
```
tty
```
命令的目标仅支持精确的单主机名。不支持
```
@group
```
、
```
all
```
、
```
*
```
和模糊名称。
```
run
```
命令默认为串行执行；添加
```
-p/--parallel
```
参数可并行执行。
```
run sudo
```
和
```
tty sudo
```
是为远程命令封装了提权逻辑的子命令（优先使用无密码sudo，失败后回退到已保存的服务器密码）。何时使用请参考上文使用sudo提权章节。

Syntax Guardrails

语法约束

Prefer explicit separator:

sshc run <target> -- <command ...>

and

sshc tty <name> -- <command ...>

For command-like user requests ("看时间", "查磁盘", "重启服务"), execute directly via
```
sshc run ...
```
, not via config inspection.

Transfer syntax:

Upload:

sshc up <local_path> <server:remote_path>

Download:

sshc down <server:remote_path> <local_path>

Config lifecycle:

Add/Edit/Show/Remove:
```
sshc config add|edit|show|remove ...
```

Group operations:

sshc config group list|add|rename|remove ...

JSON automation only:
- ```
sshc api list|get|set|rm
```

优先使用明确的分隔符：

sshc run <target> -- <command ...>

和

sshc tty <name> -- <command ...>

。

对于类命令的用户请求（“看时间”、“查磁盘”、“重启服务”），直接通过
```
sshc run ...
```
执行，不要先检查配置。

传输语法：

上传：

sshc up <local_path> <server:remote_path>

下载：

sshc down <server:remote_path> <local_path>

配置生命周期操作：

添加/编辑/查看/删除：
```
sshc config add|edit|show|remove ...
```

主机组操作：

sshc config group list|add|rename|remove ...

仅用于JSON自动化场景：
- ```
sshc api list|get|set|rm
```

Discovery and Preflight Policy

发现和预检策略

When user asks to run a remote command (for example, "看看 nas 的时间"), do not preflight with
```
sshc config show
```
or
```
sshc api list
```
.
Use
```
sshc list
```
only if target naming is uncertain.
Then execute directly with
```
sshc run <target> -- <cmd>
```
.
Example:
```
sshc list
```
then
```
sshc run nas -- date
```
.

当用户要求运行远程命令时（例如“看看nas的时间”），不要先执行
```
sshc config show
```
或
```
sshc api list
```
做预检。
仅当目标名称不明确时使用
```
sshc list
```
。
之后直接执行
```
sshc run <target> -- <cmd>
```
。
示例：先执行
```
sshc list
```
，再执行
```
sshc run nas -- date
```
。

Safe Defaults

安全默认配置

Prefer
```
-P
```
(prompted password) over
```
--password
```
to avoid shell history leakage.
Avoid exposing secrets from
```
api get
```
, import/export payloads, or config fields.
Use serial execution for risky operations (service restart, file mutation, package changes).
Use
```
-p/--parallel
```
only for idempotent and low-blast-radius tasks (read-only checks, status collection).
For potentially destructive remote commands, ask for confirmation and target scope first.

优先使用
```
-P
```
（提示输入密码）而非
```
--password
```
，避免shell历史泄露密码。
避免暴露
```
api get
```
、导入/导出 payload 或配置字段中的敏感信息。
对风险操作（服务重启、文件修改、包变更）使用串行执行。
仅对幂等、影响范围小的任务（只读检查、状态收集）使用
```
-p/--parallel
```
并行执行。
对于可能有破坏性的远程命令，先确认用户意图和目标范围再执行。

Troubleshooting Order

排查顺序

Verify command syntax:
```
sshc --help
```
or subcommand
```
--help
```
.
Validate target names with
```
sshc list
```
.
Run
```
sshc doctor
```
(or
```
sshc doctor <name>
```
) for environment and reachability.
Retry with the smallest reproducer command (single host, simple command).
Use
```
sshc config show <name>
```
only for config debugging.
Use
```
sshc api get <name>
```
only when JSON inspection is explicitly required.

验证命令语法：执行
```
sshc --help
```
或子命令加
```
--help
```
查看。
执行
```
sshc list
```
验证目标名称是否正确。
运行
```
sshc doctor
```
（或
```
sshc doctor <name>
```
）检查环境和连通性。
用最小可复现命令重试（单主机、简单命令）。
仅在调试配置问题时使用
```
sshc config show <name>
```
。
仅在明确要求JSON格式排查时使用
```
sshc api get <name>
```
。

References

参考资料

Read references/command-recipes.md for detailed syntax and ready-to-run examples.

阅读 references/command-recipes.md 查看详细语法和可直接运行的示例。