Settings Sync & Config File

Keep settings consistent with iCloud, or control selected values from a text file

iCloud Settings Sync

Open Settings → Privacy & Data → iCloud Sync, enable iCloud Sync, then turn on Sync Settings. This switch is separate from the controls for SSH history, known hosts, and connection profiles. SSH private keys also use a separate iCloud Keychain setting managed per key.

App settings are stored and merged individually. A change to one setting does not replace another device’s complete configuration. After the initial merge, the newest change to each unpinned setting is used across devices signed into the same Apple Account.

First-time merge

If both this device and iCloud already contain settings, rootshell asks which side should win where the same key exists:

Use Settings from iCloud applies iCloud values for overlapping keys. Settings that exist only on this device are kept and uploaded.
Keep This Device’s Settings uploads this device’s values for overlapping keys. Settings found only in iCloud are still kept.
Pinned settings remain local with either choice.

If the Apple Account changes, settings sync pauses so values from two accounts are not combined silently. Turn Sync Settings on again and choose which settings to keep.

Keep Settings on One Device

Touch and hold a setting, or right-click it on Mac, and choose Keep on This Device. The setting stops following iCloud while other settings continue to sync. Device-shaped and platform-specific settings may start in this local state.

Synced Groups shows which groups follow iCloud and lets you keep or sync a whole group.
Pinned Settings lists individual, group, config-file, and always-local settings.
When a pinned setting has a different value waiting in iCloud, syncing it again asks whether to use the iCloud value or send the local value.

Optional Text Config File

Open Settings → Privacy & Data → Config File to create the standard file, choose an external file, edit or reload it, inspect diagnostics, or export current settings. The file uses a Ghostty-style key = value format and is separate from the generated terminal-engine config that rootshell maintains.

Build	Standard path
Standalone macOS	`~/.config/rootshell/config`
Sandboxed macOS	`~/Documents/rootshell.conf`
iPhone and iPad	`~/rootshell.conf`, visible as `rootshell.conf` in the app’s Files folder

You can also select a file from iCloud Drive or a dotfile repository. A shared file pins every active key on each device that uses it.

Syntax

# Lines beginning with # are comments
theme = Catppuccin Mocha
font-size = 14
cursor-style-blink = true

# Repeat list settings
favorite-theme-ids = Catppuccin Mocha
favorite-theme-ids = Solarized Light

# Include another file; ? makes a missing include optional
config-file = shared.conf
config-file = ?machine-local.conf

Keys are case-insensitive; values are trimmed and may be wrapped in double quotes.
Booleans accept true/false, yes/no, on/off, or 1/0.
An empty value resets that setting to its default while keeping it pinned by the file.
For scalar keys repeated in the loaded files, the last value wins. List keys use every repeated value.
Relative includes resolve from the containing file. Includes are cycle-safe and limited to three levels; each file must be UTF-8 and no larger than 256 KiB.
Unknown or invalid keys are ignored and appear under Diagnostics. keybind entries are ignored because shortcuts are managed in Keyboard Shortcuts.

Precedence and write-back

Every active key in the config file overrides the current UI value and is pinned to that device, so an iCloud update cannot replace it. Comment out or remove the key to make it follow iCloud again; if rootshell has a newer iCloud value waiting, that value is then adopted. This gives the effective order:

Active config-file value
Device-local value for an individually or group-pinned setting
Latest iCloud value for an unpinned setting
App default

Turn on Allow Settings to Edit This File if changes made in the Settings UI should update file-bound keys. rootshell rewrites only the affected line and preserves comments and ordering. Leave it off to treat file-bound values as read-only in Settings.

Create Config File starts with every supported setting commented out, so it changes nothing until you uncomment a line. Export Current Settings writes current non-default values as active lines and includes defaults as comments. This is the easiest way to discover the exact value spelling for enum-style settings.

Config Key Reference

These are all keys accepted by the current config overlay. Availability can vary by platform and build. Each row gives the value type, every fixed allowed value, and the app default. Enumerated values are case-sensitive. Boolean values are case-insensitive.

