跳到主要内容

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 连接。