wsh 命令参考
这里是 wsh 的完整参考手册,内容对照这个构建版本里 wsh 实际提供的命令编写。如果想先了解大多数
命令共用的 -b 区块引用语法,请先读 wsh 命令。
命令按作用对象分组。每一个都给出语法、参数,以及一个可以直接运行的示例。
全局参数
任何作用于区块、标签页或工作区的命令都支持:
-b, --block <ref> 指定作用的区块 id(默认 "this")
<ref> 支持的全部简写形式(this、tab、workspace、client、区块编号、视图名、截断或完整
id)见概览页的如何指定一个区块一节。
view / edit

wsh view [-m] {file|directory|url}
wsh edit [-m] {file}
在预览区块里打开一个文件或目录,或者在 web 区块里打开一个网址。view(别名 preview、
open)用于查看;文本和代码文件会在内置的代码编辑器里打开,图片和 markdown 直接渲染,目录则作为
文件浏览器打开。edit 打开的是同一个预览区块,但会额外把它设为编辑模式。
参数:
-m,--magnified—— 以放大模式打开该区块。
wsh view .
wsh view ./screenshot.png
wsh edit ./config.json
wsh view https://example.com
editor
wsh editor [-m] <file>
打开一个文件进行编辑,并且会阻塞直到该区块被关闭——这一点与立即返回的 view/edit 不同。
这让它可以直接当 $EDITOR 用:在 shell profile 里设置 EDITOR="wsh editor",像 git commit 这
样的命令就会在 Termia 的图形编辑器里打开文件,并等你关闭它之后再继续。
参数:
-m,--magnified—— 以放大模式打开该区块。
export EDITOR="wsh editor"
git commit
term
wsh term [-m] [directory]
打开一个新的终端区块。不带参数时在你当前工作目录打开;否则在给定目录打开(~ 会被展开)。如果
你是在一个已连接远程主机的区块里运行这条命令,新终端会打开在同一条连接上。
参数:
-m,--magnified—— 以放大模式打开该区块。
wsh term ~/projects/termia-terminal
run
wsh run [flags] -- command [args...]
wsh run [flags] -c "shell command string"
在一个新终端区块里运行一条命令。要么在 -- 后面给一条命令(直接执行,不经过 shell),要么用
-c 给一段 shell 命令字符串(经过 shell 执行)——两者不能同时用。新区块会继承你当前的环境变量
和工作目录。
参数:
-m,--magnified—— 以放大模式打开该区块。-c, --command <string>—— 在 shell 里运行这段字符串,而不是使用--后的命令。-x, --exit—— 命令成功退出后自动关闭该区块(出错则保持打开)。-X, --forceexit—— 无论命令退出状态如何,退出后都关闭该区块。--delay <ms>—— 配合-x/-X,关闭前等待的毫秒数(默认2000)。-p, --paused—— 创建区块但不启动命令,由你手动启动。--cwd <path>—— 命令的工作目录(默认:你当前的目录)。-a, --append—— 重启时追加输出,而不是先清空区块。
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 或内置的默认 widget 配置里创建一个区块。
参数:
-m,--magnify—— 以放大模式打开该区块。
wsh launch sysinfo
deleteblock
wsh deleteblock -b <ref>
删除一个区块。不接受位置参数——用 -b 指定目标(默认是当前区块,所以直接裸执行会关掉你正在
输入命令的这个终端)。
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:*模式,额外包含用于清除的特殊 key。
wsh getmeta
wsh getmeta -b 2 file
wsh getmeta -b tab "bg:*"
setmeta
wsh setmeta [-b <ref>] [--json file.json] key=value ...
设置一个区块或标签页的一个或多个元数据 key。值会尽量按 JSON 解析
(true/false/null、数字、[...]/{...}/"..."),解析不了就当作普通字符串。key 里包含
/ 表示嵌套路径(a/b=1 会写成 {"a": {"b": 1}})。把某个 key 设为 null 会删除它。
参数:
--json <file>—— 从一个 JSON 文件加载基础元数据(-表示从 stdin 读取);命令行上给出的值 会覆盖文件里的同名 key。
wsh setmeta -b 3 file=~/notes.txt
wsh setmeta -b tab bg=blue bg:opacity=0.3
wsh setmeta -b tab --json -
setbg
wsh setbg [--opacity 0.5] [--tile|--center] [--size auto] [--clear] [--print] [image-path|"#rrggbb"|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—— 只打印将要应用的元数据,不实际应用。
wsh setbg ./wallpaper.jpg
wsh setbg --center --size 200px ./logo.png
wsh setbg "#1a1a2e"
wsh setbg --opacity 0.2
wsh setbg --clear
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 读取的是客户端范围(全局)的变量,而不是当前区块的。
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...
存一个或多个变量。和 getvar 一样,默认是客户端范围,除非给了 -l/--local 或 -b。
参数:
--varfile <name>—— 变量文件名(默认var)。-l,--local—— 存到当前区块,而不是客户端范围。-r,--remove—— 删除给定的 key,而不是设置它们。
wsh setvar DEPLOY_ENV=staging
wsh setvar -l BUILD_NUM=42
wsh setvar -r DEPLOY_ENV
file
wsh file <subcommand> [flags] <uri>...
跨三种存储系统管理文件,通过 URI 寻址:
wsh://[connection]/[path]—— 某个本机或远程连接上的路径,经由wsh访问。裸路径或//host/path是当前连接或指定连接的简写。wavefile://[zoneid]/[path]—— Termia 内部的区块/标签页/客户端文件存储(setvar/getvar就建立在它之上)。zoneid是一个区块/标签页 id,或者client/global之一。s3://[bucket]/[path](也可以写成[profile]:s3://...或aws:[profile]:s3://...)——一个 兼容 S3 的存储桶,凭据取自你的 AWS CLI 配置或profiles.json。
所有 file 子命令都支持:
-t,--timeout <ms>—— 操作超时时间(默认15000)。
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>
在不同存储系统之间(本机磁盘、wsh://、wavefile://、s3://)复制或移动文件。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://<blockid>/<filename>(或配合 -b 加一个普通文件名),因为 file 还能
跨连接和 S3 使用。
wsh readfile var
conn
wsh conn <subcommand>
管理原始的 SSH 和 WSL 连接,数据存在 connections.json 里。
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版本过旧,可以用这个)。wsh conn add <connection> [-i identityfile]...—— 添加一个连接。<connection>形如user@host[:port]或wsl://<distro>。wsh conn set <connection> [-i identityfile]... [--host h] [--user u] [--port p]—— 修改一个 已有连接的字段;只有你传入的参数会被改动。wsh conn rm <connection>—— 从配置中删除一个连接。wsh conn open <connection>—— 打开一个新终端区块,直接连接到该连接(会先尝试连接)。
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>
把一个终端连接到远程主机。默认会切换当前终端区块的连接;加 -n 则会为该连接打开一个全新的
终端区块。
参数:
-i,--identityfile <path>—— 用于公钥认证的身份文件(可重复)。-n,--new—— 打开一个新终端区块,而不是切换当前的。
wsh ssh myuser@myhost
wsh ssh -n -i ~/.ssh/id_ed25519 myuser@myhost
wsl
wsh wsl [-d <distribution>]
把当前终端区块的连接切换为一个本机 WSL 发行版。不带 -d/--distribution 时使用你的默认发行
版。
wsh wsl -d Ubuntu
server
wsh server <subcommand>
统一管理 Vault 主机(见 主机与 Vaults)和 connections.json:Vault 主机是那份持
久的、带凭据的列表;connections.json 是 wsh ssh/wsh conn 使用的运行时层。这里说的"服务器"
两者皆可,按 user@ip[:port] 合并为一份列表。
wsh server list [--json]—— 列出每一个服务器(Vault 主机和/或连接)、其状态,以及是否已保存 在 Vault 里。wsh server rename <server> [--name n] [--desc d]—— 重命名或修改一个 Vault 主机的描述。只对 已经在 Vault 里的服务器有效;不涉及凭据。wsh server rm <server>—— 删除一个服务器:同时删掉它的 Vault 主机条目和connections.json条目(存在哪个删哪个)。wsh server save-to-vault <server>—— 把一个已存在但未保存的连接注册为 Vault 主机。这种方式 不会存密码(只支持基于密钥的认证)——要加密码,请到 Vaults 界面里打开该主机的表单。wsh server open <server>—— 打开一个连接到该服务器的终端。如果它是带保存密码的 Vault 主机, 密码会在连接时提供,而不会写入connections.json。
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"
task
wsh task <user@host> <task description...>
打开一个连接到 <user@host> 的新终端区块(会先确保该主机上装有 wsh),并立即在其中启动
Termia Agent,把其余参数拼成初始 prompt。这相当于用脚本一步完成"打开终端 + 输入 tt + 交代任
务"。
wsh task myuser@myhost "看看 /var/log/app.log 最后 200 行,总结一下有哪些报错"
web
wsh web open [-m] [-r <ref>] <url>
在一个新的 web 区块里打开一个网址;如果给的不是网址而是一段搜索词,则会做搜索。
参数:
-m,--magnified—— 以放大模式打开该区块。-r,--replace <ref>—— 用这个网址替换某个已有区块的内容,而不是新建一个区块(与-m互斥)。
wsh web open github.com
wsh web open "termia terminal"
wsh web open -r 3 https://example.com/dashboard
workspace
wsh workspace list
列出所有窗口里打开的工作区,包含每个工作区的名称、图标和颜色。
editconfig
wsh editconfig [configfile]
在图形编辑器里打开一个 Termia 配置文件。默认是 settings.json;其他常见文件有 presets.json 和
widgets.json。路径是相对你的配置目录解析的(见 wsh wavepath config)。
wsh editconfig
wsh editconfig presets.json
setconfig
wsh setconfig key=value ...
直接从命令行设置配置项,值的解析方式和嵌套路径语法(a/b=value)都和 setmeta 一样。
wsh setconfig term:fontsize=13
version
wsh version [-v] [--json]
打印 wsh 的版本号。裸执行 wsh version 只打印版本号,不需要连接 wavesrv;-v/--json 会额外
连接并报告你的客户端 id、配置/数据目录以及所在的更新渠道。
参数:
-v,--verbose—— 打印完整的版本信息。--json—— 以 JSON 格式打印这些信息。
wsh version
wsh version -v
wavepath
wsh wavepath {config|data|log} [-o] [-O] [-t]
打印配置目录、数据目录或日志文件的绝对路径。
参数:
-o,--open—— 同时在一个新区块里打开该路径。-O,--open-external—— 同时用你操作系统的默认外部应用打开该路径。-t,--tail—— 打印最后 100 行,而不是路径(仅对log有效)。
wsh wavepath config
wsh wavepath log --tail
wsh wavepath data --open
notify
wsh notify <message> [-t title] [-s]
通过 Termia 发送一条桌面通知。
参数:
-t,--title <text>—— 通知标题(默认Wsh Notify)。-s,--silent—— 静音,不播放通知提示音。
long-build.sh && wsh notify "构建完成" || wsh notify -t "构建失败" "看看日志"
ai —— 在这个构建版本里不可用
wsh ai 这个命令依然存在于二进制文件里(ai [-] [message...],带 -n/--new 和 -f/--file
参数用于附加文件或 stdin),但它指向的是一种在 Termia 里并不存在的聊天区块类型,而且这个构建版
本里没有对应的服务端处理逻辑——运行它会得到一条"command not implemented"错误。AI 相关的工作请改用
Termia Agent(在终端里输入 tt,或者用 wsh task)。
内部命令
以下命令存在于二进制文件里,但在 wsh --help 中是隐藏的,不是给用户直接输入用的——它们是
wavesrv 和远程连接进程内部使用的入口:
connserver—— 运行在远程主机上、为该连接的各个区块提供支持的进程。createblock—— 按视图名创建区块的底层命令;上面的view、term、run、web open等命 令都是围绕它做的用户友好封装。debug—— 内部排查用的命令(debug block、debug gettab、debug send-telemetry)。remoteexec/remoteexec-json—— 应用内部用来在一条已建立的 SSH 连接上执行单条命令。rcfiles—— (重新)生成 wsh 命令 里介绍的那些 shell 集成文件。shell—— 打印当前用户的登录 shell。test—— 开发用的空操作命令。token—— 用一个短期的 swap token 换取一段初始化脚本;新 shell 会话用它来建立wsh连接。