Integers and numbers use decimal text with no unit suffix unless a row says otherwise. Supported ranges below describe the values rootshell uses; values outside them may be clamped or replaced with the default. For repeatable text keys, write one line per item. An empty scalar value resets that setting to its default while keeping it file-bound.

AI Assistant

Key	What it configures	Value type	Allowed values and default
`ai-agent-presentation-mode`	AI Presentation	Enumerated text	`sidebar`, `window`. Default: `sidebar`.
`ai-agent-text-size`	AI Text Size	Integer	Whole-number point size from 10 through 24. Default: `14`.
`ai-approval-mode`	Approval Mode	Enumerated text	`ask_all`, `approve_writes_only`, `yolo`. Default: `ask_all`.
`ai-bedrock-region`	Bedrock Region	Enumerated text	`us-east-1`, `us-east-2`, `us-west-2`, `eu-central-1`, `eu-west-1`, `eu-west-2`, `eu-west-3`, `eu-north-1`, `ap-northeast-1`, `ap-northeast-2`, `ap-southeast-1`, `ap-southeast-2`, `ap-south-1`, `ca-central-1`, `sa-east-1`. Default: `us-east-1`.
`ai-commit-message-enabled`	AI Commit Messages	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`ai-commit-message-model`	Commit Message Model	Text	Any configured AI model ID; leave empty to use the global model. Default: empty.
`ai-global-selected-model`	AI Model	Text	Any AI model ID available to rootshell. Default: `gpt-5.6-sol`.
`ai-openrouter-favorites`	The favorite OpenRouter model list; repeat the key for multiple models	Repeatable text	Any OpenRouter model ID. Repeat the key once per item; an empty final entry clears the list. Default: empty list.
`ai-web-search-default-engine`	Default Search Engine	Enumerated text	`duckduckgo`, `google`. Default: `duckduckgo`.
`ai-web-search-enabled`	Enable Web Search	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`voice-agent-consultation-mode`	Expert Consultation	Enumerated text	`let_flash_decide`, `always_consult`, `never_consult`. Default: `let_flash_decide`.
`voice-agent-voice`	Voice	Enumerated text	`Zephyr`, `Puck`, `Charon`, `Kore`, `Fenrir`, `Leda`, `Orus`, `Aoede`, `Callirrhoe`, `Autonoe`, `Enceladus`, `Iapetus`, `Umbriel`, `Algieba`, `Despina`, `Erinome`, `Algenib`, `Rasalgethi`, `Laomedeia`, `Achernar`, `Alnilam`, `Schedar`, `Gacrux`, `Pulcherrima`, `Achird`, `Zubenelgenubi`, `Vindemiatrix`, `Sadachbia`, `Sadaltager`, `Sulafat`. Default: `Kore`.

Clipboard

Key	What it configures	Value type	Allowed values and default
`clipboard-manager-enabled`	Clipboard Manager	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`clipboard-manager-require-biometric`	Require Biometrics to Open Clipboard	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`clipboard-manager-retention`	Keep Clipboard History	Enumerated text	`forever`, `day`, `week`, `month`. Default: `week`.

Coding Agents

Key	What it configures	Value type	Allowed values and default
`agent-attention-badges-enabled`	Show Attention Badges	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`agent-detection-enabled`	Detect Coding Agents	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`agent-inbox-sort`	Agent Sort	Enumerated text	`static`, `priority`, `project`. Default: `static`.
`agent-project-probes`	Look Up Project Details	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`agent-usage-tracking-enabled`	Show Subscription Usage	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.

Connections

Key	What it configures	Value type	Allowed values and default
`auto-reconnect-enabled`	Auto Reconnect	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`auto-reconnect-max-attempts`	Reconnect Attempts	Integer	A positive whole number; zero or a negative value falls back to 5. Default: `5`.
`background-session-keepalive-enabled`	Keep SSH Alive in Background	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`hide-non-pq-kex-warning`	Whether to hide the warning when SSH does not negotiate a post-quantum key exchange	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`profiles-sort-order`	Sort Profiles By	Enumerated text	`name`, `recentlyUsed`, `mostUsed`, `dateCreated`. Default: `name`.
`ssh-force-ipv4-enabled`	Force IPv4	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`ssh-health-monitoring-enabled`	Connection Health Monitoring	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`ssh-health-probe-interval`	The interval between SSH connection health probes	Integer	A positive number of seconds; Settings offers `1`, `5`, `10`, `15`, `30`, `60`. Default: `15`.
`ssh-password-default-auth-requirement`	Saved Password Authentication	Enumerated text	`none`, `perSession`, `perUse`. Default: `none`.
`ssh-password-default-storage-level`	Saved Password Storage	Enumerated text	`deviceOnly`, `backupOnly`, `iCloudSync`. Default: `backupOnly`.
`ssh-public-key-auth-probe-enabled`	OpenSSH Public Key Compatibility	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Cursor

