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/extensions"
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>
tuna://stage/<subject>/<action>
tuna://stage/<subject>/<action>/<target>

Example:

open "tuna://stage/com.apple.TextEdit/Open"

Run commands

Run executes a command immediately:

tuna://run/<subject>/<action>
tuna://run/<subject>/<action>/<target>

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

open "tuna://run/com.apple.TextEdit/Open?show=false"

Subject, action, and target path components are Tuna item identifiers. Percent-encode spaces, slashes, and other special characters.

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