用 cli-anything-iterm2 管理 iTerm2 Profiles 与 Preferences：从配色预设到 tmux 偏好的一体化配置实践-北京尧图网络

用 cli-anything-iterm2 管理 iTerm2 Profiles 与 Preferences从配色预设到 tmux 偏好的一体化配置实践【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本文聚焦 CLI-Anything 生态中 cli-anything-iterm2 的配置管理能力讲解如何用profile与pref两组命令对正在运行的 iTerm2 实例进行外观Profile / 配色预设与全局偏好PreferenceKey / 主题 / tmux 相关开关的编程化读写。读完本文你将能复刻本文全部命令完成「查看全部 Profile → 按 GUID 取详情 → 套用 Solarized Dark 配色 → 调整 tmux 窗口打开方式与 dashboard 上限 → 检测当前主题」的完整自动化流程并理解每个命令在底层 iTerm2 Python API 与 CLI 之间是如何落地的。文中所有结论均可在 profile-pref.md 与对应源码模块中得到验证。一、先分清两组概念Profiles 与 Preferences在 iTerm2 中profile配置文件与preference全局偏好是两层不同的设置概念作用对象典型内容cli-anything-iterm2 入口Profile单个会话/窗口的外观与行为模板字体、颜色、badge 文本、按键映射profile命令组PreferenceiTerm2 应用级全局开关打开 tmux 窗口的方式、dashboard 条目数、自动隐藏客户端等pref命令组这一区分直接映射到 CLI 的两组子命令结构上见 iterm2_ctl_cli.pyprofile组与 iterm2_ctl_cli.pypref组。二、运行前提一条命令能触达 iTerm2 的三个必要条件所有profile/pref命令最终都经由 iterm2_backend.py 中的run_iterm2()同步包装器驱动 iTerm2 Python API 通过 WebSocket 连接正在运行的 iTerm2.app。因此执行前需满足iTerm2 正在运行macOSbrew install --cask iterm2已启用 Python APIiTerm2 → Preferences → General → Magic → Enable Python API该提示同时出现在 CLI 的帮助文本与后端错误信息中Python 侧依赖就绪安装cli-anything-iterm2或pip install -e .底层会import iterm2见 iterm2_backend.py 的require_iterm2_running()。命令统一形态为cli-anything-iterm2 [--json] group command [OPTIONS] [ARGS]其中--json会以结构化 JSON 输出结果便于 Agent 解析profile组还遵守 CLI 的「会话上下文」机制——apply-preset未显式传--session-id时会回退到此前通过app current/app set-context保存的上下文 session见 iterm2_ctl_cli.py。三、Profile 命令查列表、取详情、套配色参考文档 profile-pref.md 给出的 Profile 命令全集cli-anything-iterm2 profile list [--filter NAME] cli-anything-iterm2 profile get guid # detailed settings cli-anything-iterm2 profile color-presets cli-anything-iterm2 profile apply-preset Solarized Dark [--session-id ID]3.1profile list枚举可用 Profile列出 iTerm2 中全部 Profile 的名称 GUID对。--filter NAME支持按名称子串过滤不区分大小写。其底层实现位于 core/profile.py 的list_profiles()通过iterm2.PartialProfile.async_query(connection)拉取所有 Profile过滤时使用name_filter.lower() not in name.lower()空名以(unnamed)兜底。# 全量列表 cli-anything-iterm2 profile list # 只看名称含 dark 的 Profile cli-anything-iterm2 profile list --filter dark3.2profile get guid按 GUID 取详情get需要你在profile list中拿到的 GUID返回该 Profile 的关键字段。需要如实说明当前的「详情」是精选子集——从 core/profile.py 看get_profile_detail()先按 GUID 匹配PartialProfile再调用async_get_full_profile()取全量 Profile但仅导出三个字段return { name: full.name, guid: full.guid, badge_text: full.badge_text, }CLI 层iterm2_ctl_cli.py据此逐行打印name、guid、badge_text。若 GUID 不存在get_profile_detail()会抛出ValueError: Profile with GUID ... not found.由 CLI 统一格式化为Error: ...并退出见 handle_iterm2_error。cli-anything-iterm2 profile list # 先找 GUID cli-anything-iterm2 profile get guid # 再取详情3.3profile color-presets枚举可用配色预设列出 iTerm2 内置的全部颜色预设名返回经过排序的字符串列表。实现为 core/profile.py 的list_color_presets()即iterm2.ColorPreset.async_get_list(connection)后sorted()。执行cli-anything-iterm2 profile color-presets3.4profile apply-preset给指定会话套用配色把命名配色预设应用到某个会话的 Profile 上例如经典深色方案Solarized Darkcli-anything-iterm2 profile apply-preset Solarized Dark cli-anything-iterm2 profile apply-preset Solarized Dark --session-id w0t0p0需要特别说明其作用范围apply_color_preset()core/profile.py并非修改磁盘上的 Profile 定义而是取当前会话的 Profile 对象 →ColorPreset.async_get(connection, preset_name)拿到预设 →profile.async_set_color_preset(preset)→ 再session.async_set_profile(profile)写回会话本质是对该会话生效的即时配色切换。底层流程可概括为async_find_session(connection, session_id)定位目标会话见 iterm2_backend.pyColorPreset.async_get()按名取预设把预设套到会话 Profile 并回写会话。成功返回{session_id, preset_applied}若预设名不存在iTerm2 API 侧会抛错并由 CLI 统一呈现。四、Pref 命令全局偏好的发现、读取与写入pref组的核心价值在于「以代码方式读写任意 iTerm2 全局偏好」参考文档给出的完整命令集cli-anything-iterm2 pref list-keys # all valid PreferenceKey names cli-anything-iterm2 pref list-keys --filter tmux # filter by substring cli-anything-iterm2 pref get OPEN_TMUX_WINDOWS_IN cli-anything-iterm2 pref set OPEN_TMUX_WINDOWS_IN 2 cli-anything-iterm2 pref theme # current theme tags is_dark bool4.1pref list-keys发现所有合法键名不必记忆偏好键先让 CLI 告诉你全部合法键名cli-anything-iterm2 pref list-keys cli-anything-iterm2 pref list-keys --filter tmux # 只看与 tmux 相关的 cli-anything-iterm2 pref list-keys --filter font # 只看字体相关其实现iterm2_ctl_cli.py直接遍历iterm2.preferences.PreferenceKey枚举把所有成员的枚举名形如OPEN_TMUX_WINDOWS_IN按字典序排序输出--filter为不区分大小写的子串过滤结果中同时给出count。4.2pref get/pref set键名解析与值类型归一化cli-anything-iterm2 pref get OPEN_TMUX_WINDOWS_IN cli-anything-iterm2 pref set OPEN_TMUX_WINDOWS_IN 2这两个命令背后是 core/pref.py 的get_preference()与set_preference()。有两个值得展开的实现细节双通道键名解析入参key会先尝试当作iterm2.PreferenceKey的枚举成员名解析如OPEN_TMUX_WINDOWS_IN失败则原样回退为原始偏好键字符串如OpenTmuxWindowsIn所以两种写法都可用。字符串值自动类型化_parse_value()core/pref.py会把 CLI 传入的字符串转成合适类型规则如下输入字符串示例解析结果说明true/false任意大小写True/False布尔值2int2整数字符串优先转 int1.5float1.5非整数的数字串转 floatSolarized Dark等保持字符串其它一律原样保留因此pref set OPEN_TMUX_WINDOWS_IN 2实际写入的是整数2而pref set AUTO_HIDE_TMUX_CLIENT_SESSION true写入的是布尔True无需在命令行区分类型。set_preference最终调用iterm2.async_set_preference(connection, pref_key, parsed)并返回{key, value, set: True}。4.3pref theme读取当前主题标签cli-anything-iterm2 pref theme返回当前 iTerm2 主题的标签列表与is_dark布尔值。实现见get_theme()core/pref.py先iterm2.async_get_app(connection)再调用app.async_get_theme()得到一组标签例如[dark]、[light]或[dark, highContrast]is_dark dark in tags。这对 Agent 判断「当前是深色还是浅色外观、是否高对比度」非常有用例如据此决定要向终端发送什么颜色的 ANSI 输出。五、tmux 偏好速记命令四个高频开关一步到位参考文档为 tmux 相关偏好专门提供了速记层cli-anything-iterm2 pref tmux-get # all tmux prefs at once cli-anything-iterm2 pref tmux-set open_in 2 # 0native_windows 1new_window 2tabs_in_existing cli-anything-iterm2 pref tmux-set auto_hide_client true cli-anything-iterm2 pref tmux-set use_profile true cli-anything-iterm2 pref tmux-set dashboard_limit 105.1pref tmux-get一次性读全get_tmux_preferences()core/pref.py一次性并发读取 4 个 PreferenceKey并附带一个人类可读的标签映射返回字段对应 PreferenceKey说明open_tmux_windows_inOPEN_TMUX_WINDOWS_IN0native_windows1new_window2tabs_in_existinglabel 随附在返回结果中tmux_dashboard_limitTMUX_DASHBOARD_LIMITtmux dashboard 显示的最大条目数auto_hide_tmux_client_sessionAUTO_HIDE_TMUX_CLIENT_SESSION是否自动隐藏 tmux 客户端会话use_tmux_profileUSE_TMUX_PROFILE新建窗口时是否使用 tmux profileCLI 层iterm2_ctl_cli.py除输出完整字典外还会附带一行把open_in的数值还原为文字标签例如open_in: 2 (tabs_in_existing)。5.2pref tmux-set按易记名设置set_tmux_preference()core/pref.py只接受四个人类可读设置名通过内部setting_map映射到 PreferenceKey如果传了未知设置名会抛出ValueError并提示合法集合setting_map { open_in: iterm2.PreferenceKey.OPEN_TMUX_WINDOWS_IN, dashboard_limit: iterm2.PreferenceKey.TMUX_DASHBOARD_LIMIT, auto_hide_client: iterm2.PreferenceKey.AUTO_HIDE_TMUX_CLIENT_SESSION, use_profile: iterm2.PreferenceKey.USE_TMUX_PROFILE, }tmux-set设置名合法取值含义open_in0/1/2tmux 新窗口的呈现方式原生窗口 / 新 iTerm2 窗口 / 并入现有窗口的标签页dashboard_limit整数dashboard 最大条目数auto_hide_clienttrue/false是否自动隐藏 tmux 客户端会话use_profiletrue/false新窗口是否使用 tmux Profile例如把 tmux 窗口默认作为现有窗口中的标签页打开2并让 dashboard 最多显示 10 个条目cli-anything-iterm2 pref tmux-set open_in 2 cli-anything-iterm2 pref tmux-set dashboard_limit 10结合 iTerm2 的 tmux 集成core/tmux.py可以理解这些偏好的意义iTerm2 中每个 tmux 窗口会以 iTerm2 标签页形式出现list_tmux_tabs()只返回tmux_window_id非空的标签页见 core/tmux.py因此「新 tmux 窗口出现在哪里原生窗口/新窗口/现有窗口标签页」由OPEN_TMUX_WINDOWS_IN决定AUTO_HIDE_TMUX_CLIENT_SESSION与USE_TMUX_PROFILE则分别控制客户端会话的显隐与新建窗口所用 Profile。这些偏好与 CLI 的tmux create-window、tmux set-visible、tmux bootstrap等命令配合可实现完整的 tmux -CC 工作流完整流程见 tmux-guide.md。六、从命令到 Python API 的调用链理解整条链路有助于排查问题profile与pref命令并非直接操作 plist 或 AppleScript而是统一的「Click 命令 → 同步桥 → 异步协程 → iTerm2 Python API」结构Click 层iterm2_ctl_cli.py定义profile、pref两组命令负责参数解析、--json格式化与错误兜底同步桥iterm2_backend.py 的run_iterm2(coro_fn, ...)用iterm2.run_until_complete()把异步协程包成同步调用并捕获 WebSocket 连接失败等异常给出「iTerm2 是否在运行 / Python API 是否启用」的排查提示协程实现core/profile.py与core/pref.py中每个函数都签名为async def ...(connection, ...)内部直接调用iterm2.PartialProfile、iterm2.ColorPreset、iterm2.async_get_preference、iterm2.async_set_preference、app.async_get_theme等官方 Python API 对象。因此所有配置操作的实时生效性都来自 iTerm2 自身 APICLI 只是把「需要在 Python REPL 里手写的 async 代码」压缩成了可脚本化、可被 Agent 调用的单行命令。七、测试覆盖与验证方式该功能模块在仓库内配有明确测试清单见 tests/TEST.md 与测试源码test_core.py中的test_profile_helptest_core.py等用例验证profile --help的子命令结构与 CLI 骨架E2E 用例TestProfileOperations覆盖profile list至少返回 1 个 Profile与profile color-presets返回字符串列表等这些用例依赖正在运行的 iTerm2见 test_full_e2e.py子进程级测试如test_json_profile_list确认安装后的命令行入口在--json下也能正常输出涉及pref/tmux的测试会按环境跳过TEST.md 明确记录TestTmuxOperations一类的用例在没有活动tmux -CC会话时会跳过启动方式在 iTerm2 终端内执行tmux -CC。对读者而言最快的本地验证路径是先cli-anything-iterm2 profile color-presets再cli-anything-iterm2 profile apply-preset Solarized Dark随后cli-anything-iterm2 pref tmux-get观察 tmux 四项偏好最后cli-anything-iterm2 pref theme确认主题标签——整个过程均可在一次终端会话内完成且每条命令都能加--json换成结构化输出。八、常见问题速查现象原因与排查Error: Profile with GUID ... not found.profile get的 GUID 非法先用profile list取真实 GUIDError: No session ID specified...apply-preset等会话级命令未传--session-id且未设置上下文先执行app current/app set-contextError: Unknown tmux setting ...tmux-set只接受open_in/dashboard_limit/auto_hide_client/use_profile四个名字命令报无法连接 iTerm2 / WebSocket refused未启动 iTerm2或 Preferences → General → Magic → Enable Python API 未勾选启用后需重启 iTerm2数字以字符串形式写入而非数值只有当值是字符串时_parse_value才会自动转换如需精确布尔或数值直接传true/2形态即可以上行为均可在 profile.py、pref.py 与 iterm2_backend.py 中逐行核验。掌握profile与pref两组命令后iTerm2 的外观与行为配置就不再依赖手工点击菜单而可以沉淀为可复现的脚本与 Agent 工作流中的标准步骤。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

用 cli-anything-iterm2 管理 iTerm2 Profiles 与 Preferences：从配色预设到 tmux 偏好的一体化配置实践

相关推荐

Linux nullfs：重塑根文件系统挂载与内核线程隔离的启动语义

2025年Java技术栈全面盘点：从JVM到微服务与AI应用

Delphi 10.2安装XLSReadWriteII：从解压到Excel读写实战指南

更多资讯

GD32烧录指南：GD LINK Programmer配置、操作与故障排查

14款论文降重降AI工具横向评测：从查重原理到实战选型指南

Android歌词渐变：用LinearGradient实现卡拉OK式进度高亮

基于Hadoop+Spark+Hive的游戏推荐系统毕业设计实战

企业AI Agent选型指南：十大开源平台深度解析与落地经验

云端验证+ARM加固：软件授权管理系统设计全解

今日更新

在S3C2410上移植Nucleus RTOS：启动、驱动与实时性调优实战

2026年Turnitin降重降AI二合一红黑榜：能过和别碰

2026期刊投稿AI写作工具实测：6款打分谁更值得用

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？