Key	What it configures	Value type	Allowed values and default
`cursor-blink-mode`	Blink Style	Enumerated text	`normal`, `breathing`, `heartbeat`, `neon_flicker`, `pulse`, `candle`, `rootshell`. Default: `normal`.
`cursor-color`	Cursor Color	Optional text	A six-digit RGB hex color such as `f5e0dc`; leave empty to use the theme. Default: unset.
`cursor-effect`	Cursor Effect	Enumerated text	`none`, `warp`, `sweep`, `tail`, `blaze`, `teslaCoil`, `neon`, `aurora`. Default: `none`.
`cursor-height`	Cursor Height	Integer	A whole-number adjustment from -4 through 10. Default: `0`.
`cursor-opacity`	Cursor Opacity	Number	A decimal from 0.0 through 1.0. Default: `0.8`.
`cursor-style-blink`	Whether the cursor blinks	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`cursor-style`	Cursor Style	Enumerated text	`block`, `bar`, `underline`, `block_hollow`. Default: `block`.
`cursor-text`	Text Under Cursor	Optional text	A six-digit RGB hex color such as `1e1e2e`; leave empty to use the theme. Default: unset.
`cursor-thickness`	Cursor Thickness	Integer	A whole-number adjustment from -4 through 10. Default: `0`.

Font

Key	What it configures	Value type	Allowed values and default
`external-display-font-size`	External Display Font Size	Number	A point size; 0 uses the automatic external-display size. Default: `0`.
`font-family`	Font	Optional text	The exact name of an available font family; leave empty to use the default. Default: unset.
`font-size`	Font Size	Number	A point size from 4 through 24. Default: `13`.
`ligatures-enabled`	Enable Ligatures	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.

Gestures

Key	What it configures	Value type	Allowed values and default
`line-scrollback-enabled`	Use Line Scrolling	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`rubber-band-scrollback-enabled`	Rubber Band Scrolling	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`scroll-mode-enabled`	Scroll Mode	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`tab-expose-gesture-enabled`	Pull Down for Tab Exposé	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`two-finger-long-press-duration`	Two-Finger Long Press	Number	Seconds; Settings offers `0`, `0.5`, `1`, `2`. Zero disables the gesture. Default: `0.5`.

Keyboard Toolbar

Key	What it configures	Value type	Allowed values and default
`arrow-joystick-mode`	Arrow Key Mode	Enumerated text	`drawer`, `joystick`. Default: `drawer`.
`keyboard-toolbar-drawer-open-by-default`	Open Drawer by Default	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`keyboard-toolbar-drawer-toggle-mode`	More Button Behavior	Enumerated text	`stack`, `cycle`. Default: `stack`.
`persistent-toolbar`	Persistent Toolbar	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`show-toolbar-with-hardware-keyboard`	Show Toolbar with Hardware Keyboard	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Keyboard

Key	What it configures	Value type	Allowed values and default
`compose-autocorrect-enabled`	Compose Autocorrect	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`double-space-for-period`	Double-Space Period Shortcut	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`force-ascii-keyboard`	Force ASCII Keyboard	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`macos-option-as-alt`	Whether the macOS Option key behaves as Alt	Enumerated text	`off`, `on`, `left`, `right`. Default: `off`. `false` and `true` are accepted aliases for `off` and `on`.

Live Activity

