WTFUtil 0.51.0 常用命令与快捷键详解

目标：完整梳理终端个人信息仪表盘 WTFUtil（GitHub 仓库 wtfutil/wtf，命令名 wtfutil）v0.51.0 的命令行用法与运行时快捷键——wtfutil 主命令的全部参数（--config / --module / --profile / --version 等）与 save-secret 子命令、TUI 界面内的全局快捷键与模块级快捷键、以及各模块的数据源要求，逐条配实测命令与回显。全文命令与输出均在 Ubuntu 22.04.5 LTS（x86_64）服务器实测通过，实测版本为 v0.51.0（查询日期 2026-10-23）。

⚠️ 防混淆说明：本专栏的 WTFUtil 指 GitHub 上的 wtfutil/wtf 项目，安装后命令名为 wtfutil。它与部分 Linux 发行版软件仓库里自带的 wtf 命令（BSD games 工具集中用于查询术语释义的小工具）毫无关系，两者同名不同物——本文及本专栏所有内容均围绕 wtfutil 命令展开。

一、环境信息

本文实测所用环境如下：

操作系统：Ubuntu 22.04.5 LTS（x86_64）；
WTFUtil 版本：v0.51.0（安装过程见《Ubuntu 22.04 安装 WTFUtil 0.51.0 指南》）；
许可证：MPL-2.0；
终端：支持 256 色的终端，TERM=xterm-256color；
配置文件：~/.config/wtf/config.yml（配置参数的逐项说明见《WTFUtil 0.51.0 配置参数详解》）。

版本回显实测：

wtfutil --version

实测输出：

WTF v0.51.0 (built: 2026-09-29T16:08:28Z)

二、前置条件

已安装 v0.51.0 且 wtfutil --version 输出正常；
终端已设置合法 TERM（如 xterm-256color）：TERM 缺失或非法时启动会报 terminal entry not found（排障实录见《WTFUtil 0.51.0 配置参数详解》第九章 9.3 节，该篇含完整报错回显与解法）；
运行时快捷键操作要求 wtfutil 运行在可交互的前台终端（tmux / screen / 图形终端均可）——TUI 需要真实终端设备，脱离终端执行时会报 open /dev/tty 类错误（实测见 3.5 节）。

三、命令行参数详解（wtfutil 主命令）

wtfutil 主命令的参数全集以 --help 实测输出为准。本节先给全量帮助回显，再逐参数详解。

3.1 --help / -h：查看帮助

wtfutil --help

实测输出（全量）：

Usage:
  wtfutil [OPTIONS] [command] [args...]

Application Options:
  -c, --config=  Path to config file
  -m, --module=  Display info about a specific module, i.e.: 'wtfutil -m=todo'
  -p, --profile  Profile application memory usage
  -v, --version  Show version info

Help Options:
  -h, --help     Show this help message


Commands:
  save-secret <service>
    service      Service URL or module name of secret.
  Save a secret into the secret store. The secret will be prompted for.
  Requires wtf.secretStore to be configured.  See individual modules for
  information on what service and secret means for their configuration,
  not all modules use secrets.

从帮助输出可见 wtfutil 的完整命令面：4 个应用参数（-c / -m / -p / -v）、2 个帮助参数（-h，以及 -v 兼具版本功能）与 1 个子命令（save-secret）。各参数详解见 3.2–3.6 节。

3.2 --version / -v：查看版本

wtfutil --version

实测输出：

WTF v0.51.0 (built: 2026-09-29T16:08:28Z)

输出格式为 WTF <版本号> (built: <构建时间>)。注意产品名显示为 WTF（项目更名 Tessera 的过渡期产物，见《WTFUtil 介绍与选型指南》），构建时间为官方发布时的 UTC 时间戳，可用于核对二进制来源。

3.3 --config / -c：指定配置文件启动

-c / --config= 指定本次启动加载的配置文件路径，不使用默认的 ~/.config/wtf/config.yml：

wtfutil --config=/root/noexit.yml

等价的短参数写法：

wtfutil -c=/root/noexit.yml

正常加载实测：指定一份包含世界时钟的合法配置后启动，界面按该配置渲染（世界时钟模块正常显示）：

│ Beijing      01:44 CST   Oct 24            │

配置文件语法错误的报错实测（指定一个 YAML 缩进写坏的文件）：

wtfutil --config=/root/broken.yml

实测输出：

ERROR Could not load '/root/broken.yml'.

