Configuration

Tuna keeps the configuration you may want to sync or edit in a TOML file named config.toml. You can manage Tuna entirely through Settings, but the file is useful for keeping the same setup on multiple Macs, putting your preferences in a dotfiles repository, or making a precise change by hand.

Where The File Lives

By default, Tuna uses:

~/Library/Application Support/Tuna/config.toml

Open Settings -> General -> Configuration to reveal the file, reload it, or choose a custom folder. A custom folder is useful for iCloud Drive, Dropbox, Syncthing, or a dotfiles checkout. Tuna always names the file config.toml inside the selected folder.

Tuna does not create the file on an untouched installation. The configuration is sparse: it only contains values that differ from Tuna’s built-in defaults, plus custom data such as hotkeys and Smart Links. Returning a setting to its default removes that override. If every override is removed, Tuna removes the empty file too.

How Saving And Reloading Work

Tuna loads config.toml at launch and writes changes made in Settings back to it automatically. Writes are atomic and slightly delayed so a series of quick changes produces one update.

When editing the file yourself:

1. Make a backup or commit your current file.
2. Save your changes.
3. Choose Reload from Disk in Settings, run tuna config reload, or open tuna://config/reload.

Tuna validates the whole file before applying it. Unknown sections, unknown fields, invalid built-in values, duplicate IDs, and malformed item or action references make the reload fail rather than silently applying a partial configuration. Tuna leaves an unreadable file untouched and shows the error in Settings -> Logs.

If the file changes outside Tuna while Tuna also has unsaved changes, Tuna reports a conflict. You can reload the file to keep the external version or explicitly overwrite it with Tuna’s current state. Tuna will not silently choose one version.

A Small Example

You do not need to copy a complete template. Include only the values you want to override:

[settings]
screenPreference = "activeWindow"
appPresentationMode = "both"
backspaceBehavior = "deleteCharacters"
resultListNavigationBindings = "vimStyle"
typingTimeoutDuration = 1.5

The names and string values are case-sensitive.

Built-in Setting Values

All keys below live under [settings]. Booleans use true or false, strings use quotes, and numbers do not. The default shown is what Tuna uses when the key is absent.

Window And Results

Key	Default	Accepted values
themeIdentifier	Default theme	A theme’s identifier. The default theme is omitted from the file.
resultsRevealDelay	2.0	Seconds as a number.
showResultsImmediatelyOnActivation	false	true, false
mainWindowAnimationsEnabled	true	true, false
screenPreference	"mouse"	"mouse", "primary", "activeWindow"
appPresentationMode	"statusBar"	"statusBar", "dock", "both", "never"

Search And Keyboard Behavior

Key	Default	Accepted values
typingTimeoutDuration	2.5	Seconds from 0.2 through 3.0; 3.0 means Off. Lower values are raised to 0.2.
backspaceBehavior	"clearSearch"	"clearSearch", "deleteCharacters"
spacebarBehavior	"normal"	"normal", "switchToTextMode", "jumpToTargetPane"
resultListNavigationBindings	"arrowKeysOnly"	"arrowKeysOnly", "macOSStandard", "vimStyle"
switchToTextModeWhenNoResults	false	true, false
holdToExecuteEnabled	false	true, false
pureStringRankingEnabled	false	true, false
preferStringPasteboardContent	false	true, false

Activation

The four trigger-type keys accept the same values:

• fuzzyModeTriggerType
• textModeTriggerType
• comboModeTriggerType
• talkModeTriggerType

Their default is "shortcut". Accepted values are "disabled", "shortcut", "doublePress", and "modifier".

The four double-press keys also share one value set:

• activationDoublePressTrigger
• textModeDoublePressTrigger
• comboModeDoublePressTrigger
• talkModeDoublePressTrigger

Their default is "disabled". Accepted values are "disabled", "leftCommand", "rightCommand", "leftOption", and "rightOption".

comboModeModifierTrigger and talkModeModifierTrigger default to "disabled". They accept "disabled", "rightCommand", "leftCommand", "rightOption", "leftOption", "rightCommandOption", "leftCommandOption", and "hyper".