Key	What it configures	Value type	Allowed values and default
`live-activity-enabled`	Live Activity	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`live-activity-network-info-enabled`	Live Activity Network Info	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`live-activity-session-filter`	Which sessions appear in Live Activities	Enumerated text	`all`, `diary`, `vpnOnly`, `infoOnly`. Default: `diary`.
`live-activity-wifi-info-enabled`	Live Activity WiFi Info	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Locale

Key	What it configures	Value type	Allowed values and default
`clock-format`	Clock Format	Enumerated text	`system`, `twelveHour`, `twentyFourHour`. Default: `system`.
`custom-locale`	Custom Locale	Text	A POSIX locale identifier such as `en_US.UTF-8`. Default: `en_US.UTF-8`.
`locale-mode`	Locale	Enumerated text	`auto`, `none`, `custom`. Default: `auto`.

Multiplexers

Key	What it configures	Value type	Allowed values and default
`herdr-custom-command`	herdr Auto-Start Command	Text	Any single-line shell command; leave empty to use the built-in command. Default: empty.
`herdr-session-discovery-enabled`	Discover herdr Sessions	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`herdr-session-name`	herdr Session Name	Text	Any session name; leave empty for automatic selection. Default: empty.
`local-session-discovery-enabled`	Discover Local Sessions	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`session-discovery-sort-order`	Session Sort Order	Enumerated text	`attachedFirst`, `detachedFirst`, `alphabetical`. Default: `attachedFirst`.
`tab-expose-multiplexer-enabled`	Show Multiplexer Tabs in Exposé	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`tmux-auto-hide-gateway-on-attach`	Auto-hide Gateway on Attach	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`tmux-custom-command`	tmux Auto-Start Command	Text	Any single-line shell command; leave empty to use the built-in command. Default: empty.
`tmux-discovery-attach-mode`	How discovered tmux sessions are attached	Enumerated text	`regular`, `control`. Default: `regular`.
`tmux-new-tab-action`	What a new tab does while using tmux control mode	Enumerated text	`localShell`, `tmuxTab`, `ask`. Default: `localShell`.
`tmux-session-discovery-enabled`	Discover tmux Sessions	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`tmux-session-name`	tmux Session Name	Text	Any tmux session name; leave empty for automatic selection. Default: empty.
`tmux-tab-close-action`	What closing a tmux tab does	Enumerated text	`closeWindow`, `detachSession`, `detachSessionAndCloseGateway`, `hideTab`, `ask`. Default: `closeWindow`.
`zellij-session-discovery-enabled`	Discover zellij Sessions	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`zmx-custom-command`	zmx Auto-Start Command	Text	Any single-line shell command; leave empty to use the built-in command. Default: empty.
`zmx-session-discovery-enabled`	Discover zmx Sessions	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`zmx-session-name`	zmx Session Name	Text	Any session name; leave empty for automatic selection. Default: empty.

Notifications

Key	What it configures	Value type	Allowed values and default
`agent-notification-include-prompt`	Include the Question	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`agent-notification-policy`	When coding-agent activity creates notifications	Enumerated text	`off`, `blockedOnly`, `blockedAndDone`, `allTransitions`. Default: `blockedOnly`.
`push-agent-background-only`	Whether agent pushes are limited to times when rootshell is in the background	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`push-agent-logos-enabled`	Whether supported agent pushes include Claude or Codex artwork	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`ssh-notification-enabled`	SSH Session Reminders	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`task-detect-builds`	Detect Builds	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`task-detect-infra`	Detect Infrastructure Commands	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`task-detect-prompts`	Detect Prompts	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`task-detect-tests`	Detect Tests	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`task-detect-transfers`	Detect Transfers	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`task-detection-enabled`	Detect Long-Running Commands	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`task-notification-policy`	When long-running commands create notifications	Enumerated text	`off`, `blockedOnly`, `blockedAndDone`, `allTransitions`. Default: `blockedOnly`.
`terminal-notification-enabled`	Terminal Notifications	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Colors

Key	What it configures	Value type	Allowed values and default
`palette-generate`	Generate Palette	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`palette-harmonious`	Harmonious Palette	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Power

