wezterm cli list-clients 命令详解：查询多路复用会话的已连接客户端

导读

wezterm cli list-clients 是 wezterm 多路复用（multiplexing）体系中用于列出所有已连接客户端及其会话状态的诊断命令。当你在一个机器上运行 wezterm mux server、从多个终端窗口甚至多台主机远程接入时，它帮你一眼看清每个客户端的用户、主机、进程 ID、连接时长、空闲时长、所属 workspace 与焦点 pane。阅读本文后，你将掌握该命令的表格/JSON 两种输出格式、每个字段的精确语义，以及从 CLI 到 mux server 的底层实现链路。

命令概述

wezterm cli list-clients 用于列出当前连接的客户端集合及与之相关的附加信息。它直接依赖 wezterm 的 mux（多路复用器）体系：当有多个客户端进程连接到同一个 mux server 时，该命令返回服务端记录的每个客户端会话信息。

执行方式很简单：

$ wezterm cli list-clients
USER HOST     PID CONNECTED     IDLE       WORKSPACE FOCUS
wez  foo  1098536 166.03140978s 31.40978ms default       0

该命令自 20220624-141144-bd1b7c5d 版本起可用（见 docs/cli/cli/list-clients.md 中的版本标注）。若你的 wezterm 版本低于此，请先升级。

输出字段语义

表格输出的每一列含义如下（依据官方文档）：

列名	含义
USER	与该会话关联的用户名（username）
HOST	与该会话关联的主机名（hostname）
PID	客户端会话的进程 ID
CONNECTED	该连接已建立的时间长度
IDLE	距该客户端最后一次收到输入所经过的时间
WORKSPACE	该会话当前活动的 workspace 名称
FOCUS	该会话中获得焦点的 pane id

注意，示例输出中 CONNECTED 与 IDLE 的显示精度并不固定：从源码 wezterm/src/cli/list_clients.rs 可以看到，时间格式化有一个自适应的精度调整逻辑——当秒数不足 60 秒时保留毫秒级精度（如 31.40978ms），超过 60 秒则自动降为整秒精度（如 166s），避免输出过度冗长。此外，表格实际还包含一列源码级存在但示例中常为空的 SSH_AUTH_SOCK 列（列定义见 list_clients.rs），用于显示通过 SSH 连接时客户端持有的 SSH 认证 socket 路径，本地直连时该列为空。

输出格式控制：--format

命令通过 --format 参数控制输出格式，支持两种取值，默认值为 table：

$ wezterm cli list-clients --help
list clients

Usage: wezterm cli list-clients [OPTIONS]

Options:
      --format <FORMAT>  Controls the output format. "table" and "json" are
                         possible formats [default: table]
  -h, --help             Print help

在 CLI 实现 wezterm/src/cli/list_clients.rs 中，format 被定义为带默认值 table 的枚举参数，解析逻辑由 clap 完成，取值非法时会在参数解析阶段直接报错退出。

表格格式（table）

表格模式对每列显式声明了名称与对齐方式：USER、HOST、CONNECTED、IDLE、WORKSPACE、SSH_AUTH_SOCK 左对齐，PID、FOCUS 右对齐，随后借助 tabout 库的 tabulate_output 完成对齐渲染（见 list_clients.rs）。表格的每一行数据来源于 mux 中的 ClientInfo，其中 workspace 与 SSH socket 字段在缺失时以空字符串占位，FOCUS 在无焦点 pane 时为空白（见 list_clients.rs）。

JSON 格式（json）

当需要脚本化处理或与其他工具集成时，可使用 JSON 输出：

$ 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
  }
]

JSON 输出与表格列的对应关系如下：

JSON 字段	对应表格列	类型与说明
username	USER	字符串，会话关联的用户名
hostname	HOST	字符串，会话关联的主机名
pid	PID	无符号整数，客户端进程 ID
connection_elapsed	CONNECTED	对象 {secs, nanos}，自连接建立以来的时长
idle_time	IDLE	对象 {secs, nanos}，距最后一次收到输入的时长
workspace	WORKSPACE	字符串，活动 workspace 名，缺失时为空串
focused_pane_id	FOCUS	可选整数（Option<PaneId>），无焦点 pane 时为 null
ssh_auth_sock	SSH_AUTH_SOCK	可选字符串，SSH 认证 socket 路径

