wezterm cli list-clients 命令详解查询多路复用会话的已连接客户端【免费下载链接】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 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与该会话关联的用户名usernameHOST与该会话关联的主机名hostnamePID客户端会话的进程 IDCONNECTED该连接已建立的时间长度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 字段对应表格列类型与说明usernameUSER字符串会话关联的用户名hostnameHOST字符串会话关联的主机名pidPID无符号整数客户端进程 IDconnection_elapsedCONNECTED对象{secs, nanos}自连接建立以来的时长idle_timeIDLE对象{secs, nanos}距最后一次收到输入的时长workspaceWORKSPACE字符串活动 workspace 名缺失时为空串focused_pane_idFOCUS可选整数OptionPaneId无焦点 pane 时为nullssh_auth_sockSSH_AUTH_SOCK可选字符串SSH 认证 socket 路径对应结构体CliListClientsResultItem定义在 wezterm/src/cli/list_clients.rs。值得注意源码注释明确指出该结构体直接序列化为命令输出属于稳定的对外格式字段与类型需要谨慎保持向后兼容——这意味着你在脚本中依赖这些 JSON 字段名是安全的不会在后续小版本中轻易变动。数据来源与底层实现链路1. 客户端标识与状态的数据结构每个被列出的客户端其信息在 mux 层由两个结构体承载定义于 mux/src/client.rsClientIdmux/src/client.rs客户端的唯一身份标识包含hostname、username、pid、epoch、id与ssh_auth_sock。其中epoch记录进程启动时的 Unix 时间戳与单调递增的id组合用于区分同一进程内先后建立的不同客户端连接。ClientInfomux/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 调用链从命令行到结果的完整链路为wezterm cli list-clients解析参数后构造ListClientsCommand调用客户端对象的list_clients()wezterm/src/cli/mod.rs 处统一分发到各子命令的runlist_clients()通过宏声明为 RPC 调用rpc!(list_clients, GetClientList (), GetClientListResponse)见 wezterm-client/src/client.rs即向 mux server 发送GetClientList请求服务端在 wezterm-mux-server-impl/src/sessionhandler.rs 中处理该请求将任务派发到主线程调用Mux::get().iter_clients()取出全部客户端列表包装为GetClientListResponse返回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.markdownlist命令则用于列出 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 多路复用会话管理的良好起点。【免费下载链接】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），仅供参考