Key	What it configures	Value type	Allowed values and default
`always-on-display-minutes`	How long the display is kept awake	Integer	Zero disables it; 1 through 30 sets a timeout in minutes; 31 or greater means always on. Default: `0`.
`brightness-gain`	The display brightness boost amount	Number	A decimal from 1.0 through 2.0; out-of-range values are clamped. Default: `1`.
`power-auto-saver`	Automatic Battery Saver	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`power-battery-refresh-rate`	Refresh Rate on Battery	Enumerated text	`sixty`, `thirty`. Default: `sixty`.
`power-max-refresh-rate`	Maximum Refresh Rate	Enumerated text	`auto`, `sixty`, `thirty`, `adaptive`. Default: `auto`.

Privacy

Key	What it configures	Value type	Allowed values and default
`auto-redact-enabled`	Redact Sensitive Text	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`geo-provider-type`	IP Geolocation	Enumerated text	`ipinfo`, `mmdb`, `dns`, `disabled`. Default: `ipinfo` in builds configured for that provider; otherwise `dns`.
`location-diary-auto-mode`	Location Diary Mode	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Prompt

Key	What it configures	Value type	Allowed values and default
`custom-username`	Username	Text	Any single-line username; leave empty to use the session username. Default: empty.
`prompt-add-newline`	Blank Line Before Prompt	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`show-git-in-prompt`	Show Git Status	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`starship-theme`	Prompt Theme	Enumerated text	`catppuccin`, `tokyoNight`, `pastelPowerline`, `gruvboxRainbow`, `dracula`, `nord`, `oneDark`, `solarizedDark`, `monokaiPro`, `kanagawaWave`, `rosePine`, `synthwave84`, `everforest`. Default: `catppuccin`.
`use-right-prompt`	Right Prompt	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`use-starship-prompt`	Starship-style Prompt	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`use-transient-prompt`	Transient Prompt	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Roam

Key	What it configures	Value type	Allowed values and default
`roam-default-predict-overwrite`	Overwrite Predictions	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`roam-default-prediction-mode`	Default Prediction Mode	Enumerated text	`always`, `adaptive`, `never`. Default: `adaptive`.
`roam-hole-punch-enabled`	Enable Hole-Punch	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`roam-mosh-alt-screen-enabled`	Use Alternate Screen	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`roam-multipath-tcp-enabled`	Multipath TCP	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`trzsz-default-transport-mode`	Default Transport	Enumerated text	`quic`, `kcp`, `auto`. Default: `kcp`.
`trzsz-default-udp-port-max`	The last port in the default trzsz UDP range	Integer	A UDP port from 1 through 65535; it must be at least the minimum port. Default: `61999`.
`trzsz-default-udp-port-min`	The first port in the default trzsz UDP range	Integer	A UDP port from 1 through 65535; it must not exceed the maximum port. Default: `61000`.
`trzsz-keep-pending-input`	Keep Input While Offline	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Screen Sharing

Key	What it configures	Value type	Allowed values and default
`screen-sharing-clipboard-sync-default`	Default Clipboard Sync	Enumerated text	`automatic`, `off`, `alwaysOn`. Default: `automatic`.
`screen-sharing-panning-default`	Default Panning Mode	Enumerated text	`edge`, `continuous`. Default: `edge`.

Selection

Key	What it configures	Value type	Allowed values and default
`copy-on-select`	Copy on Select	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`selection-appearance-mode`	Selection Style	Enumerated text	`rootshell`, `themeDefault`, `invertFgBg`, `custom`. Default: `rootshell`.
`selection-background`	The selection background color	Text	A six-digit RGB hex color such as `f5e0dc`. Default: `f5e0dc`.
`selection-foreground`	The selection foreground color	Text	A six-digit RGB hex color such as `1e1e2e`. Default: `1e1e2e`.
`use-native-selection-loupe`	Use Native Selection Loupe	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Session

Key	What it configures	Value type	Allowed values and default
`scrollback-persistence-enabled`	Persist Scrollback History	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`session-persistence-enabled`	Restore Sessions on Launch	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.

Shaders & Effects

