跳到主要内容

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 操作的服务器都是从哪里来的。