WezTerm CLI 全面指南：用 `wezterm cli` 远程操控运行中的终端实例

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/wezterm

wezterm cli是 WezTerm（GPU 加速、跨平台、以 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 给出的判定逻辑按以下优先级执行：

1. --prefer-mux标志：若传入该标志，则查阅wezterm.lua配置文件，取配置定义的第一条unix domain（Unix 域套接字）作为连接目标，即优先连接后台多路复用器服务器。
2. $WEZTERM_UNIX_SOCKET环境变量：若该变量已设置，则直接使用其指向的位置来识别运行中的实例。
3. 查找运行中的 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时，按以下规则确定窗格：

1. $WEZTERM_PANE环境变量：若已设置，则直接使用其值作为窗格 ID。WezTerm 的 shell 集成（见 assets/shell-integration/wezterm.sh）会在每个窗格内导出该变量，因此在任何窗格中执行命令时，"当前窗格"自动可用。
2. 最近交互会话的焦点窗格：若无该变量，则获取客户端列表，按最近交互的会话排序，取该会话中拥有焦点的窗格 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"，与文档描述一致。

环境变量小结

查看运行状态：list与list-clients

wezterm 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 -- wez@foo:~ file://foo/home/wez/

每一行描述一个窗格，字段含义：

• WINID：窗格所在窗口的 ID
• TABID：窗格所在标签页的 ID
• PANEID：窗格 ID
• WORKSPACE：窗格关联的工作区名称
• 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 -- wez@foo:~", "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：客户端会话的进程 ID
• CONNECTED：连接已建立的时间
• 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-pane

wezterm 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：在指定窗口生成标签页，而非当前窗口

其--help（docs/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-text

wezterm 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：指定接收文本的窗格

其--help（docs/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表示主屏幕顶部，负数则向滚动缓冲回溯。

其--help（docs/examples/cmd-synopsis-wezterm-cli-get-text--help.txt）补充：--start-line默认值为 0（终端屏幕首行），--end-line默认值为屏幕底部；--pane-id指定目标窗格。

焦点与导航：activate-*与get-pane-direction

wezterm 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：按窗格树中的序数位置循环切换

其--help（docs/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.md）：

• Left、Right、Up、Down：按方向确定
• Next、Prev：按窗格树的序数位置确定

--help（docs/examples/cmd-synopsis-wezterm-cli-get-pane-direction--help.txt）注明：若该方向没有窗格，则不输出任何内容。这个命令是"只查询、不切换"的版本，适合脚本先探测布局再决定操作。

wezterm cli activate-tab

激活（切换到）一个标签页（自20230326-111934-3666303c起，见 docs/cli/cli/activate-tab.md）。其--help（docs/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-tab

wezterm cli adjust-pane-size DIRECTION

沿指定方向调整当前窗格（或--pane-id指定窗格）的尺寸（自20230712-072601-f4abf8fd起，见 docs/cli/cli/adjust-pane-size.md）。DIRECTION取值Left、Right、Up、Down，大小写不敏感。--help（docs/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）。--help（docs/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：指定要移动的窗格

--help（docs/examples/cmd-synopsis-wezterm-cli-move-pane-to-new-tab--help.txt）确认：--new-window表示在新建窗口创建标签页而非当前窗格所在窗口。

生命周期与元数据：kill-pane、set-tab-title、set-window-title、rename-workspace

wezterm 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）。--help（docs/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）。--help（docs/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）。--help（docs/examples/cmd-synopsis-wezterm-cli-rename-workspace--help.txt）显示：<NEW_WORKSPACE>为工作区新名称；--workspace显式指定要重命名的工作区；--pane-id用于推导要重命名的工作区。

子命令速查表

表中"较早"表示对应子命令文件未标注{{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(.workspace=="work") | .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