wsh 命令
wsh 是 Termia 的命令行伴侣。它连接的是驱动图形界面的同一个 wavesrv 后端,所以凡是你用鼠标能做
的事——打开一个文件预览、新建一个终端、读取另一个区块存的变量、连接到某台主机——都可以在命令行
里完成。它是你终端里的命令与 Termia 的区块、标签页、工作区之间的桥梁。
它在哪里可用
wsh 在你打开的每一个终端区块里都已经在 PATH 上了,无论是本机还是通过 SSH、WSL 连接的远程主
机。你不需要安装或配置任何东西——Termia 会自动完成这一切。
- 本机终端:Termia 会把
wsh二进制文件复制到自己的数据目录,并通过它为 zsh、bash、fish、 PowerShell 管理的 shell 启动文件把这个目录加进PATH。这一步发生在你自己的.zshrc/.bashrc执行之前。 - 远程主机(SSH):第一次连接某台主机时,Termia 会探测那台主机上是否已有
wsh;如果没有,就 通过同一个 SSH 会话把对应操作系统/架构的二进制文件复制到~/.termia/bin/wsh。此后,任何连接到 这台主机的终端区块也会自动在PATH里看到wsh。如果安装失败或版本过旧,可以用wsh conn ensure或wsh conn reinstall强制重新安装。 - WSL:对
wsl://连接同样适用这套机制。
想知道 wsh 本身和它的数据到底放在你机器上的什么位置,直接问 wsh 本身,而不要去猜路径:
wsh wavepath config # settings.json、presets.json、widgets.json 等
wsh wavepath data # wsh 二进制文件、shell 集成文件、本机区块存储
wsh wavepath log # wavesrv 的日志文件
wsh wavepath log --tail # 打印日志最后 100 行
如何指定一个区块
大多数 wsh 命令都作用于某个区块、标签页或工作区,并通过 -b/--block 参数指定目标。省略时,
默认使用你当前所在终端的那个区块。-b 支持以下几种简写形式:
| 值 | 含义 |
|---|---|
this(默认) | 你当前所在终端的区块 |
tab | 当前标签页 |
workspace(或 ws) | 当前工作区 |
client(或 global) | 客户端范围,跨所有窗口共享 |
5 | 当前标签页里的第 5 个区块,按从左上到右下编号 |
tab:2 | 当前工作区里的第 2 个标签页 |
term 或 term:2 | 当前标签页里第 1 个(或第 2 个)视图为 term 的区块 |
a67f55a3 | 截断为前 8 位的区块/标签页 id |
d6ff4966-231a-4074-b78a-20acc7226b41 | 完整 id |
按住 Ctrl+Shift(在 macOS、Windows、Linux 上都是同一个物理按键)可以让当前标签页里每个区块都
显示编号浮层;也可以右键点击某个区块的标题栏,选择复制区块 ID,拿到它的完整 id 用于脚本。
常用命令导览
打开东西
# 预览或编辑一个文件(目录、图片、markdown、代码都可以)
wsh view ./README.md
wsh view .
# 强制用图形编辑器打开,并等它关闭(适合当 $EDITOR 用)
wsh edit ./notes.txt
# 在 web 区块里打开一个网址
wsh web open https://example.com
# 在某个目录下打开一个新终端
wsh term ./myproject
# 在独立的区块里跑一条命令,成功退出后自动关闭
wsh run -x -- npm test
一个区块的元数据、变量和文件
# 看看 wavesrv 对你正在输入命令的这个区块都知道些什么
wsh getmeta
# 换成看编号为 3 的区块
wsh getmeta -b 3
# 只读一个 key
wsh getmeta file
# 修改某个区块使用的连接
wsh setmeta -b 3 connection=myhost
# 存一个重启也不会丢的值,范围是整个客户端
wsh setvar DEPLOY_ENV=staging
# 在任意终端里读回来
echo $(wsh getvar DEPLOY_ENV)
# 存一个文件,本机或远程的任何区块都能读到
echo "hello" | wsh file write wavefile://client/greeting.txt
wsh file cat wavefile://client/greeting.txt
连接与服务器
# 查看每一个 SSH/WSL 连接以及它当前是否已连接
wsh conn status
# 列出保存的服务器(Vault 主机 + connections.json 里的临时连接)
wsh server list
# 让当前终端连接到某台远程主机
wsh ssh myuser@myhost
# 打开一个新终端,直接连接到某台已保存的服务器(如果有 Vault 密码会自动使用)
wsh server open myuser@myhost
服务器是如何进入这个列表的,见 主机与 Vaults;连接的完整生命周期见 连接。
在命令行里使用 Termia Agent
# 在远程主机上打开一个新终端,直接交给 Termia Agent 并带上一个任务
wsh task myuser@myhost "检查磁盘占用,清理 /tmp 下一周以前的文件"
在任意终端区块里输入 tt 并回车,就能在那个区块里交互式启动 Termia Agent。wsh task 则是
把这一整套流程压缩成一步,专门用于你还没在上面打开过终端的主机——它会确保连接可用、打开一个终端,
并带着初始 prompt 启动 agent。agent 启动后能做什么,见 Termia Agent。
其他命令
# 设置标签页的背景图片或颜色
wsh setbg ./wallpaper.jpg
wsh setbg "#1a1a2e"
wsh setbg --clear
# 从脚本里触发一条桌面通知
long-build-command && wsh notify "构建完成"
# 按 id 启动一个已配置的 widget
wsh launch sysinfo
获取帮助

每个命令都支持 -h/--help,不带任何参数运行 wsh 会打印完整的命令列表。wsh version 打印 CLI
的版本号;wsh version -v 还会额外打印你的配置目录、数据目录以及所在的更新渠道。
接下来看
- wsh 命令参考——每个命令、它的参数,以及一个示例。
- wsh 架构——
wsh底层是如何与wavesrv通信的。 - 主机与 Vaults——
wsh server和wsh conn操作的服务器都是从哪里来的。