跳到主要内容

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 连接时 用得上。