Key	What it configures	Value type	Allowed values and default
`active-effect-id`	The selected background effect	Optional text	`aurora`, `solarGraph`, `fireflies`, `butterflies`, `jellyfish`, `photoBackground` or `videoBackground_<video-id>`; leave empty for no effect. Default: unset.
`background-effect-includes-pinned-sidebar`	Whether the background effect extends under the pinned sidebar	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`custom-shader-animation`	Shader Animation	Enumerated text	`false`, `true`, `always`. Default: `true`. `false` disables animation; `true` animates only while focused.

Sidebar

Key	What it configures	Value type	Allowed values and default
`tab-sidebar-auto-hide-on-select`	Auto-Hide Sidebar After Selection	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`tab-sidebar-large-controls`	Large Sidebar Controls	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. The default depends on the device class.
`tab-sidebar-pinned`	Pin Tab Sidebar	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`tab-sidebar-row-lines`	Sidebar Title Lines	Integer	A whole number from 1 through 3. Default: `1`.

Sounds

Key	What it configures	Value type	Allowed values and default
`bell-sound-preset`	The terminal bell sound	Enumerated text	`hapticOnly`, `classicBell`, `softChime`, `typewriterDing`, `digitalBeep`, `glassTap`, `mutedThud`, `none`. Default: `hapticOnly`.
`bell-sound-volume`	The terminal bell volume	Number	A decimal from 0.0 through 1.0. Default: `0.7`.
`notification-sound-preset`	The notification sound	Enumerated text	`systemDefault`, `crystalChime`, `gentlePing`, `warmTone`, `brightAlert`, `softMarimba`, `none`. Default: `systemDefault`.

Tabs

Key	What it configures	Value type	Allowed values and default
`compact-pill-tab-spacing`	Compact Tab Spacing	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`show-tab-scope-menu`	Show Group Menu	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`show-tab-shortcut-indicators`	Show Tab Shortcuts	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`tab-bar-animations-disabled`	Disable Tab Animations	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`tab-bar-hidden`	Whether the top tab bar is hidden	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`tab-expose-shows-captions`	Tab Exposé Captions	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`top-tab-agent-detail-mode`	Agent Detail in Tabs	Text	Any single-line text is accepted, but `off` is the only currently defined value; this key is reserved for compatibility. Default: `off`.
`top-tab-style`	Tab Style	Enumerated text	`pills`, `integrated`, `ledger`, `trough`. Default: `pills`.

Terminal

Key	What it configures	Value type	Allowed values and default
`local-shell-command`	The command used to start a local shell	Text	Any single-line shell command; leave empty to use the default login shell. Default: empty.
`terminal-type-local`	Terminal Type (Local)	Text	`xterm-256color`, `xterm-ghostty`, `xterm`, `vt100` or a custom 1–64 character value containing only ASCII letters, digits, period, underscore, plus, or hyphen. Default: `xterm-ghostty` on macOS and `xterm-256color` on iOS.
`terminal-type-remote`	Terminal Type (Remote)	Text	`xterm-256color`, `xterm-ghostty`, `xterm`, `vt100` or a custom 1–64 character value containing only ASCII letters, digits, period, underscore, plus, or hyphen. Default: `xterm-256color`.
`window-padding-x`	Horizontal terminal padding	Optional integer	A whole number from 0 through 32; leave empty for automatic padding. Default: automatic.
`window-padding-y`	Vertical terminal padding	Optional integer	A whole number from 0 through 32; leave empty for automatic padding. Default: automatic.

Theme

Key	What it configures	Value type	Allowed values and default
`appearance-mode`	Appearance	Enumerated text	`automatic`, `light`, `dark`. Default: `automatic`.
`day-night-theme-day-theme`	Day Theme	Text	The exact name of an installed or bundled theme. Default: `Solarized Light`.
`day-night-theme-enabled`	Match System Theme	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`day-night-theme-night-theme`	Night Theme	Text	The exact name of an installed or bundled theme. Default: `Catppuccin Mocha`.
`favorite-theme-ids`	The favorite theme list; repeat the key for multiple themes	Repeatable text	Any installed or bundled theme ID. Repeat the key once per item; an empty final entry clears the list. Default: empty list.
`selected-app-icon-variant`	App Icon	Enumerated text	`(empty)` for the default icon, or `AppIconBlack`, `AppIconCRT`, `AppIconNoBorder`, `AppIconUnderscore`, `AppIconSixColors`, `AppIconSixColorsDark`, `AppIconOrig`, `AppIconRadicalSolarizedDark`, `AppIconRadicalSolarizedLight`, `AppIconRadicalDracula`, `AppIconRadicalNord`, `AppIconRadicalGruvboxDark`, `AppIconRadicalTokyoNight`, `AppIconRadicalCatppuccin`, `AppIconRadicalBases`, `AppIconRadicalMonoLight`, `AppIconRadicalMonokai`, `AppIconRadicalMonoDark`, `AppIconRadicalRosePine`. Default: empty.
`themed-ui`	Theme-Aware UI	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`theme`	Theme	Text	The exact name of an installed or bundled theme. Legacy comma-separated day/night pairs are not accepted here; use the separate day and night keys. Default: `Catppuccin Mocha`.

