Superset settings via CLI
Change the desktop app's user settings from the command line with
superset settings. Works offline, no login required; everything is local
to this machine.
Commands
superset settings list # every key: value, default, allowed values
superset settings get <key> # effective value (default if unset)
superset settings set <key> <value> # validated write
superset settings reset <key> # back to the app default
superset settings theme list # system + built-ins + imported custom themes
superset settings theme get
superset settings theme set <id> # e.g. dark | light | monokai | system | <custom id>
superset settings theme set system --system-light light --system-dark monokai
superset settings theme export <id> [--out <file>] # dump full theme JSON (starter)
superset settings theme import <file> # add/replace custom themes (validated)
superset settings theme remove <id> # delete a custom theme
Prefer --json (auto-on in agent environments; parse it rather than
matching the human sentences) and superset settings list to discover keys
and allowed values instead of guessing. In Superset terminals superset is
already on PATH. SUPERSET_HOME_DIR overrides the target profile
(~/.superset by default); useful for testing against a sandbox copy.
Creating custom themes
Two paths; both end with import → set (a running app restyles live).
From scratch: a minimal file is enough. Every color you omit is filled
in from the built-in base theme for your declared type, so start small and
override only what you care about:
{
"name": "Midnight Ocean",
"type": "dark",
"ui": {
"background": "#071A2E",
"sidebar": "#061426",
"primary": "#38BDF8"
},
"terminal": { "background": "#071A2E", "cursor": "#38BDF8" }
}
superset settings theme import ocean.json # -> Imported 1 theme: midnight-ocean
superset settings theme set midnight-ocean # a running app applies it live
From a starter: export any theme's complete definition (all ~38 ui +
21 terminal colors) and edit it. Best when restyling everything:
superset settings theme export dark --out my-theme.json
# edit, then:
superset settings theme import my-theme.json && superset settings theme set my-theme
Theme file anatomy
| Field |
Notes |
name / id |
either works; the id is slugified ("Midnight Ocean" → midnight-ocean). Reserved: dark, light, monokai, system |
type |
"dark" or "light" (defaults to dark); picks the base theme that fills omitted colors |
ui |
app chrome. Highest-impact keys: background, foreground, sidebar, card, popover, primary, accent, muted, border, input, ring, plus sidebar* variants |
terminal |
xterm colors: background, foreground, cursor, selectionBackground, and the 16 ANSI names (red, brightRed, ...) |
editor |
optional { "colors": {...}, "syntax": {...} } for the file editor; generated from ui/type when omitted |
author, version, description |
optional metadata |
Rules (same parser as the app's Appearance → Import): all colors are CSS color
strings; missing colors inherit from the base; a file can hold one theme, an
array, or a pack { "themes": [...] }; max 256 KB; re-importing an id
replaces that theme; import never activates; theme set does.
Verify and iterate
superset settings theme list # SOURCE column shows custom; * marks active
superset settings theme get # active theme id
superset settings theme export midnight-ocean # round-trip the stored result
superset settings theme remove midnight-ocean # active falls back to dark
Iterating on colors: each import replaces the theme, and a running app
applies it live; the loop is edit → import → theme set <id> (re-set to
re-apply the active theme after edits).
How changes take effect
After every write the CLI nudges the running desktop app
(POST /settings-changed on its local server) and the app refreshes
immediately, themes included, no restart. The command output tells you
which happened: "refreshed immediately" / "Applied to the running desktop
app" means the nudge landed. The notes below are the fallback behavior when
no app acknowledged (app not running, or an older app version):
- Regular settings (most of
settings set): written to
~/.superset/local.db. A running older app picks them up the next time
its window regains focus; no restart needed.
- Git settings (
branchPrefixMode, branchPrefixCustom,
worktreeBaseDir): host-wide values written through the local host
service (auth via its manifest, no login needed). Requires the desktop app
or superset start to be running; also refreshed on window focus.
- Ringtone caveat:
selectedRingtoneId changes what sound plays
immediately, but the checkmark in Settings → Notifications only updates
after an app restart.
- Theme (
settings theme set): applies live when the nudge lands. If
the output shows the restart fallback instead: quit the app cleanly first,
then set, then relaunch; a running older app overwrites the file on its
own writes. If you are an agent running inside a Superset terminal, never
kill the app yourself (that kills your own session); ask the user to
restart instead.
- Both stores are created by the desktop app. On a machine that never ran
the app,
set commands fail with a hint to launch it once.
Key reference (by section)
Booleans accept true/false/on/off/1/0/yes/no.
| Section |
Keys |
| behavior |
confirmOnQuit, fileOpenMode (split-pane|new-tab), showResourceMonitor, openLinksInApp, defaultEditor (vscode, cursor, zed, ...) |
| git |
branchPrefixMode (none|github|author|custom), branchPrefixCustom, worktreeBaseDir; host-wide, written through the local host service, so the app (or superset start) must be running |
| notifications |
selectedRingtoneId (shamisen, arcade, ping, quick, doowap, woman, african, afrobeat, edm, comeback, shabala), notificationSoundsMuted, notificationVolume (0-100) |
| terminal |
terminalLinkBehavior (external-editor|file-viewer), terminalParkedRuntimeCap (2-64), showPresetsBar, useCompactTerminalAddButton, autoApplyDefaultPreset, waitForSetupBeforeAgent |
| terminal appearance |
terminalFontFamily, terminalFontSize (10-24, 0.5 steps), terminalLineHeight (1-2.5), terminalLetterSpacing (-2-4), terminalFontWeight (100-900), terminalLigatures, terminalMinimumContrast (1|3|4.5|7), terminalCursorStyle (block|bar|underline), terminalCursorBlink |
| editor appearance |
editorFontFamily, editorFontSize, editorLineHeight, editorLetterSpacing, editorFontWeight, editorLigatures |
Not settable here (by design)
exposeHostServiceViaRelay: security-sensitive; the app gates it behind
a plan check and an explicit confirmation dialog. Point the user to
Settings → Security.
- Structured settings (terminal presets, agent preset overrides/custom
agents, disabled agent hooks); use
superset agents ... or the app UI.
deleteLocalBranch and other renderer-only prefs stored in the app's
localStorage (diff view, chat model, hotkey rebinds) are not reachable
from outside the renderer.
Examples
# Dark theme with bigger terminal text
superset settings theme set dark
superset settings set terminalFontSize 16
superset settings set terminalLineHeight 1.4
# Quieter notifications
superset settings set notificationVolume 40
superset settings set selectedRingtoneId ping
# Git hygiene (host service must be running)
superset settings set branchPrefixMode custom
superset settings set branchPrefixCustom kiet/
1---
2name: superset-settings
3description: Read and update the Superset desktop app's user settings (theme, fonts, terminal, git, notifications, behavior) via the superset CLI, including creating and installing custom themes from JSON. Use when asked to change app settings, switch or create a theme, adjust fonts, or configure desktop preferences without opening the settings UI.
4metadata:
5 source: https://skillmd.com/skills/superset-sh/superset-settings
6---
7
8# Superset settings via CLI
9
10Change the desktop app's user settings from the command line with
11`superset settings`. Works offline, no login required; everything is local
12to this machine.
13
14## Commands
15
16```bash
17superset settings list # every key: value, default, allowed values
18superset settings get <key> # effective value (default if unset)
19superset settings set <key> <value> # validated write
20superset settings reset <key> # back to the app default
21
22superset settings theme list # system + built-ins + imported custom themes
23superset settings theme get
24superset settings theme set <id> # e.g. dark | light | monokai | system | <custom id>
25superset settings theme set system --system-light light --system-dark monokai
26
27superset settings theme export <id> [--out <file>] # dump full theme JSON (starter)
28superset settings theme import <file> # add/replace custom themes (validated)
29superset settings theme remove <id> # delete a custom theme
30```
31
32Prefer `--json` (auto-on in agent environments; parse it rather than
33matching the human sentences) and `superset settings list` to discover keys
34and allowed values instead of guessing. In Superset terminals `superset` is
35already on PATH. `SUPERSET_HOME_DIR` overrides the target profile
36(`~/.superset` by default); useful for testing against a sandbox copy.
37
38## Creating custom themes
39
40Two paths; both end with import → set (a running app restyles live).
41
42**From scratch**: a minimal file is enough. Every color you omit is filled
43in from the built-in base theme for your declared `type`, so start small and
44override only what you care about:
45
46```json
47{
48 "name": "Midnight Ocean",
49 "type": "dark",
50 "ui": {
51 "background": "#071A2E",
52 "sidebar": "#061426",
53 "primary": "#38BDF8"
54 },
55 "terminal": { "background": "#071A2E", "cursor": "#38BDF8" }
56}
57```
58
59```bash
60superset settings theme import ocean.json # -> Imported 1 theme: midnight-ocean
61superset settings theme set midnight-ocean # a running app applies it live
62```
63
64**From a starter**: export any theme's complete definition (all ~38 ui +
6521 terminal colors) and edit it. Best when restyling everything:
66
67```bash
68superset settings theme export dark --out my-theme.json
69# edit, then:
70superset settings theme import my-theme.json && superset settings theme set my-theme
71```
72
73### Theme file anatomy
74
75| Field | Notes |
76| --- | --- |
77| `name` / `id` | either works; the id is slugified (`"Midnight Ocean"` → `midnight-ocean`). Reserved: `dark`, `light`, `monokai`, `system` |
78| `type` | `"dark"` or `"light"` (defaults to dark); picks the base theme that fills omitted colors |
79| `ui` | app chrome. Highest-impact keys: `background`, `foreground`, `sidebar`, `card`, `popover`, `primary`, `accent`, `muted`, `border`, `input`, `ring`, plus `sidebar*` variants |
80| `terminal` | xterm colors: `background`, `foreground`, `cursor`, `selectionBackground`, and the 16 ANSI names (`red`, `brightRed`, ...) |
81| `editor` | optional `{ "colors": {...}, "syntax": {...} }` for the file editor; generated from `ui`/`type` when omitted |
82| `author`, `version`, `description` | optional metadata |
83
84Rules (same parser as the app's Appearance → Import): all colors are CSS color
85strings; missing colors inherit from the base; a file can hold one theme, an
86array, or a pack `{ "themes": [...] }`; max 256 KB; re-importing an id
87replaces that theme; import never activates; `theme set` does.
88
89### Verify and iterate
90
91```bash
92superset settings theme list # SOURCE column shows custom; * marks active
93superset settings theme get # active theme id
94superset settings theme export midnight-ocean # round-trip the stored result
95superset settings theme remove midnight-ocean # active falls back to dark
96```
97
98Iterating on colors: each `import` replaces the theme, and a running app
99applies it live; the loop is edit → import → `theme set <id>` (re-set to
100re-apply the active theme after edits).
101
102## How changes take effect
103
104After every write the CLI nudges the running desktop app
105(`POST /settings-changed` on its local server) and the app refreshes
106immediately, themes included, no restart. The command output tells you
107which happened: "refreshed immediately" / "Applied to the running desktop
108app" means the nudge landed. The notes below are the fallback behavior when
109no app acknowledged (app not running, or an older app version):
110
111- **Regular settings** (most of `settings set`): written to
112 `~/.superset/local.db`. A running older app picks them up the next time
113 its window regains focus; no restart needed.
114- **Git settings** (`branchPrefixMode`, `branchPrefixCustom`,
115 `worktreeBaseDir`): host-wide values written through the local host
116 service (auth via its manifest, no login needed). Requires the desktop app
117 or `superset start` to be running; also refreshed on window focus.
118- **Ringtone caveat**: `selectedRingtoneId` changes what sound plays
119 immediately, but the checkmark in Settings → Notifications only updates
120 after an app restart.
121- **Theme** (`settings theme set`): applies live when the nudge lands. If
122 the output shows the restart fallback instead: quit the app cleanly first,
123 then set, then relaunch; a running older app overwrites the file on its
124 own writes. If you are an agent running inside a Superset terminal, never
125 kill the app yourself (that kills your own session); ask the user to
126 restart instead.
127- Both stores are created by the desktop app. On a machine that never ran
128 the app, `set` commands fail with a hint to launch it once.
129
130## Key reference (by section)
131
132Booleans accept `true/false/on/off/1/0/yes/no`.
133
134| Section | Keys |
135| --- | --- |
136| behavior | `confirmOnQuit`, `fileOpenMode` (`split-pane\|new-tab`), `showResourceMonitor`, `openLinksInApp`, `defaultEditor` (vscode, cursor, zed, ...) |
137| git | `branchPrefixMode` (`none\|github\|author\|custom`), `branchPrefixCustom`, `worktreeBaseDir`; host-wide, written through the local host service, so the app (or `superset start`) must be running |
138| notifications | `selectedRingtoneId` (shamisen, arcade, ping, quick, doowap, woman, african, afrobeat, edm, comeback, shabala), `notificationSoundsMuted`, `notificationVolume` (0-100) |
139| terminal | `terminalLinkBehavior` (`external-editor\|file-viewer`), `terminalParkedRuntimeCap` (2-64), `showPresetsBar`, `useCompactTerminalAddButton`, `autoApplyDefaultPreset`, `waitForSetupBeforeAgent` |
140| terminal appearance | `terminalFontFamily`, `terminalFontSize` (10-24, 0.5 steps), `terminalLineHeight` (1-2.5), `terminalLetterSpacing` (-2-4), `terminalFontWeight` (100-900), `terminalLigatures`, `terminalMinimumContrast` (1\|3\|4.5\|7), `terminalCursorStyle` (`block\|bar\|underline`), `terminalCursorBlink` |
141| editor appearance | `editorFontFamily`, `editorFontSize`, `editorLineHeight`, `editorLetterSpacing`, `editorFontWeight`, `editorLigatures` |
142
143## Not settable here (by design)
144
145- `exposeHostServiceViaRelay`: security-sensitive; the app gates it behind
146 a plan check and an explicit confirmation dialog. Point the user to
147 Settings → Security.
148- Structured settings (terminal presets, agent preset overrides/custom
149 agents, disabled agent hooks); use `superset agents ...` or the app UI.
150- `deleteLocalBranch` and other renderer-only prefs stored in the app's
151 localStorage (diff view, chat model, hotkey rebinds) are not reachable
152 from outside the renderer.
153
154## Examples
155
156```bash
157# Dark theme with bigger terminal text
158superset settings theme set dark
159superset settings set terminalFontSize 16
160superset settings set terminalLineHeight 1.4
161
162# Quieter notifications
163superset settings set notificationVolume 40
164superset settings set selectedRingtoneId ping
165
166# Git hygiene (host service must be running)
167superset settings set branchPrefixMode custom
168superset settings set branchPrefixCustom kiet/
169```