This could mean one of two things:

    1. That file doesn't exist.
    2. That file has a YAML syntax error. Try running it through http://www.yamllint.com to check for errors.

Error: yaml: line 5: mapping values are not allowed in this context

报错最后一句指出 YAML 语法错误的具体行号，按行号修复缩进即可（完整排障过程见《WTFUtil 0.51.0 配置参数详解》第九章 9.4 节）。

3.4 --module / -m：查看模块内置帮助

-m=<模块名> 输出该模块的键盘命令与配置参数说明，全部来自二进制内置文本，离线可用、与当前版本严格一致，是配置模块前必看的第一手资料：

wtfutil -m=todo

实测输出（全量）：

 Keyboard commands for Todo

  \     Open the documentation for this module in a browser
  /     Show/hide this help prompt
  r     Refresh widget
  j     Select next item
  k     Select previous item
        Toggle checkmark
  n     Create new item
  o     Open file
  #     Set tag(s) to show
  f     Filter shown items


  Down          Select next item
  Up            Select previous item
  Esc           Clear selection
  Ctrl-D        Delete item
  Ctrl-J        Demote item
  Ctrl-L        Make item last
  Ctrl-K        Promote item
  Ctrl-F        Make item first
  Enter         Edit item

Configuration Attributes

 positionSettings
 Defines where in the grid this module's widget will be displayed.

 bordered
 Optional Whether or not the module should be displayed with a border.
 Values: true, false

 enabled
 Optional Whether or not this module is executed and if its data displayed onscreen.
 Values: true, false

 focusable
 Optional Whether or  not this module is focusable.
 Values: true, false

 languageTag
 Optional The BCP 47 language tag to localize text to.
 Values: Any supported BCP 47 language tag.

 refreshInterval
 Optional How often this module will update its data.
 Values: A positive integer followed by a time unit (ns, us, ms, s, m, h, or nothing which defaults to s)

 title
 Optional The title string to show when displaying this module

 focusChar
 Optional Define one of the number keys as a short cut key to access the widget.

💡 说明：todo 模块键位表中 j/k（下/上一个条目）、n（新建）、Ctrl-D（删除）等构成了完整的本地待办清单操作集；Toggle checkmark 一行的按键显示为空白是上游帮助文本的显示瑕疵，实际为空格键（Space）切换勾选。

再实测一个带专属参数的模块（clocks 的完整参数表已在配置篇 3.2 节收录）；-m 对不支持帮助文本的模块名会输出其键盘命令段或空内容，均不报错。

3.5 --profile / -p：内存性能分析

-p 启用 Go 内存 profiling，用于排查 wtfutil 自身的内存占用问题（日常使用不需要）：

wtfutil -p

实测输出（启动日志）：

2026/10/23 17:48:55 profile.go:182: profile: memory profiling enabled (rate 4096), /tmp/profile2540668199/mem.pprof

分析数据写入 /tmp/profile<随机数>/mem.pprof，可用 Go 的 go tool pprof <文件> 进一步分析。

⚠️ 在不连接终端设备的执行环境（如自动化脚本、CI）里跑 wtfutil -p，profile 启用后会因无法打开 TTY 继续报错退出：

ERROR open /dev/tty: no such device or address

这是 TUI 应用的共性约束（见第二章第 3 条），不是 -p 参数本身的缺陷。

3.6 save-secret 子命令：向密钥库写入机密

save-secret <service> 把一条机密（secret）写入 wtfutil 的密钥存储，供支持 secrets 的模块引用（如各类 API Key 类模块）。<service> 为服务 URL 或模块名。

wtfutil save-secret testservice

实测输出（在未配置密钥库、且非交互环境下执行）：

Error: EOF

定位：save-secret 执行后会交互式提示输入机密内容，机密输入来自当前终端；在不提供标准输入的环境里读输入直接得到 EOF，故报 Error: EOF。同时该功能要求配置文件中已配置 wtf.secretStore（帮助文本原文：Requires wtf.secretStore to be configured）。

正确用法：先在 config.yml 中配置 wtf.secretStore（指定密钥库路径等），再在交互式终端中运行 wtfutil save-secret <service>，按提示粘贴机密内容回车完成写入。涉及凭据的操作不建议在共享终端或录屏环境进行。

3.7 WTF_CONFIG 环境变量：命令行参数的补充通道

除 --config 外，还可用环境变量 WTF_CONFIG 指定配置文件：

export WTF_CONFIG=/root/noexit.yml
wtfutil

