WezTerm CLI 全面指南用wezterm cli远程操控运行中的终端实例【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm cli是 WezTermGPU 加速、跨平台、以 Rust 实现的终端模拟器与多路复用器提供的命令行子命令集合它用于与正在运行的 WezTerm GUI 或多路复用器mux实例交互可以在不进入 GUI 的情况下以脚本方式创建程序、操作标签页与窗格。本文以仓库中的 docs/cli/cli/index.markdown 为核心骨架逐一详解实例定位、窗格定位机制以及全部 17 个子命令的用法、参数与输出格式并结合 wezterm/src/cli/mod.rs 的源码说明其底层实现读完即可将 WezTerm 的窗格/标签页/工作区操作完全脚本化。wezterm cli是什么cli子命令的职责非常聚焦与一个正在运行的 WezTerm GUI 实例或多路复用器实例建立连接并驱动它执行生成程序、操作标签页tab与窗格pane等操作。它本身不是一个独立的终端而是一个远程控制通道。从源码看WezTerm 将 CLI 实现拆分为大量独立模块并在 wezterm/src/cli/mod.rs 中统一注册为CliSubCommand枚举包括list、list-clients、proxy、tlscreds、move-pane-to-new-tab、split-pane、spawn、send-text、get-text、activate-pane-direction、get-pane-direction、kill-pane、activate-pane、activate-tab、adjust-pane-size、rename-workspace、set-tab-title、set-window-title、zoom-pane等。其中proxy与tlscreds属于内部 RPC 工具面向普通用户的主要是后文列出的 17 个功能性子命令。与 WezTerm 的 Lua 配置 API如 docs/config/lua相比CLI 的优势在于任何语言编写的脚本、任何进程都能直接通过命令行完成同样的窗格管理操作无需编写 Lua。定位正确的目标实例Targeting the correct instance一个 WezTerm 环境里可能同时存在多个 GUI 进程、外加一个多路复用器服务器。wezterm cli必须首先决定连接到哪一个实例。文档 index.markdown 给出的判定逻辑按以下优先级执行--prefer-mux标志若传入该标志则查阅wezterm.lua配置文件取配置定义的第一条unix domainUnix 域套接字作为连接目标即优先连接后台多路复用器服务器。$WEZTERM_UNIX_SOCKET环境变量若该变量已设置则直接使用其指向的位置来识别运行中的实例。查找运行中的 GUI 实例此时可通过--class参数指定窗口类window class用于选中一个以相同--class启动的 GUI 窗口若 GUI 启动时未用--class覆盖默认值则该参数为可选。这一逻辑在源码中有对应佐证wezterm/src/cli/mod.rs 中CliCommand结构体定义了--no-auto-start不自动启动服务器、--prefer-mux优先连接后台 mux 服务器与--class指定 GUI 窗口类以匹配正确的 GUI 实例三个顶层选项文档所述即这三个参数的行为。补充--no-auto-start源码中还提供了--no-auto-start选项默认情况下如果找不到可连接的实例wezterm cli会自动启动 mux 服务器加上该标志后则不自动启动用于严格限定仅连接已存在的实例的场景。定位目标窗格Targeting Panes大多数子命令通过一个通常可省略的--pane-id参数来指定操作目标窗格。当未显式给出--pane-id时按以下规则确定窗格$WEZTERM_PANE环境变量若已设置则直接使用其值作为窗格 ID。WezTerm 的 shell 集成见 assets/shell-integration/wezterm.sh会在每个窗格内导出该变量因此在任何窗格中执行命令时当前窗格自动可用。最近交互会话的焦点窗格若无该变量则获取客户端列表按最近交互的会话排序取该会话中拥有焦点的窗格 ID。源码中--pane-id的帮助文本在几乎所有子命令模块中重复出现例如 wezterm/src/cli/send_text.rs、wezterm/src/cli/split_pane.rs 均注释为The default is to use the current pane based on the environment variable WEZTERM_PANE与文档描述一致。环境变量小结环境变量作用$WEZTERM_UNIX_SOCKET指定运行中实例的 Unix 域套接字位置用于选择连接目标实例$WEZTERM_PANE指定当前窗格的 ID供--pane-id缺省时使用查看运行状态list与list-clientswezterm cli list— 列出窗口、标签页与窗格该命令列出正在被管理的全部窗口、标签页和窗格。默认输出为表格形式见 docs/cli/cli/list.md$ wezterm cli list WINID TABID PANEID WORKSPACE SIZE TITLE CWD 0 0 0 default 80x24 wezterm cli list -- wezfoo:~ file://foo/home/wez/每一行描述一个窗格字段含义WINID窗格所在窗口的 IDTABID窗格所在标签页的 IDPANEID窗格 IDWORKSPACE窗格关联的工作区名称SIZE窗格尺寸以终端单元列 × 行计TITLE窗格标题CWD窗格关联的当前工作目录自 2022-06-24版本20220624-141144-bd1b7c5d起支持 JSON 输出$ wezterm cli list --format json [ { window_id: 0, tab_id: 0, pane_id: 0, workspace: default, size: { rows: 24, cols: 80 }, title: wezterm cli list --format json -- wezfoo:~, cwd: file://foo/home/wez/ } ]其--help输出见 docs/examples/cmd-synopsis-wezterm-cli-list--help.txt确认--format支持table默认与json两种格式。在源码中输出格式由 wezterm/src/cli/mod.rs 中的CliOutputFormat结构体统一解析--format参数默认值为table非法值会报unknown output format。实用场景脚本可以通过wezterm cli list --format json获取某个窗格的 ID再配合send-text、split-pane等命令做定向控制。wezterm cli list-clients— 列出已连接的客户端多路复用场景下多个客户端会话可能连接到同一个 mux 服务器。该命令列出所有已连接的客户端及其附加信息见 docs/cli/cli/list-clients.md$ wezterm cli list-clients USER HOST PID CONNECTED IDLE WORKSPACE FOCUS wez foo 1098536 166.03140978s 31.40978ms default 0字段含义USER会话关联的用户名HOST会话关联的主机名PID客户端会话的进程 IDCONNECTED连接已建立的时间IDLE距离该客户端最后一次输入的时间WORKSPACE该会话当前活跃的工作区FOCUS该会话中拥有焦点的窗格 ID同样支持 JSON 输出自20220624-141144-bd1b7c5d起$ wezterm cli list-clients --format json [ { username: wez, hostname: foo, pid: 1098536, connection_elapsed: { secs: 226, nanos: 502667166 }, idle_time: { secs: 0, nanos: 502667166 }, workspace: default, focused_pane_id: 0 } ]这一命令正是窗格定位规则中最近交互会话的数据来源。生成与拆分spawn与split-panewezterm cli spawn— 在新标签页或新窗口生成命令在运行中的实例里新建标签页或窗口并启动程序成功时在标准输出打印新窗格的 pane-id见 docs/cli/cli/spawn.md$ wezterm cli spawn 1无参数时它在新标签页中运行默认程序通常是你的 shell示例中新建的窗格 ID 为 1。生成其他程序时建议用--分隔wezterm cli spawn自身的参数与传给程序的参数避免歧义$ wezterm cli spawn -- top 2显式以登录 shell 方式运行 bash$ wezterm cli spawn -- bash -l 3支持的行为选项--cwd CWD为生成程序设置当前工作目录--domain-name DOMAIN_NAME在指定的多路复用域中生成默认为当前窗格所在域--new-window在新窗口中打开标签页--workspace WORKSPACE与--new-window配合为窗口设置工作区名称默认名称为default--window-id WINDOW_ID在指定窗口生成标签页而非当前窗口其--helpdocs/examples/cmd-synopsis-wezterm-cli-spawn--help.txt补充了细节[PROG]...接受任意程序及参数--pane-id用于指定当前窗格以推导目标域与目标窗口--window-id不可与--workspace、--new-window同时使用--workspace要求配合--new-window。wezterm cli split-pane— 拆分当前窗格拆分当前窗格并生成新命令到新窗格中成功时输出新窗格 ID见 docs/cli/cli/split-pane.md$ wezterm cli split-pane 2在下方新建一个窗格并以登录 shell 运行 bash$ wezterm cli split-pane -- bash -l 3在左侧拆分、新窗格占 30% 空间$ wezterm cli split-pane --left --percent 30 4参数说明--cwd CWD为初始生成程序指定当前工作目录--horizontal等价于--right若未指定任何方向默认等价于--bottom--pane-id指定要拆分的窗格定位规则见 docs/cli/cli/index.markdown 的 Targeting Panes 一节自20220624-141144-bd1b7c5d起完整支持以下方向与尺寸选项--bottom垂直拆分新窗格在下方--cells CELLS新拆分占用的单元数省略时默认使用可用空间的 50%--left水平拆分新窗格在左侧--move-pane-id MOVE_PANE_ID不生成新命令而是把指定窗格移入新创建的拆分--percent PERCENT以可用空间的百分比指定新窗格大小--right水平拆分新窗格在右侧--top垂直拆分新窗格在上方--top-level不拆分当前活跃窗格而是拆分整个窗口--help全文见 docs/examples/cmd-synopsis-wezterm-cli-split-pane--help.txt。注意--move-pane-id提供了一种把某个窗格搬进新拆分的能力配合多窗格管理可以快速重排布局。输入与取数send-text与get-textwezterm cli send-text— 向窗格发送文本向窗格发送文本效果等同于粘贴若窗格启用了 bracketed paste括号粘贴模式文本将以括号粘贴形式发送见 docs/cli/cli/send-text.md$ wezterm cli send-text hello there这会把hello there发送到当前窗格的输入中。也支持从 stdin 管道传入$ echo hello there | wezterm cli send-text参数--no-paste直接发送文本不采用括号粘贴自20220624-141144-bd1b7c5d起--pane-id指定接收文本的窗格其--helpdocs/examples/cmd-synopsis-wezterm-cli-send-text--help.txt说明TEXT参数省略时会从 stdin 读取。实用场景这是脚本自动化中最常用的命令之一——例如向特定窗格输入命令、触发交互式程序的内部动作。wezterm cli get-text— 抓取窗格文本内容获取窗格的文本内容并输出到 stdout见 docs/cli/cli/get-text.md$ wezterm cli get-text /tmp/myscreen.txt这会把当前窗格的主屏幕不含滚动缓冲部分抓取到/tmp/myscreen.txt。默认只输出纯文本、不带颜色或样式转义序列如需保留样式加--escapes$ wezterm cli get-text --escapes /tmp/myscreen-with-colors.txt默认抓取区域是终端主屏幕不含滚动缓冲。可通过--start-line与--end-line限定范围两者均接受整数值0表示主屏幕顶部负数则向滚动缓冲回溯。其--helpdocs/examples/cmd-synopsis-wezterm-cli-get-text--help.txt补充--start-line默认值为 0终端屏幕首行--end-line默认值为屏幕底部--pane-id指定目标窗格。焦点与导航activate-*与get-pane-directionwezterm cli activate-pane激活当前窗格或通过--pane-id指定的窗格自20230326-111934-3666303c起见 docs/cli/cli/activate-pane.md。wezterm cli activate-pane-direction DIRECTION将激活焦点切换到指定方向的窗格自20221119-145034-49b9839f起见 docs/cli/cli/activate-pane-direction.md。方向参数不区分大小写left与Left等价Left、Right、Up、Down按方向激活Next、Prev按窗格树中的序数位置循环切换其--helpdocs/examples/cmd-synopsis-wezterm-cli-activate-pane-direction--help.txt列出DIRECTION的可选值为Up, Down, Left, Right, Next, Prev。wezterm cli get-pane-direction DIRECTION打印相对当前窗格、位于指定方向的窗格 ID自20230408-112425-69ae8472起见 docs/cli/cli/get-pane-direction.mdLeft、Right、Up、Down按方向确定Next、Prev按窗格树的序数位置确定--helpdocs/examples/cmd-synopsis-wezterm-cli-get-pane-direction--help.txt注明若该方向没有窗格则不输出任何内容。这个命令是只查询、不切换的版本适合脚本先探测布局再决定操作。wezterm cli activate-tab激活切换到一个标签页自20230326-111934-3666303c起见 docs/cli/cli/activate-tab.md。其--helpdocs/examples/cmd-synopsis-wezterm-cli-activate-tab--help.txt给出了三种定位方式--tab-id TAB_ID按标签页 ID 指定--tab-index TAB_INDEX按当前窗格所在窗口内的索引指定索引从 0 开始0 为最左侧标签页负数可从右侧计数-1为最右侧标签页--tab-relative TAB_RELATIVE按相对偏移指定-1选中左侧相邻标签页1选中右侧相邻标签页默认在左右边界循环环绕加--no-wrap则禁止环绕并在边界处钳制--pane-id用于推导包含目标标签页的窗口布局调整adjust-pane-size、zoom-pane、move-pane-to-new-tabwezterm cli adjust-pane-size DIRECTION沿指定方向调整当前窗格或--pane-id指定窗格的尺寸自20230712-072601-f4abf8fd起见 docs/cli/cli/adjust-pane-size.md。DIRECTION取值Left、Right、Up、Down大小写不敏感。--helpdocs/examples/cmd-synopsis-wezterm-cli-adjust-pane-size--help.txt补充--amount AMOUNT指定调整的单元数默认值为 1。wezterm cli zoom-pane对窗格执行放大zoom、取消放大unzoom或切换状态自20240127-113634-bbcac864起见 docs/cli/cli/zoom-pane.md。--helpdocs/examples/cmd-synopsis-wezterm-cli-zoom-pane--help.txt列出三个互斥动作--zoom未放大则放大、--unzoom已放大则取消、--toggle切换放大状态默认行为即--toggle。wezterm cli move-pane-to-new-tab将某个窗格移入新标签页可留在原窗口或放入新窗口自20220624-141144-bd1b7c5d起见 docs/cli/cli/move-pane-to-new-tab.md。默认把当前窗格移到同窗口的新标签页--new-window在新窗口中创建标签页--window-id WINDOW_ID在指定窗口 ID 中创建新标签页而非当前窗口--workspace WORKSPACE配合--new-window使用为新窗口命名工作区默认名default--pane-id指定要移动的窗格--helpdocs/examples/cmd-synopsis-wezterm-cli-move-pane-to-new-tab--help.txt确认--new-window表示在新建窗口创建标签页而非当前窗格所在窗口。生命周期与元数据kill-pane、set-tab-title、set-window-title、rename-workspacewezterm cli kill-pane立即且不做任何确认地终止当前窗格或--pane-id指定的窗格自20230326-111934-3666303c起见 docs/cli/cli/kill-pane.md。文档特别强调立即且不提示使用前请确认目标窗格以免误杀正在运行的程序。wezterm cli set-tab-title TITLE修改标签页标题自20230408-112425-69ae8472起见 docs/cli/cli/set-tab-title.md。--helpdocs/examples/cmd-synopsis-wezterm-cli-set-tab-title--help.txt显示TITLE为新标题--tab-id直接指定目标标签页--pane-id用于推导目标标签页取该窗格所在标签页。wezterm cli set-window-title TITLE修改窗口标题自20230408-112425-69ae8472起见 docs/cli/cli/set-window-title.md。--helpdocs/examples/cmd-synopsis-wezterm-cli-set-window-title--help.txt显示TITLE为新标题--window-id直接指定目标窗口--pane-id用于推导目标窗口。wezterm cli rename-workspace NEW-WORKSPACE重命名工作区自20230408-112425-69ae8472起见 docs/cli/cli/rename-workspace.md。--helpdocs/examples/cmd-synopsis-wezterm-cli-rename-workspace--help.txt显示NEW_WORKSPACE为工作区新名称--workspace显式指定要重命名的工作区--pane-id用于推导要重命名的工作区。子命令速查表子命令作用引入版本list列出窗口、标签页与窗格支持 table/json较早list-clients列出已连接的客户端会话20220624-141144-bd1b7c5dspawn在新标签页/窗口生成程序输出新窗格 ID较早split-pane拆分窗格并生成程序输出新窗格 ID20220624-141144-bd1b7c5d方向/尺寸选项send-text向窗格发送文本粘贴式或直接较早--no-paste于20220624-141144-bd1b7c5dget-text抓取窗格文本含滚动缓冲区间到 stdout20230320-124340-559cb7b0activate-pane激活指定窗格20230326-111934-3666303cactivate-pane-direction按方向/序数激活相邻窗格20221119-145034-49b9839fget-pane-direction打印指定方向的窗格 ID20230408-112425-69ae8472activate-tab按 ID/索引/相对偏移激活标签页20230326-111934-3666303cadjust-pane-size按方向调整窗格尺寸20230712-072601-f4abf8fdzoom-pane放大/取消放大/切换窗格放大状态20240127-113634-bbcac864kill-pane立即终止窗格不提示20230326-111934-3666303cmove-pane-to-new-tab移动窗格到新标签页/新窗口20220624-141144-bd1b7c5drename-workspace重命名工作区20230408-112425-69ae8472set-tab-title设置标签页标题20230408-112425-69ae8472set-window-title设置窗口标题20230408-112425-69ae8472表中较早表示对应子命令文件未标注{{since(...)}}即属于较早期版本即有的能力各版本的完整标记可在对应文档文件中核对。任意命令均可通过wezterm cli 子命令 --help获取当前安装版本的确切选项。组合实战把窗格管理脚本化将上述命令串联可以完成典型的自动化工作流场景一在一个窗格中运行命令并抓取结果# 用 -- 分隔参数向当前窗格发送命令后回车 wezterm cli send-text ls -la echo DONE wezterm cli send-text $\r # 稍等执行完成后抓取当前窗格屏幕内容 wezterm cli get-text /tmp/screen.txt场景二按方向探测并聚焦窗格# 先查询右侧是否有窗格 PID$(wezterm cli get-pane-direction Right) if [ -n $PID ]; then wezterm cli activate-pane --pane-id $PID fi场景三把当前窗格提升为独立窗口中的标签页wezterm cli move-pane-to-new-tab --new-window --workspace work场景四配合list做全局调度# 找出 workspace 为 work 的第一个窗格并发送命令 PANE$(wezterm cli list --format json | jq -r .[] | select(.workspacework) | .pane_id | head -1) wezterm cli send-text --pane-id $PANE cd /data/web/disk1 pwd底层实现与更多资源从实现角度看所有子命令都通过 wezterm/src/cli/mod.rs 中定义的Client来自wezterm-clientcrate建立与目标的连接客户端发现与实例定位还涉及 wezterm-client/src/discovery.rs。命令行解析使用clap框架split-pane、spawn两个命令启用了trailing_var_arg这正是它们要求用--分隔程序参数的原因——--之后的内容不会被当作子命令自身的选项解析。此外spawn与split-pane的PROG参数帮助文本都明确写了wezterm cli spawn -- bash -l这类登录 shell 示例与文档一致。如需进一步阅读仓库内的相关资料各子命令的独立文档docs/cli/cli/ 目录下的 17 个.md文件各命令的完整--help输出docs/examples/ 下的cmd-synopsis-wezterm-cli-*.txt文件CLI 实现源码wezterm/src/cli/入口为 mod.rs通用 CLI 说明--help、--version等全局行为docs/cli/general.md结语wezterm cli把 WezTerm 的窗口、标签页、窗格与工作区管理完整暴露给了命令行通过--prefer-mux、$WEZTERM_UNIX_SOCKET、--class精确选择目标实例通过--pane-id与$WEZTERM_PANE精确定位窗格再借助spawn、split-pane、send-text、get-text、activate-*、zoom-pane、move-pane-to-new-tab等命令完成从生成程序到布局调整、从文本注入到内容抓取的完整闭环。掌握这套命令后即可将 WezTerm 深度融入自己的脚本与自动化流水线。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考