对应结构体 CliListClientsResultItem 定义在 wezterm/src/cli/list_clients.rs。值得注意：源码注释明确指出该结构体直接序列化为命令输出，属于稳定的对外格式，字段与类型需要谨慎保持向后兼容——这意味着你在脚本中依赖这些 JSON 字段名是安全的，不会在后续小版本中轻易变动。

数据来源与底层实现链路

1. 客户端标识与状态的数据结构

每个被列出的客户端，其信息在 mux 层由两个结构体承载，定义于 mux/src/client.rs：

• ClientId（mux/src/client.rs）：客户端的唯一身份标识，包含 hostname、username、pid、epoch、id 与 ssh_auth_sock。其中 epoch 记录进程启动时的 Unix 时间戳，与单调递增的 id 组合用于区分同一进程内先后建立的不同客户端连接。
• ClientInfo（mux/src/client.rs）：客户端的运行时状态，包含 client_id、connected_at（上次连接时间）、active_workspace（活动 workspace）、last_input（最后一次收到输入的时间）、focused_pane_id（当前焦点 pane）。ClientInfo 还提供了 update_last_input 与 update_focused_pane 两个方法，供服务端在收到客户端输入或焦点切换事件时刷新状态（mux/src/client.rs）。

CONNECTED、IDLE 两个时长字段并非存储值，而是由 CLI 侧在渲染时实时计算的：取当前时间 Utc::now() 减去 connected_at / last_input（见 list_clients.rs），因此展示的是"此时此刻"的精确状态，而非历史快照。

2. RPC 调用链

从命令行到结果的完整链路为：

1. wezterm cli list-clients 解析参数后构造 ListClientsCommand，调用客户端对象的 list_clients()（wezterm/src/cli/mod.rs 处统一分发到各子命令的 run）；
2. list_clients() 通过宏声明为 RPC 调用：rpc!(list_clients, GetClientList = (), GetClientListResponse)（见 wezterm-client/src/client.rs），即向 mux server 发送 GetClientList 请求；
3. 服务端在 wezterm-mux-server-impl/src/sessionhandler.rs 中处理该请求：将任务派发到主线程，调用 Mux::get().iter_clients() 取出全部客户端列表，包装为 GetClientListResponse 返回；
4. CLI 端收到响应后，根据 --format 选择渲染为对齐表格或 pretty 格式的 JSON 数组（serde_json::Serializer::pretty，见 list_clients.rs）。

由于 iter_clients() 直接遍历 mux 中注册的全部客户端，因此当同一个 mux server 被多个 wezterm 客户端共享（例如 wezterm connect 远程接入、多个窗口同时挂载同一会话）时，此命令会一次性列出所有接入方，这是排查"谁占用了会话、哪个客户端卡住导致空闲"等问题的直接入口。

典型使用场景

• 多路复用会话体检：在 WEZTERM_UNIX_SOCK 指向的本地 mux server 上，快速确认当前有哪些客户端进程接入、各自的空闲时长，找出长时间无输入的挂起会话。
• workspace 管理配合：WORKSPACE 列展示各客户端的活动 workspace，可结合 wezterm cli rename-workspace 等命令核对 workspace 归属。
• 脚本化监控：使用 --format json 将输出喂给 jq 等工具，例如筛选出空闲超过阈值的客户端 PID，进而决定是否 wezterm cli kill-pane 清理对应 pane。

更多 CLI 子命令可参考 docs/cli/cli/index.markdown，list 命令则用于列出 panes/tabs 的明细（见 docs/cli/cli/list.md），可与 list-clients 互为补充。

小结

wezterm cli list-clients 是一个信息密度高、输出可编程化的小命令：表格模式适合人工巡检，JSON 模式适合脚本集成；其字段语义在 mux/src/client.rs 与 wezterm/src/cli/list_clients.rs 中一一对应、稳定公开。理解它，是掌握 wezterm 多路复用会话管理的良好起点。