These fields choose how a mode is triggered; the actual app hotkey chords are stored in the [hotkeys] section described below.

Built-in Hyper

Key	Default	Accepted values
physicalHyperKeySource	"off"	"off", "capsLock", "rightOption", "rightCommand"
physicalHyperKeyQuickPressBehavior	"doesNothing"	"doesNothing", "togglesCapsLock", "triggersEscape"
shortcutDisplayUsesHyperSymbol	true	true, false

The quick-press behavior matters when a physical key is being used as Hyper. Right Option and Right Command preserve their normal quick press; Caps Lock can toggle Caps Lock or act as Escape.

Clipboard And Shelf

Key	Default	Accepted values
clipboardHistoryEnabled	true	true, false
clipboardHistoryRetention	"oneMonth"	"oneDay", "sevenDays", "oneMonth", "threeMonths", "sixMonths", "oneYear", "unlimited"
clipboardIgnoredBundleIdentifiers	Password-manager defaults	An array of application bundle identifier strings. Supplying it replaces the entire list.
showTasksIndicatorWhenHidden	true	true, false
shelfWindowAlwaysOnTop	true	true, false
shelfAutoCloseWhenTasksComplete	false	true, false
shelfCatalogEnabled	true	true, false

The built-in clipboard ignore list contains:

clipboardIgnoredBundleIdentifiers = [
  "com.1password.1password",
  "com.agilebits.onepassword7",
  "com.apple.Passwords",
  "com.apple.keychainaccess",
  "com.bitwarden.desktop",
  "com.dashlane.Dashlane",
  "com.keepersecurity.KeeperPasswordManager",
  "com.nordpass.NordPass",
]

Clipboard retention beyond one month requires Tuna Pro.

Catalogs And Diagnostics

Key	Default	Accepted values
advancedCatalogsEnabled	true	true, false
textActionsFileExtension	"txt"	A file extension without the leading dot.
proxyDiagnosticsLoggingEnabled	false	true, false
devicesDiagnosticsLoggingEnabled	false	true, false

Older files may contain catalogPeriodicRescanEnabled and catalogPeriodicRescanIntervalMinutes. Tuna accepts these keys for compatibility but ignores them; catalogs now update at startup, on demand, or in response to filesystem changes.

Combo Mode

Key	Default	Accepted values
comboModeCheatsheetBehavior	"delay"	"never", "delay", "always"
comboModeCheatsheetDelayMS	2000	Milliseconds as a non-negative integer.
comboModeCheatsheetExpandGroups	false	true, false
comboModeCheatsheetShowIcons	true	true, false
comboModeCheatsheetShowDetails	true	true, false
comboModeModifierConfiguration	"controlGroupOptionSticky"	"controlGroupOptionSticky", "optionGroupControlSticky"
comboModeKeyboardLayoutBehavior	"respectCurrentLayout"	"respectCurrentLayout", "forceUS"
comboModeBackspaceBehavior	"resetToRoot"	"resetToRoot", "stepBack"
comboModeThemeStyle	"inherit"	"inherit", "breadcrumb", "cheatsheet", "none"

Talk Mode Presentation

Key	Default	Accepted values
dictationActivationMode	"pushToTalk"	"pushToTalk", "toggle"
dictationPresentationStyle	"inherit"	"inherit", "mini", "hidden"
dictationWindowPosition	"center"	"center", "topLeft", "topCenter", "topRight", "bottomLeft", "bottomCenter", "bottomRight"

Other Configuration Sections

Tuna writes these top-level sections when they contain non-default or user-created data:

Section	What it contains
[catalogs]	Per-catalog browse sort, global-search scope, and search-priority overrides. Priorities are -2, -1, 1, or 2; 0 means no override and is omitted.
[catalogConfiguration]	Folder depth overrides, custom folders, script directories, and custom items. Custom item kinds are "url", "path", and "text"; custom-folder entry types are "directory" and "file"; filters are "folders" and "extensions". Paths may use ~.
[Catalogsettings](/docs/catalogsettings)	String values declared by built-in or installed extensions. Available keys and values depend on the extension. A present list replaces all stored extension settings; omitting the section leaves them untouched.
[hotkeys]	Tuna’s five app hotkeys—activate, Text Mode, Combo Mode, stage Finder selection, and dictation—plus custom command hotkeys.
[comboMode]	The complete non-default Combo Mode binding tree.
[smartLinks]	The complete Smart Links list when it differs from the built-in list.
[actionPreferences]	Sparse action ordering and default-action overrides.

