Skip to content
spotuify

spotuify search

When to use it

Section titled “When to use it”

Search Spotify’s catalog (or your local cache)

Examples

Section titled “Examples”
Terminal window
spotuify search "luther vandross" --type track
spotuify search "quiet storm" --source local --format jsonl
spotuify search "imagine dragons" --play --index 1

Help

Section titled “Help”
Search Spotify's catalog (or your local cache)


Usage: spotuify search [OPTIONS] <QUERY>


Arguments:
  <QUERY>
          Search query


Options:
      --log-format <LOG_FORMAT>
          Phase 13 (P13-A) - pick the daemon log format for this run. Also honoured via `SPOTUIFY_LOG_FORMAT`


          [possible values: text, json]


      --type <KIND>
          Media type to search


          [default: all]
          [possible values: all, track, episode, show, album, artist, playlist]


      --no-daemon-start
          Phase 13 (P13-H) - if set, the CLI never auto-starts the daemon. Errors with a clear hint when the daemon socket is missing


      --source <SOURCE>
          Where to search. `spotify` (default) queries the Web API for catalog discovery. `local` queries only the local Tantivy index (offline / library lookup). `hybrid` returns local cached hits immediately and refreshes Spotify in the background


          [default: spotify]
          [possible values: local, spotify, hybrid]


      --limit <LIMIT>
          Maximum results to return (Spotify caps per-type at 10 empirically)


          [default: 50]


  -o, --set <key.path=value>
          Phase 13 (P13-H) - one-shot TOML override (e.g. `-o player.bitrate=160`). Repeatable. Applies for this invocation only; the config file on disk is unchanged


      --pages <PAGES>
          Pages of 10 to request per media type. `1` = one-shot (current behavior, up to 60 items). `2`-`3` aggregate pages via `SearchStream` before printing; `3` matches the TUI fanout (up to 180 items) and is the maximum - higher values clamp


          [default: 1]


      --play
          Play one result instead of printing results


      --index <INDEX>
          1-based search result index for --play


          [default: 1]


      --sort <SORT>
          Sort results (relevance keeps Spotify's order)


          Possible values:
          - relevance
          - name
          - duration
          - artist
          - date:      Newest release first (episodes/shows)


          [default: relevance]


      --format <FORMAT>
          Output format


          [default: table]
          [possible values: table, json, jsonl, csv, ids]


  -h, --help
          Print help (see a summary with '-h')