wsh 命令参考
这是 macOS 版 wsh 的完整命令参考。想看引导式的入门介绍——二进制从哪来、怎么装到远端主机上、
-b/--block 怎么寻址一个面板、标签页或窗口——先读 wsh 命令;这一页不会
重复那部分内容。
wsh 对接的是和 Windows/Linux 应用同一个 wavesrv 后端,所以这里的大多数命令只是创建或读取
纯粹的后端对象(面板、元数据、变量、文件),不管哪个应用在跑都完全一样。少数几条命令则是要求
正在运行的应用本身去做点什么——弹一条通知、读一个网页面板的 DOM、报告更新通道。macOS 能
应答的正好就是 wsh 怎么“喊话”回应用 覆盖的那几条;
task 通过原生端注册的每面板路由启动 TT Agent;旧聊天式 ai 命令的限制在下文标出。
下面每个命令块前面都有一行在 macOS 上的结论,依据是实际读过的
macnative/Sources/TermiaNative/PlatformIntegration.swift(回调路由)和 AppModel.swift 里
建面板的相关代码,而不是只拿 Electron 版的行为去套。
打开面板

view、edit、term、run、launch 最终都是通过同一个底层原语(createblock,隐藏命令——
见内部命令)建面板。只要面板的 view 值是 macOS 认识的那几种——term、
preview、web、gitstatus、sysinfo/cpuplot——面板就能正常打开。其他类型的 view 依然会在
wavesrv 里建出对应的后端对象(Windows/Linux 会把它渲染出来),但 macOS 只会显示一个占位面板,
写着"暂不支持的面板类型:<view>",而不是空白或报错的面板。
view / edit
wsh view [-m] {file|directory|url}
wsh edit [-m] {file}
在预览面板里打开一个文件或目录,或者在网页面板里打开一个 URL。view(别名 preview 和
open)用来查看;edit 打开同一个预览面板,但直接进入编辑模式。
参数:
-m,--magnified— 打开时直接放大这个面板。
在 macOS 上: 可用。文本、代码、Markdown 和图片都走 文件与传输里说的同一个预览面板;目录会打开成和 SFTP 面板 一样的文件浏览器。
wsh view .
wsh view ./screenshot.png
wsh edit ./config.json
wsh view https://example.com
editor
wsh editor [-m] <file>
打开一个文件进行编辑,并且一直阻塞到这个面板被关闭——这一点和立刻返回的 view/edit 不
一样,让它可以直接当 $EDITOR 用。
参数:
-m,--magnified— 打开时直接放大这个面板。
在 macOS 上: 可用。它等的是绑定在新面板 id 上的后端 blockclose 事件,不管你是在 mac 应用
还是 Electron 应用里关掉这个面板,触发方式都一样。
export EDITOR="wsh editor"
git commit
term
wsh term [-m] [directory]
打开一个新的终端面板。不给参数时在你当前工作目录打开;给了参数就在指定目录打开(~ 会展开)。
在一个连着远端主机的面板里执行,新终端会开在同一个连接上。
参数:
-m,--magnified— 打开时直接放大这个面板。
在 macOS 上: 可用,行为完全一致。
wsh term ~/projects/termia-terminal
run
wsh run [flags] -- command [args...]
wsh run [flags] -c "shell command string"
在一个新的终端面板里运行一条命令。可以在 -- 之后直接给命令(不经过 shell),也可以用 -c
给一条 shell 命令字符串——两者不能同时用。
参数:
-m,--magnified— 打开时直接放大这个面板。-c, --command <string>— 用 shell 运行这个字符串,而不是--之后的命令。-x, --exit— 命令成功退出后自动关闭面板(出错则保持打开)。-X, --forceexit— 命令一退出就关闭面板,不管退出状态如何。--delay <ms>— 配合-x/-X,关闭前等待的毫秒数(默认2000)。-p, --paused— 创建面板但不启动命令,由你自己手动启动。--cwd <path>— 命令的工作目录(默认:你当前的目录)。-a, --append— 重启时追加输出,而不是先清空面板。
在 macOS 上: 可用。它本质上还是一个 term 视图的面板,自动关闭和追加输出这些行为,走的是
和 macOS 终端面板一样的终端控制器逻辑。
wsh run -x -- npm test
wsh run -m -- npm run dev
wsh run -c "docker compose up -d"
launch
wsh launch [-m] <widget-id>
按 id 从 widgets.json 或内置的默认小组件里创建一个面板。
参数:
-m,--magnify— 打开时直接放大这个面板。
在 macOS 上: 只要小组件的 view 是 macOS 能渲染的那几种(比如 sysinfo 小组件)就可用。
如果小组件指向的 view macOS 没有对应的渲染器,依然会建出一个面板——只是一个"暂不支持的面板
类型"占位符,绝不会悄悄启动一个 shell 顶替。自定义小组件目录见插件,macOS 读
的是同一份 widgets.json。
wsh launch sysinfo
关闭面板
deleteblock
wsh deleteblock -b <ref>
删除一个面板。不接受位置参数——用 -b 指定目标(默认是当前面板,所以不带参数直接跑会关掉
你正输入命令的这个终端)。
在 macOS 上: 可用。删除是一次后端对象的移除;macOS 一旦观察到这次删除,就会把这个面板从 布局里摘掉——和它自愈一个后端对象已经不存在的面板时走的是同一条路。
wsh deleteblock -b 4
元数据
getmeta
wsh getmeta [-b <ref>] [-v] [--raw] [--clear-prefix] [key...]
把一个面板或标签页的元数据打印成 JSON。不给 key 就打印全部;给一个 key 就只打印那个值。以
:* 结尾的 key 是前缀匹配,会返回所有以这个前缀开头的 key,以及去掉末尾冒号后那个 key 本身
(如果存在的话)。
参数:
-v,--verbose— 同时把解析出来的面板/标签页 id 打印到 stderr。--raw— 对单个字符串值,原样打印而不加 JSON 引号。--clear-prefix— 配合key:*模式,同时带上那个特殊的清除键。
在 macOS 上: 可用,行为完全一致——纯粹的元数据读取,不涉及任何渲染。
wsh getmeta
wsh getmeta -b 2 file
wsh getmeta -b tab "bg:*"
setmeta
wsh setmeta [-b <ref>] [--json file.json] key=value ...
给一个面板或标签页设置一个或多个元数据键。值会尽量按 JSON 解析
(true/false/null、数字、[...]/{...}/"..."),解析不了就当作普通字符串。key 里带
/ 表示嵌套路径(a/b=1 会设成 {"a": {"b": 1}})。把某个 key 设为 null 会删掉它。
参数:
--json <file>— 从一个 JSON 文件加载一份基础元数据(-读取 stdin);命令行上直接给的值 会覆盖文件里的同名 key。
在 macOS 上: 可用,包括实际用得最多的那几种情况——设置 connection 会按新的主机重建这个
面板的视图(和面板设置菜单走的是同一条"先写元数据、再重建"的路径),给标签页设置
bg/bg:* 会重画它的背景(关于位置/铺陈方式的一个限制,见下文 setbg)。
wsh setmeta -b 3 file=~/notes.txt
wsh setmeta -b tab bg=blue bg:opacity=0.3
wsh setmeta -b tab --json -
变量
getvar/setvar 读写一份按面板存放(默认是客户端范围)的小型键值存储,底层用的和 file 用
wavefile:// 寻址的是同一套文件存储。两者都是纯粹的后端操作、不涉及渲染,所以在 macOS 上表现
完全一致。
getvar
wsh getvar [-l] [--varfile name] <key>
wsh getvar [-l] --all [-0] [-n|-N]
读取此前用 setvar 存下的变量。不带 --all 时必须给一个 key;值会打印到 stdout,末尾不带
换行符,除非 stdout 是一个终端(或用 -n 强制加换行)。key 不存在时以状态码 1 退出。
参数:
--varfile <name>— 变量文件名(默认var)。--all— 打印全部变量,而不是单个 key。-0,--null— 配合--all,用空字节而不是换行分隔各条。-l,--local— 从当前面板读取,而不是客户端范围。-n,--newline— 始终打印末尾换行。-N,--no-newline— 从不打印末尾换行。
不加 -b 或 -l 时,getvar 读的是客户端范围(全局)变量,不是当前面板的。
在 macOS 上: 可用,行为完全一致。
wsh setvar API_TOKEN=abc123
curl -H "Authorization: $(wsh getvar API_TOKEN)" https://example.com
wsh getvar --all
setvar
wsh setvar [-l] [--varfile name] KEY=VALUE...
wsh setvar [-l] -r KEY...
存储一个或多个变量。默认是客户端范围,除非给了 -l/--local 或 -b。
参数:
--varfile <name>— 变量文件名(默认var)。-l,--local— 存到当前面板,而不是客户端范围。-r,--remove— 删除给定的 key,而不是设置它们。
在 macOS 上: 可用,行为完全一致。
wsh setvar DEPLOY_ENV=staging
wsh setvar -l BUILD_NUM=42
wsh setvar -r DEPLOY_ENV
文件
wsh file <subcommand> [flags] <uri>...
通过 URI 管理三种存储系统里的文件:wsh://[connection]/[path](一条 wsh 能到达的路径,
本机或远端都行)、wavefile://[zoneid]/[path](Termia 内部的面板/标签页/客户端文件存
储——setvar/getvar 就是建在它上面的),以及 s3://[bucket]/[path](也可以写成
[profile]:s3://...)。所有 file 子命令都支持 -t/--timeout <ms>(默认 15000)。
在 macOS 上: 每一个 file 子命令都可用,行为完全一致。它们都不做任何渲染——走的都是
文件与传输里 SFTP 面板用的同一套 Go 文件共享后端,那一页的界面虽然是
macOS 专属的,底层传输代码却是共用的。
file ls
wsh file ls [-r] [-l] [-1] [-f] [uri]
列出一个目录(不给参数就是当前目录)。-r 递归,-l 用长格式列出,-1 每行一个名字(管道
输出时自动如此),-f 只列文件。
wsh file ls wsh://myuser@myhost/home/myuser/
wsh file ls -l wavefile://client/
file cat
wsh file cat <uri>
把文件内容打印到 stdout。
wsh file cat wavefile://client/notes.txt
file info
wsh file info <uri>
打印文件的名字、权限模式、修改时间、大小,以及任何存储的元数据。
wsh file info wsh://myhost/etc/nginx/nginx.conf
file write
echo "..." | wsh file write <uri>
把 stdin 写入一个文件,覆盖原有内容(不支持追加的后端单次写入上限 10MB)。
echo "hello" | wsh file write wavefile://client/greeting.txt
file append
tail -f app.log | wsh file append <uri>
把 stdin 追加到一个文件,不存在就创建(文件总大小上限 10MB)。
echo "deploy finished" | wsh file append wavefile://workspace/deploy.log
file rm
wsh file rm [-r] <uri>
删除一个文件。-r/--recursive 递归删除一个目录及其内容。
wsh file rm wavefile://client/greeting.txt
file cp / file mv
wsh file cp [-m] [-f] <source-uri> <dest-uri>
wsh file mv [-r] [-f] <source-uri> <dest-uri>
在不同存储系统之间复制或移动文件。mv 会在复制成功后删除源文件。
-m,--merge(仅cp)— 合并进一个已存在的目标目录。-r,--recursive(仅mv)— 递归移动目录。-f,--force— 覆盖已存在的目标。
wsh file cp wavefile://client/config.txt ./local-config.txt
wsh file cp ./local-config.txt wsh://myhost/etc/myapp/config.txt
wsh file mv -f ./draft.md wavefile://workspace/notes.md
readfile
wsh readfile <filename>
从当前面板的内部存储读取一个文件并打印到 stdout。这是 file 出现之前的老命令;新脚本推荐用
wsh file cat wavefile://<paneid>/<filename>。
在 macOS 上: 可用,行为完全一致。
wsh readfile var
连接与主机
conn
wsh conn <subcommand>
管理 connections.json 里存的原始 SSH 连接。
wsh conn status— 显示每个连接及其是否已连接。wsh conn list [--json]— 列出配置里的每个连接及其状态。wsh conn connect <connection>— 连接。wsh conn disconnect <connection>— 断开连接。wsh conn disconnectall— 断开所有当前已连接的连接。wsh conn ensure <connection>— 确保这个连接上装好了wsh,没装就装。wsh conn reinstall <connection>— 在这个连接上强制重新安装wsh。wsh conn add <connection> [-i identityfile]...— 添加一个连接(user@host[:port])。wsh conn set <connection> [-i identityfile]... [--host h] [--user u] [--port p]— 编辑一个已有连接的字段;只改你传的那些参数。wsh conn rm <connection>— 从配置里移除一个连接。wsh conn open <connection>— 打开一个已经接到这个连接上的新终端面板(会先尽力去连接)。
在 macOS 上: 可用,行为完全一致,而且这正是面板设置菜单里**重装远端 wsh…**那一项背后的
同一套机制——见 wsh 命令。macOS 读取安装用的二进制,走的是和
Windows/Linux 版一样的 dist/bin 布局(正式安装时打包在 .app 内部),所以往主机上推哪个
wsh 这件事上,macOS 没有任何特殊之处。
wsh conn status
wsh conn add myuser@myhost -i ~/.ssh/id_ed25519
wsh conn open myuser@myhost
wsh conn reinstall myuser@myhost
ssh
wsh ssh [-i identityfile]... [-n] <user@host>
把一个终端连接到远端主机(通过 SSH)。默认切换的是当前终端面板的连接;加上 -n 则改为为
这个连接开一个全新的终端面板。
参数:
-i,--identityfile <path>— 公钥认证用的身份文件(可重复给出)。-n,--new— 打开一个新的终端面板,而不是切换当前这个。
在 macOS 上: 可用,行为完全一致。切换一个已有面板的连接(不带 -n)会写入 connection
元数据键,并原地重连这个面板的会话——和从主机侧栏切换主机走的是同一条路。
wsh ssh myuser@myhost
wsh ssh -n -i ~/.ssh/id_ed25519 myuser@myhost
wsl
wsh wsl [-d <distribution>]
把当前终端面板的连接切换到本机的一个 WSL 发行版。
在 macOS 上:不适用。 WSL 是 Windows 独有的概念;macOS 上根本没有 wsl:// 这种连接类型
可切,这和 wsh 或原生客户端实现了什么无关。
server
wsh server <subcommand>
把已保存的主机(Termia 内部把这类条目叫作 Vault 条目;见主机)和
connections.json 统一起来管理的命令:已保存的主机是那份持久的、带凭据的列表;
connections.json 是 wsh ssh/wsh conn 用的运行时层。
wsh server list [--json]— 列出每一台服务器(已保存的主机和/或连接),它的状态,以及是否 已保存。wsh server rename <server> [--name n] [--desc d]— 重命名或改写一台已保存主机的描述 (只改元数据,不动凭据)。只对已经保存过的主机有效。wsh server rm <server>— 移除一台服务器:把它的已保存主机条目和connections.json条目 一并删掉,存在哪个就删哪个。wsh server save-to-vault <server>— 把一个尚未保存的连接注册成一台已保存的主机。这种方式 绝不会存密码(只支持基于密钥的认证)——要加密码,请打开这台主机的表单。wsh server open <server>— 打开一个连到这台服务器的终端。如果它是带密码的已保存主机,密码 会在连接时提供,绝不会写进connections.json。
在 macOS 上: 可用,行为完全一致——用的是同一份 Go 代码和同一份主机侧栏读写的已保存主机 存储。
wsh server list
wsh server save-to-vault myuser@myhost
wsh server open myuser@myhost
wsh server rename myuser@myhost --name "staging box" --desc "us-east"
命令行里的 TT Agent
task
wsh task <user@host> <task description...>
确保目标连接可用并按需安装 wsh,打开新的远端终端面板,再通过该面板的 feblock:<id> 路由启动 TT Agent,任务描述作为交互会话的初始提示词。
在 macOS 上:可用。 原生端现已注册每面板路由并处理 termiaagentstart。需要有效模型配置,远端需要可用的 wsh;命令成功创建面板不等于 Agent 任务已经完成。它不是远端后台无交互执行器。
网页面板
web open
wsh web open [-m] [-r <ref>] <url>
在一个新的网页面板里打开一个 URL;如果给的不是 URL 而是一段裸的搜索词,就做一次搜索。
参数:
-m,--magnified— 打开时直接放大这个面板。-r,--replace <ref>— 用这个 URL 替换一个已有面板的内容,而不是新建一个(和-m互斥)。
在 macOS 上: 可用,行为完全一致——建出的是一个 web 视图的面板,macOS 渲染它和渲染任何
其他网页面板没有区别。见 Git、监控与网页面板。
wsh web open github.com
wsh web open "termia terminal"
wsh web open -r 3 https://example.com/dashboard
web get(隐藏命令)
wsh web get [--inner] [--all] [--json] css-selector
用 CSS 选择器查询一个网页面板的页面内容并打印匹配结果。因为是给脚本用的,不是日常操作,所以从
--help 里隐藏了。需要 -b 指向一个网页面板(不给就用当前面板,而当前面板必须是网页面板)。
参数:
--inner— 取内部 HTML,而不是外部 HTML。--all— 取全部匹配(querySelectorAll),而不是只取第一个。--json— 以 JSON 格式输出。
在 macOS 上: 可用。这就是 wsh 怎么“喊话”回应用
里说的 webselector 命令——mac 回调路由恰好实现的四条之一——对真实网页面板的页面内容求值,
和 Windows/Linux 上一样。
wsh web get -b 3 "h1"
wsh web get --all --json ".product-price"
工作区
workspace list
wsh workspace list
列出所有窗口里已打开的工作区,包括每一个的名字、图标和颜色。
在 macOS 上: 可用。这里的"工作区"就是一个窗口的身份,和
wsh 命令里 -b workspace 指的是同一个对象。
配置
editconfig
wsh editconfig [configfile]
在一个预览面板里打开一份 Termia 配置文件,并设成编辑模式。默认是 settings.json;其他常用的
文件有 presets.json 和 widgets.json。路径相对于你的配置目录解析(wsh wavepath config)。
在 macOS 上: 可用——它就是一个普通的 preview 视图面板,打开的是 wsh view/wsh edit
用的同一个代码编辑器。
wsh editconfig
wsh editconfig presets.json
setconfig
wsh setconfig key=value ...
直接从命令行设置配置项,值的解析方式和嵌套的 a/b=value 路径写法都和 setmeta 一样。
在 macOS 上: 可用。配置是两个应用共读的同一份文件;macOS 也会实时应用这个改动——走的是
settings.json 不管从哪个来源改动之后,都会刷新每个已打开窗口的那条配置热加载路径。
wsh setconfig term:fontsize=13
标签页背景
setbg
wsh setbg [--opacity value] [--tile|--center] [--size value] (image-path|"#color"|color-name)
设置一个标签页的背景。可以是一张图片的路径(jpg、png、gif、webp、svg)、一个带引号
的十六进制颜色,或者一个 CSS 颜色名。
参数:
--opacity <0.0-1.0>— 背景不透明度(默认0.5)。单独使用时可以只改已有背景的不透明度。--tile— 平铺图片(和--center互斥)。--center— 居中显示图片、不缩放(适合 logo)。--size <px|%|auto>— 居中图片的尺寸(默认auto)。--clear— 清除背景。--print— 只打印将要应用的元数据,不实际应用。
在 macOS 上: 背景本身能生效——图片或颜色,带不透明度都行——但**--tile 和
--center/--size 不起作用**。wsh setbg 把图片引用和铺陈方式写成了单独一条 CSS
background 字符串(--tile 对应 url('...') repeat,--center 对应
url('...') no-repeat center/<size>);macOS 的背景渲染器只从这条字符串里解析出图片
URL,铺陈方式则一律按 --center/--size 都没给时的样子处理——缩放铺满标签页,和默认行为
一样。这不是 wsh 这边能修的:它写的是标准 CSS,只有 Electron 渲染器的 CSS 引擎才会完整
解释它。
wsh setbg ./wallpaper.jpg
wsh setbg --center --size 200px ./logo.png # 设置生效了,但 macOS 依然会缩放铺满渲染
wsh setbg "#1a1a2e"
wsh setbg --opacity 0.2
wsh setbg --clear
通知
notify
wsh notify <message> [-t title] [-s]
通过 Termia 发一条系统通知。
参数:
-t,--title <text>— 通知标题(默认Wsh Notify)。-s,--silent— 静音,不播放通知提示音。
在 macOS 上: 可用——这就是
wsh 怎么“喊话”回应用里的 notify 命令。它会弹一条
系统通知(同一个事件也会出现在应用内的通知面板里);如果 Termia 正是当前活跃的应用,横幅会被
压下——毕竟你已经在看同样的文字了。
long-build.sh && wsh notify "Build finished" || wsh notify -t "Build failed" "check the log"
版本与路径
version
wsh version [-v] [--json]
打印 wsh 的版本号。单纯的 wsh version 只打印版本号,不需要连上 wavesrv;
-v/--json 会额外建立连接,报告客户端 id、配置/数据目录,以及更新通道。
参数:
-v,--verbose— 打印完整的版本信息。--json— 以 JSON 格式打印这些信息。
在 macOS 上: 可用。-v/--json 报告的更新通道永远是 none——这个构建还没有自动更新
通道,所以 none 是一个真实、当下就成立的答案,不是报错也不是占位。
wsh version
wsh version -v
wavepath
wsh wavepath {config|data|log} [-o] [-O] [-t]
打印你的配置目录、数据目录或日志文件的绝对路径。
参数:
-o,--open— 同时在一个新面板里打开这个路径。-O,--open-external— 同时用系统默认的外部应用打开这个路径。-t,--tail— 打印日志最后 100 行,而不是路径(只对log有效)。
在 macOS 上: 可用,行为完全一致,包括 -o(会打开一个 preview 面板指向这个路径)。
wsh wavepath config
wsh wavepath log --tail
wsh wavepath data --open
AI——不可用
ai
wsh ai [-] [message...] [-n] [-f file]...
参数:
-n,--new— 新建一个 AI 面板,而不是用当前/默认的那个。-f,--file <path>— 附加文件内容(可重复;-表示读取 stdin)。
在两个应用上都不可用。 wsh ai 依然编译在二进制里,但它指向的是一种这个应用里已经不存在
的 AI 聊天面板类型,而且它发消息的命令在后端根本没有实现——Electron 前端没有与之匹配的面板
组件,后端的命令分发里也没有对应的分支。不管你跑的是哪个应用,执行它都会报"命令未实现"的
错误;这不是 macOS 独有的缺口。AI 相关的工作请改用 TT Agent(在面板里输入
tt,或者用 wsh task)。
内部命令
这些命令编译在二进制里,但从 wsh --help 里隐藏了,本来就不是给人直接敲的——是 wavesrv 和
远端连接进程内部使用的入口。不管是哪个应用在驱动 wavesrv,它们的行为都完全一样,因为都不涉及
任何和具体应用相关的渲染:
createblock— 按 view 名字创建面板的底层原语;view、term、run、web open以及 打开面板里的其他命令都是围着它做的用户可见封装。connserver— 跑在远端主机上、通过这条连接驱动各个面板的进程。debug— 内部调试命令(debug block、debug gettab、debug send-telemetry)。remoteexec/remoteexec-json— 内部用来在一个已建立的 SSH 连接上执行单条命令。rcfiles— (重新)生成 wsh 命令里说到的那些 shell 集成文件。shell— 打印当前用户的登录 shell。test— 开发用的空操作命令。token— 用一个短期有效的置换令牌换取一段初始化脚本;新的 shell 会话建立wsh连接时 用得上。