These structures use canonical catalog references. The easiest and safest way to author them is to make the change in Tuna, then inspect the TOML Tuna writes. Smart Links are identified by their unique name — commands refer to them as tuna.smart-links/<name> — and Combo bindings carry no persisted identity at all. Custom hotkeys have a UUID id, which you may omit when authoring by hand: Tuna assigns one on load and writes it back on the next save.

Smart Links Objects

Each [[smartLinks.entries]] object has four required fields:

Field	Meaning
name	The title shown in Tuna, and the entry’s identity: saved commands and hotkeys refer to tuna.smart-links/<name>. Names must be unique (case-insensitive).
template	URL template. Usually contains {{input}} or {{clipboard}}.
requiresInput	Whether Tuna requires a target value before opening the link.
enabled	Whether the entry is available in the Smart Links catalog.

[[smartLinks.entries]]
name = "GitHub Search"
template = "https://github.com/search?q={{input}}"
requiresInput = true
enabled = true

[[smartLinks.entries]]
name = "Tuna Website"
template = "https://tunaformac.com"
requiresInput = false
enabled = true

Renaming a Smart Link in Tuna’s Settings rewrites every command that refers to it. Renaming one by editing this file does not — commands referring to the old name stop resolving until you update them.

The entries are a complete ordered list, not a patch. To deliberately clear them, use:

[smartLinks]
entries = []

Names and templates must not be empty, and names must be unique (case-insensitive). See Smart Links for template placeholders and filters.

Combo Mode Binding Objects

[comboMode] contains one required bindings array. Every binding has an optional single-character key, an optional label, an optional iconPath, and a destination object. Destination types are "url", "group", "command", and "route".

This example contains a website, a nested group, and a Tuna search route:

[comboMode]

[[comboMode.bindings]]
key = "w"
label = "Tuna Website"

[comboMode.bindings.destination]
type = "url"
url = "https://tunaformac.com"

[[comboMode.bindings]]
key = "g"
label = "Go"

[comboMode.bindings.destination]
type = "group"

[[comboMode.bindings.destination.bindings]]
key = "s"
label = "Search Tuna"

[comboMode.bindings.destination.bindings.destination]
type = "route"

[comboMode.bindings.destination.bindings.destination.route]
type = "search"
query = "Tuna"

A command destination embeds the same saved-command object used by a custom hotkey:

[comboMode]

[[comboMode.bindings]]
key = "e"
label = "Open Example"

[comboMode.bindings.destination]
type = "command"

[comboMode.bindings.destination.command]
type = "savedCommand"
subjectIdentifiers = ["url:https://example.com"]
actionIdentifier = "tuna.common-actions/open-url"
behavior = "run"
presentation = "automatic"

Saved-command behavior is "run" or "stage"; presentation is "automatic", "show", or "hidden". A command may also have a targetIdentifier. Subject and target values use canonical item references, while the action uses catalog-id/action-id. See URL Schemes for the reference grammar.

Route objects can open Tuna search, Text Mode, Combo Mode, Talk Mode, Settings, configuration reload, or extension-development actions. Let Tuna’s Combo Mode editor generate these objects so all fields match the selected route.

The bindings array is a complete tree. bindings = [] deliberately clears Combo Mode; removing the whole section leaves the currently stored configuration alone.

Hotkey Objects

[hotkeys] has an optional app object and a required custom array. App shortcuts are named activate, textMode, comboMode, stageFinderSelection, and dictation. A custom hotkey’s id is optional when authoring by hand; Tuna adopts the stored hotkey with the same command or assigns a fresh identity, and writes it back on the next save.

[hotkeys]

[[hotkeys.custom]]

