Tuna

Tuna CLI

Tuna includes a tuna command for using Tuna from your terminal.

Use it to pipe terminal output into Tuna, stage or run Tuna commands, or open Tuna already browsing a path. The CLI talks to the running Tuna app; if Tuna is not open, the helper launches it in the background and waits for it to become ready.

Install

Open Tuna Settings -> General -> Command Line, turn on Enable CLI, then click Install CLI if the helper is missing or stale.

Tuna installs the bundled helper to:

~/.local/bin/tuna

Make sure ~/.local/bin is on your shell PATH. If Enable CLI is off, the tuna command will refuse to connect. When Enable CLI is on, Tuna repairs the helper on launch if it is missing or stale.

export PATH="$HOME/.local/bin:$PATH"

Check Installation And Enablement

The Enable CLI toggle in General -> Command Line shows whether access is enabled. It is off by default. The helper being installed does not mean access is enabled.

These terminal checks do not change settings or execute a Tuna command:

command -v tuna
test -x "$HOME/.local/bin/tuna" && printf 'Helper installed\n'
defaults read com.brnbw.Tuna CLIEnabled

The preference is local, not a config.toml key. 1 means enabled; 0 or a missing key means off by default. There is no tuna status subcommand; running tuna without arguments prints usage. To test the connection without executing an action, run tuna stage 'Tuna CLI check'. This opens Tuna and replaces the staged command. It may launch the app if it is not already running.

For help configuring Tuna with a coding assistant, install the Tuna agent skill.

Pick from stdin

Pipe newline-separated values into Tuna and pick one with the normal Tuna UI:

printf "Alpha\nBeta\nGamma\n" | tuna pick -

The selected value is printed to stdout. Cancelling exits non-zero and prints nothing.

Use browse mode when the input contains file or folder names relative to the current directory:

ls | tuna pick --browse -
ls | tuna pick -b -

Limit very large inputs:

ps aux | tuna pick --limit 2000 -

Use --limit 0 for no result cap.

Stage a command

stage fills Tuna’s subject/action/target panes without running the command:

tuna stage "buy milk"
tuna stage ~/Downloads
tuna stage ~/Downloads tuna.common-actions/open
tuna stage <catalog-id/item-id> <catalog-id/action-id> [target]

Rules:

  • subject is required
  • action is optional
  • target is only allowed when action is present
  • subject and target can be enabled catalog-id/item-id references, existing paths, raw URLs, or plain text
  • action must be a canonical catalog-id/action-id reference, not a display name such as Open

Run a command

run executes a Tuna command immediately:

tuna run ~/Downloads tuna.common-actions/open
tuna run <subject> <catalog-id/action-id> [target]

Use --silent or -s to run without showing Tuna when possible:

tuna run --silent ~/Downloads tuna.common-actions/open

Rules:

  • subject and action are required
  • target is optional when the action accepts one
  • subject and target can be enabled catalog-id/item-id references, existing paths, raw URLs, or plain text
  • action must be a canonical catalog-id/action-id reference, not a display name such as Open
  • canonical Tuna identifiers resolve enabled catalog items even when they are excluded from global search in Sources, for both stage and run

Unlike saved commands and tuna:// command URLs, CLI arguments do not interpret text:, path:, url:, color:, or alias: as Tuna typed references: they are treated as URL schemes. Pass the literal text, existing path, or raw URL instead, or use a command URL when you need a typed reference. An unresolved catalog item reference falls back to plain text; staging a command successfully is not proof that its item resolved. Inspect the staged subject before running it.

For example, launch a Chrome profile without adding profiles to global search:

tuna run --silent 'chrome.profiles/6:chrome7:Default' tuna.common-actions/run

Reload config

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

tuna config reload

The same action is available as a URL:

open "tuna://config/reload"

Browse from the terminal

Open Tuna already browsing the current directory:

tuna browse

Or browse a specific path or browsable Tuna item:

tuna browse ~/Projects
tuna browse <catalog-id/item-id>

Notes

  • The CLI is local-only and communicates with the Tuna app through an app-owned socket.
  • The Tuna app owns the UI, command execution, and selection state.
  • If the helper cannot connect, it launches Tuna and waits up to 30 seconds.