URL Schemes

Tuna supports tuna:// links for opening modes, staging commands, running commands, and reloading synced config.

Use them from scripts with macOS open:

open "tuna://search?q=calendar"

Open modes

tuna://search?q=<query>
tuna://text?q=<text>
tuna://combo
tuna://talk
tuna://dictation

Examples:

open "tuna://search?q=slack"
open "tuna://text?q=Hello%20world"
open "tuna://combo"
open "tuna://talk"

search and text accept an optional q query parameter. talk and dictation are aliases for Talk Mode.

Open Settings

tuna://settings
tuna://settings/<pane>

Common panes:

open "tuna://settings/general"
open "tuna://settings/hotkeys"
open "tuna://settings/sources"
open "tuna://settings/extension-store"
open "tuna://settings/action-defaults"
open "tuna://settings/fuzzy-mode"
open "tuna://settings/text-mode"
open "tuna://settings/dictation"
open "tuna://settings/combo-mode-settings"
open "tuna://settings/combo-mode-editor"

Stage commands

Stage fills Tuna’s command panes without running the command:

tuna://stage?subject=<reference>[&action=<reference>][&target=<reference>]

Example:

open "tuna://stage?subject=path:/Applications/TextEdit.app&action=tuna.common-actions/open"

Run commands

Run executes a command immediately:

tuna://run?subject=<reference>&action=<reference>[&target=<reference>][&show=true|false]

By default Tuna shows the interface when needed. Add show=false to request headless execution:

open "tuna://run?subject=path:/Applications/TextEdit.app&action=tuna.common-actions/open&show=false"

References use catalog-id/item-id, path:, url:, text:, color:, or alias: forms. Actions always use their action catalog and action ID. Percent-encode references when constructing a URL. Older path-segment Run and Stage links remain compatibility-only; Tuna generates the query form.

For safety, external tuna://run links that can execute shell commands are blocked unless you enable Settings -> General -> Allow shell commands from tuna:// links.

Reload config

Reload config.toml from disk after changing synced or dotfile-managed settings:

open "tuna://config/reload"

The CLI equivalent is:

tuna config reload