用途 superset-settings 是 Superset 桌面应用的设置管理命令行入口，用于在不打开界面或手动编辑配置文件的情况下，查询和修改本机的用户设置。它完全离线工作，不需要登录，数据只保存在本机。
主要能力
- 设置读写：superset settings list 列出所有键、当前值、默认值和允许值；get 读取某键的有效值（未设置时返回默认值）；set 进行校验后写入；reset 恢复应用默认值。
- 主题管理：可列出系统主题、内置主题和已导入的自定义主题，获取当前主题，设置主题（如 dark、light、monokai、system 或自定义 id），还支持为 system 主题分别指定浅色和深色的具体主题。
- 主题导入导出：export 导出完整主题 JSON（约 38 个 ui 颜色和 21 个 terminal 颜色）；import 导入或替换自定义主题；remove 删除自定义主题。导入时只校验、不激活，需再执行 theme set 才会生效。
- 设置覆盖范围：行为（退出确认、文件打开方式、资源监视、默认编辑器等）、Git（分支前缀模式、自定义前缀、worktree 基础目录）、通知（铃声、静音、音量）、终端外观与行为（字体、字号、行高、字距、字重、连字、最小对比度、光标样式与闪烁、链接行为等）、编辑器外观（字体相关设置）。
使用方式 在 Superset 终端中，superset 已在 PATH 上。建议使用 --json 输出（在智能体环境中自动开启），解析结构化结果而不是匹配人类可读句子，并用 list 先发现键和允许值。SUPERSET_HOME_DIR 可覆盖目标配置目录（默认 ~/.superset），便于在沙盒副本上测试。布尔值接受 true/false/on/off/1/0/yes/no。
创建自定义主题 有两种路径：一是从零编写最小 JSON 文件，只需声明 name、type 以及想覆盖的颜色，其余颜色会从对应类型的内置基础主题继承；二是先 export 一个完整主题再编辑。主题文件可包含单个主题、主题数组或 { "themes": [...] } 包；最大 256 KB；重新导入相同 id 会替换该主题；导入不会激活主题，theme set 才会。主题 id 会从名称生成短横线形式（如 Midnight Ocean 变为 midnight-ocean），dark、light、monokai、system 为保留 id。主题文件包含 name/id、type（dark 或 light）、ui 颜色、terminal 的 xterm 颜色、可选 editor 颜色与语法配色，以及可选 author、version、description 元数据。
生效机制 每次写入后，CLI 会通知正在运行的桌面应用，应用立即刷新，主题也包含在内，无需重启。输出会说明是否立即刷新。如果应用未运行或版本较旧，则回退：普通设置写入 ~/.superset/local.db，旧版应用在窗口重新获得焦点时读取；Git 设置通过本地主机服务写入，需要桌面应用或 superset start 正在运行。铃声设置的选中铃声立即改变播放声音，但设置界面的勾选标记需重启后更新。主题设置在通知成功时即时生效；若输出显示需要重启回退，应先干净退出应用，再设置，再启动。若在 Superset 终端内以智能体身份运行，不要自行结束应用，否则会终止自身会话，应请用户重启。两种存储均由桌面应用创建；若机器从未运行过应用，set 命令会失败并提示先启动一次。
适用场景 适合批量调整 Superset 设置、在脚本或自动化流程中读取配置、快速切换或试调主题配色，以及在智能体环境中通过 CLI 管理应用偏好。
限制 并非所有设置都可从 CLI 修改：安全敏感的 exposeHostServiceViaRelay 需在设置界面中经计划检查与确认对话框开启；终端预设、智能体预设覆盖与自定义智能体、禁用的智能体钩子属于结构化设置，应使用 superset agents 或应用界面；deleteLocalBranch 以及差异视图、聊天模型、快捷键重绑定等仅存于渲染进程 localStorage 的偏好无法从外部访问。