[hotkeys.custom.shortcut]
carbonKeyCode = 18
carbonModifiers = 6400

[hotkeys.custom.command]
type = "savedCommand"
subjectIdentifiers = ["text:hello"]
actionIdentifier = "tuna.common-actions/run-text-as-shell-command"
behavior = "run"
presentation = "hidden"

[hotkeys.app]
activate = { carbonKeyCode = 49, carbonModifiers = 2304 }
textMode = { carbonKeyCode = 17, carbonModifiers = 2304 }

carbonKeyCode and carbonModifiers are the macOS key representation used by Tuna’s shortcut library. They are intentionally low-level: record shortcuts in Settings -> Hotkeys, then copy or debug the generated values instead of calculating them by hand. A missing shortcut on a custom hotkey means the command exists but has no assigned chord.

The custom array is a complete replacement. Including [hotkeys] with custom = [] removes all custom hotkeys. If the section is present but [hotkeys.app] or one of its five fields is absent, that app shortcut is cleared on reload. Removing the entire [hotkeys] section leaves current hotkeys alone.

Every custom hotkey UUID must be unique. Its command follows the saved-command shape described in the Combo Mode section above. A staged command cannot use presentation = "hidden" because staging requires Tuna’s interface.

Action Preference Objects

Action preferences are sparse overrides layered on top of Tuna and extension defaults. The section contains three required arrays:

[actionPreferences]

[[actionPreferences.typeOrderOverrides]]
typeID = "com.tuna.type.url"
actions = [
  { catalogIdentifier = "tuna.common-actions", actionID = "open-url" },
  { catalogIdentifier = "tuna.common-actions", actionID = "copy-to-clipboard" },
]

[[actionPreferences.itemDefaultOverrides]]
scopeKind = "item"
scopeIdentifier = "tuna.smart-links/GitHub Search"
action = { catalogIdentifier = "tuna.smart-links.actions", actionID = "open-smart-link" }

[[actionPreferences.itemDefaultOverrides]]
scopeKind = "type"
scopeIdentifier = "com.tuna.type.text-snippet"
action = { catalogIdentifier = "tuna.common-actions", actionID = "copy-to-clipboard" }

[[actionPreferences.applicationOrderOverrides]]
bundleIdentifier = "com.apple.Safari"
actions = [
  { catalogIdentifier = "tuna.common-actions", actionID = "open" },
  { catalogIdentifier = "tuna.common-actions", actionID = "reveal" },
]

• typeOrderOverrides replaces the action order for one type ID.
• itemDefaultOverrides chooses one default action for either a canonical item reference or a type ID. scopeKind is "item" or "type" and determines how scopeIdentifier is parsed.
• applicationOrderOverrides replaces the action order used for one application bundle identifier.

Each scope, type, and normalized application bundle identifier may appear only once. An action may appear only once within an order. References to an unavailable extension are retained so the preference starts working again if that extension returns. Resetting an order or default in Settings removes its object and reveals the current built-in or extension default.

All three arrays describe the complete set of overrides. To reset all action preferences through the file, keep the section and set all three arrays to []. Removing the section leaves current preferences alone.

Catalog enablement is intentionally not stored in config.toml. Installed extensions and available catalogs can differ from Mac to Mac, so Tuna resolves their current availability locally. Likewise, built-in action rankings are resolved live; only your overrides are saved.

For the command references used by custom hotkeys, Combo Mode, and action preferences, see URL Schemes. For the corresponding UI, see Hotkeys and Activation, Combo Mode, and Smart Links.

Syncing Between Macs

Choose the same custom config folder on each Mac, or manage config.toml with your normal sync tool. Tuna keeps paths portable where it can by writing locations inside your home directory with ~.

Some references can still be machine-specific: an application or extension may not exist on every Mac, a custom path may point to local content, and a hotkey may conflict with another system setup. Tuna retains valid references to temporarily unavailable extensions so they work again when the extension returns.

Before resolving a sync conflict, quit Tuna on the other Mac or reload both copies so neither has pending local changes. Treat config.toml as one document: Tuna validates and applies it as a whole.