Using gooseneck

CLI reference

Every TUI action is a goose command. Fuzzy names work everywhere, and every listing takes --json.

goose and gooseneck-player are the same program. With no arguments in a terminal it opens the TUI; with a command it does that one thing and exits. Artist, album and track arguments are fuzzy: a fragment (fried), a full title, or a number from a previous listing all work.

#Browse

goose search fried                  # fuzzy artist search (--tag chasidish, -n 5)
goose artist "8th Day"              # albums, singles, top songs, related
goose album "8th Day" lucky         # tracklist (title, fragment, or number)
goose artists --tag israeli         # every artist, one per line when piped
goose tags                          # tags with artist counts

#Play

goose play "8th Day" lucky          # play an album
goose play "8th Day" lucky 3        # …starting from track 3
goose play fried                    # everything by an artist, in order
goose play fried --shuffle          # …shuffled
goose play "8th Day" --top          # just their top songs
goose play https://youtu.be/<id>    # any single video

By default the queue is replaced. --add (-a) appends and --next (-N) inserts after the current track. p is an alias for play.

#Control

Command	Does
`goose now`	What's playing. `--watch` refreshes every second; `--format` for status bars. Aliases `status`, `np`.
`goose pause` · `resume` · `toggle`	Pause control
`goose next` · `prev`	Skip (prev restarts the track if you're more than 3s in)
`goose seek +30` · `seek 1:15`	Relative or absolute seek
`goose vol` · `vol 60` · `vol -10`	Show or change volume (0–130)
`goose repeat all\|one\|off`	Repeat mode
`goose shuffle`	Shuffle the current queue
`goose queue`	Show the queue; `queue jump 4`, `queue rm 2`, `queue clear`
`goose stop`	Stop and clear the queue
`goose quit-player`	Shut down the background player

#Radio, downloads, history

goose radio "8th Day"               # endless radio (see Radio)
goose radio stop
goose download "8th Day" lucky      # save for offline (see Downloads)
goose downloads
goose history                       # recently played (-n 50)
goose top                           # most played artists
goose scrobbles top artist -s month # from your listening log

#Housekeeping

goose doctor                        # check dependencies and connectivity
goose catalog update                # refresh the catalog(s)
goose cache                         # cache info; cache clear, cache warm
goose config set theme tokyonight   # config get/set/path/edit
goose version

#Recipes

#Status bar module

Empty output when nothing is playing, so it hides itself in waybar, polybar, tmux and friends.

goose now --format '{title} — {artist}'
# fields: {title} {artist} {album} {pos} {duration} {state} {volume} {index} {count}

#Pick an artist with fzf

goose artists | fzf | xargs -I{} goose play {}

#Media keys / window-manager bindings

goose toggle     # play/pause
goose next
goose prev

With mpv-mpris installed the player also shows up in playerctl and your desktop's media controls automatically.

#JSON

# latest album of an artist
goose artist "Avraham Fried" --json | jq -r '.albums[0].title'
# what's playing, as JSON
goose now --json

#Global flags

Flag	Does
`--json`	Machine-readable output for any listing
`--no-color`	Plain output (also `NO_COLOR=1`)
`-h`, `--help`	Help for any command, e.g. `goose play --help`

Edit these docs on GitHub