实测：环境变量方式下界面同样按指定配置渲染（世界时钟正常显示）。

⚠️ 实测发现：export WTF_CONFIG 在 shell 会话内持久生效——导出一次后，之后所有不带参数的 wtfutil 都会加载它，直到 unset WTF_CONFIG。排查"配置不生效"时先检查该变量。

四、运行时快捷键详解

以下快捷键在 wtfutil 运行中的 TUI 界面内使用。全局键位来自实测行为与官方文档双重确认，模块级键位来自 -m 内置帮助（3.4 节）。

4.1 全局快捷键

按键	作用	验证方式
`q` 或 `Q`	退出 wtfutil	实测
`Ctrl-R`	强制刷新所有模块的数据（不等 refreshInterval）	官方文档
`Esc`	取消当前模块的键盘焦点	实测
`Tab`	在可聚焦模块间移动焦点（`Shift-Tab` 反向）	实测
数字键 `0`–`9`	跳转聚焦到对应 `focusChar` 的模块	实测

q 退出实测：在运行中的界面按 q，应用退出并在终端打印退出消息（默认配置下的实测回显，节选）：

   _______ ______  _____  _____  ______ _____
|__   __|  ____|/ ____|/ ____||  ____|  __ \     /\
   | |  | |__  | (___ | (___  | |__  | |__) |   /  \
   | |  | __|  \___ \ \___ \ |  __| |  _  /   / /\ \
   | |  | |____ ____) |____) || |____| | \ \  / ____ \
   |_|  |______|_____/|_____/ |______|_|  \_\/_/    \_\
the personal information dashboard for your terminal

Heads up! WTF is being renamed to Tessera. Stay tuned!
The development and maintenance of WTF is supported by sponsorships.
Sponsor the development of WTF at https://github.com/sponsors/FelicianoTech

退出消息由配置项 exitMessage.display 控制（官方文档称设 false 可关闭；v0.51.0 实测该开关未生效、消息照常打印，详见配置篇 5.4 节与 9.5 节）。

数字键聚焦实测：本专栏配置篇的生产模板中，三个可聚焦模块的标题栏分别带数字快捷键 1（值班备忘）、2（系统负载）、3（根分区容量）。在运行界面按 2：

聚焦前，"系统负载"窗口边框为 normal 色单线（┌─┐）；
按 2 后，边框变为 focused 指定的橙色系且线型变为双线（╔═╗）；
按 Esc 后恢复单线常规色。

三态边框对照（界面文本一致，线型与颜色不同）：

聚焦前：┌──────────────── 系统负载 2 ────────────────┐
聚焦后：╔════════════════ 系统负载 2 ════════════════╗

💡 说明：数字快捷键编号来自 Common 参数 focusChar（未显式配置时按模块启用顺序自动分配），标题栏是否显示数字由全局 navigation.shortcuts 控制。参数详解见《WTFUtil 0.51.0 配置参数详解》第五、六章。

Esc 与 Tab 实测：Esc 取消焦点后边框恢复 normal 色（与聚焦态对照即上文）；Tab 把焦点移动到下一个可聚焦模块，边框高亮随之转移——焦点在哪个模块，哪个模块边框呈双线高亮。

\ 与 /（模块级通用键）：\ 用系统默认浏览器打开当前模块的官方文档页；/ 显示或隐藏当前模块内的快捷键帮助浮层。两者对支持它们的模块生效（模块支持情况看 wtfutil -m=<模块名> 输出的 Keyboard commands 段是否包含该键）。

4.2 模块级快捷键（实测模块）

textfile（值班备忘/文本展示）——来自 wtfutil -m=textfile 实测输出：

 Keyboard commands for Textfile

  \     Open the documentation for this module in a browser
  /     Show/hide this help prompt
  l     Select next file
  h     Select previous file
  o     Open file


  Right Select next file
  Left  Select previous file
  Enter Open file

键位解读：filePath 配置为目录时，l / h（或 Right / Left）在目录内的多个文件间切换，o / Enter 用 openFileUtil 配置的工具打开当前文件（openFileUtil 见配置篇 5.6 节）；单文件场景下 l/h 无可见变化（实测确认）。

cmdrunner（自定义命令）：wtfutil -m=cmdrunner 输出中无模块级按键，仅 \ 通用键——该模块纯展示命令输出，无交互操作。

todo（待办清单）：完整键位表见 3.4 节实测输出，核心操作为 n 新建、Enter 编辑、Ctrl-D 删除、j/k 上下选择、f 过滤。