Transparency

Key	What it configures	Value type	Allowed values and default
`background-blur`	Blur Radius	Number	Blur radius in points; Settings uses 0 through 80. Boolean aliases are also accepted: `true` means 30 and `false` means 0. Default: `30`.
`background-opacity`	Background Opacity	Number	A decimal from 0.0 through 1.0. Default: `0.92`.
`blur-enabled`	Background Blur	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`blur-style`	Blur Style	Enumerated text	`standard`, `glassRegular`, `glassClear`. Default: `standard`. The glass styles require a supported OS version.
`pinned-sidebar-transparency-enabled`	Transparent Pinned Sidebar	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`tab-sidebar-translucent`	Translucent Tab Sidebar	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.

Visor

Key	What it configures	Value type	Allowed values and default
`visor-animation-duration-ms`	Visor Animation Duration	Integer	A nonnegative whole number of milliseconds. Default: `200`.
`visor-autohide`	Visor Auto-Hide	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.
`visor-enabled`	Enable Visor	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`visor-hotkey-key-code`	The visor global-hotkey key code	Integer	A macOS hardware key code; use an exported value when possible. Default: `-1`.
`visor-hotkey-modifiers`	The visor global-hotkey modifier mask	Integer	A macOS modifier bit mask; use an exported value when possible. Default: `0`.
`visor-position`	Visor Edge	Enumerated text	`top`, `bottom`, `left`, `right`, `center`. Default: `top`.
`visor-primary-size`	The visor size along its slide axis	Text	A number followed by `%` or `px`, such as `30%` or `480px`. Default: `30%`.
`visor-screen`	Visor Screen	Enumerated text	`main`, `mouse`, `macosMenuBar`. Default: `main`.
`visor-secondary-size`	The visor size along its cross axis	Text	A number followed by `%` or `px`; leave empty to fill the secondary axis. Default: empty.
`visor-space-behavior`	Visor Space Behavior	Enumerated text	`move`, `remain`. Default: `move`.
`visor-use-event-tap`	Visor Event Tap	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.

Window

Key	What it configures	Value type	Allowed values and default
`extend-under-home-indicator`	Extend Under Home Indicator	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`full-screen-mode-enabled`	Full Screen Mode	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`hide-window-title-bar`	Hide Title Bar	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `false`.
`split-focus-border-color`	Split Border Color	Enumerated text	`accent`, `gray`, `custom`. Default: `accent`.
`split-focus-border-custom-color`	The custom split-focus border color	Text	A six-digit RGB hex color such as `007AFF`. Default: `007AFF`.
`split-focus-border-style`	Split Focus Border	Enumerated text	`none`, `subtle`, `standard`, `bold`. Default: `standard`.
`tabs-in-titlebar-enabled`	Tabs in Title Bar	Boolean	`true` or `false`; `yes`, `no`, `on`, `off`, `1`, `0` are also accepted. Default: `true`.

Troubleshooting

Open Config File settings and check Status, Last Loaded, and Diagnostics.
Use Reload Now after editing if a change has not appeared. macOS also watches the active file for changes.
If a setting will not follow iCloud, check Pinned Settings for an individual pin, a group pin, or a config-file entry.
If sync was paused after an Apple Account change, turn Sync Settings on again and complete the merge choice.
Disabling iCloud Sync preserves local values; it only stops future synchronization.

Back to Support