五、模块数据源要求

各模块对数据源的要求差异较大，部署前按需核对（前四个为本文实测模块，后三类为按模块类型归纳）：

模块	数据源	环境要求	实测结论
clocks	系统时区数据库	`/usr/share/zoneinfo/` 存在且 `locations` 值合法	非法时区显示 `no timezone data available`，不崩溃
status	本机进程状态	无	零依赖，转轮动画指示存活
textfile	本地文本/Markdown 文件	`filePath` 指向的路径存在且可读	`format: true` 渲染 Markdown
cmdrunner	任意本地命令	`cmd` 指定的命令在 PATH 中存在	`uptime`、`df` 等输出原样进窗口
todo	本地待办文件	模块在配置中启用后自动管理存储文件	支持 `wtfutil -m=todo` 键位全集
网络类（Weather、IP 地址等）	公网 API	服务器可访问对应外部服务	需外网连通，超时见日志
平台类（GitHub、Jira、PagerDuty 等）	平台 API + API Key	配置文件中提供对应 `apiKey` 等凭据	凭据用 `save-secret`/`wtf.secretStore` 管理可免明文

💡 技术拓展：TUI 监控工具的数据获取模式常见三种——本地命令直采（cmdrunner/status，无外部依赖）、本地文件轮询（textfile/todo）、远端 API 拉取（GitHub/Weather 等，需网络与凭据）。WTFUtil 三种并存且以 refreshInterval 统一节流；同类工具 glances（见《glances 4.5.8 常用 CLI 命令与工具详解》）则全部走本地系统采集 + C/S 导出模式，选型时按数据源形态取舍即可。

六、注意事项

-m 是配置模块的第一步：先 wtfutil -m=<模块名> 看当前版本的内置参数表，再写配置，避免照抄网上旧版本参数；
配置改动需重启：wtfutil 无热重载，改完 config.yml 必须 q 退出后重新启动；
WTF_CONFIG 残留：会话内 export 过 WTF_CONFIG 后所有 wtfutil 调用都受其影响，多配置切换优先用 -c 显式指定；
凭据安全：save-secret 写入的机密与 wtf.secretStore 配合使用；githubAPIKey 等凭据也可以走 WTF_GITHUB_TOKEN 环境变量，避免写进配置文件；
非交互环境跑不了 TUI：cron、CI 等无 TTY 场景下 wtfutil 会报 open /dev/tty 退出，长驻使用建议放进 tmux/screen 会话。

七、常见问题（FAQ）

Q1：wtfutil --config=/root/broken.yml 报 Could not load，文件明明存在？ 路径存在但 YAML 语法有错——报错最后一行 yaml: line N: ... 会给出出错行号，按行修缩进（实测回显与解法见 3.3 节与配置篇 9.4 节）。

Q2：wtfutil -m=clocks 报错 terminal entry not found 或 open /dev/tty？ 两类环境问题：前者是 TERM 未设置或配置了非法 term（解法：export TERM=xterm-256color，见配置篇 9.3 节）；后者是执行环境没有终端设备（cron/CI），改到交互终端或 tmux 里运行。

Q3：数字键按了没反应？ 确认目标模块可聚焦且被分配了该数字：看界面标题栏是否带数字（navigation.shortcuts: true 时显示）；也可在配置里显式指定 focusChar。数字只对 enabled: true 且 focusable 生效的模块有效。

Q4：save-secret 报 Error: EOF？ 它需要交互式终端读取机密输入，且需先配置 wtf.secretStore；在非交互环境执行必然 EOF（实测见 3.6 节）。

Q5：怎么确认当前跑的是哪个配置文件？ 按优先级排查：命令行是否带了 -c（ps -ef | grep wtfutil 可见）→ 环境变量 echo $WTF_CONFIG → 默认 ~/.config/wtf/config.yml。三种方式的加载行为均经实测（见 3.3 与 3.7 节）。

八、参考链接

WTFUtil 官方文档站（Quick Start 的命令行选项与全局键盘命令）：https://wtfutil.com/
GitHub 仓库与 Releases：https://github.com/wtfutil/wtf
模块键盘命令与参数的一手来源：wtfutil -m=<模块名>（离线内置，见 3.4 节）
本专栏相关文档：《WTFUtil 介绍与选型指南》（定位与选型）、《Ubuntu 22.04 安装 WTFUtil 0.51.0 指南》（安装与排障）、《WTFUtil 0.51.0 配置参数详解》（配置文件与参数）。