Rocksky CLI

🎧 The official command-line interface for Rocksky — a modern, decentralized music tracking and discovery platform built on AT Protocol.

📚 View Full Documentation

Features

• Interactive TUI — a full terminal UI to browse scrobbles, stream your uploaded music, and manage playlists (just run rocksky)
• Built-in player — gapless playback with crossfade, a 10-band equalizer, bass/treble, and ReplayGain (powered by the Rockbox engine)
• Upload audio files to your private library with live progress
• Playlists — create, edit, and play playlists via the Navidrome/Subsonic-compatible API
• Favorites — like/unlike tracks and browse your starred songs
• Queue management, fuzzy search, disk caching, and MPRIS (media keys) on Linux
• MPD server — control playback and browse your library from any MPD client (ncmpcpp, rmpc, mpc, MALP…)
• Authenticate with your Rocksky account using OAuth
• View your currently playing track, recent scrobbles, and stats
• Manually scrobble tracks
• Useful developer tools for integrating Rocksky into your workflows
• MCP Server

Table of Contents

• Documentation
• Installation
• Run in development
• Usage
• Interactive TUI
  • Tabs
  • Keyboard shortcuts
• MPD Server
• Available Commands
• Rocksky MCP Server Tools
  • whoami
  • nowplaying
  • scrobbles
  • search
  • stats
  • artists
  • albums
  • tracks

Documentation

For comprehensive guides, API references, and tutorials, visit the official documentation at docs.rocksky.app.

Installation

npm install -g @rocksky/cli

You can also use the CLI without installing it globally by running npx:

npx @rocksky/cli --help

Run in development

To run the CLI in development mode, install the dependencies:

bun install

Then, run the CLI with:

bun run dev --help

Usage

rocksky <command> [options]

Interactive TUI

Running rocksky with no arguments (or rocksky tui) launches a full-screen terminal UI.

Tabs

• Global Scrobbles — a live feed of what everyone is playing (auto-refreshes); press Enter for scrobble details.
• My Music — browse your uploaded library by Tracks / Albums / Artists / Favorites, with drill-down and infinite scroll. Stream tracks with gapless playback + crossfade.
• Profile — your stats (scrobbles, artists, albums, tracks, loved) plus recent scrobbles and top tracks/artists/albums. Open your Bluesky (b) or PDSLS (d) profile.
• Playlists — create, delete, play, and edit playlists via the Navidrome (Subsonic-compatible) API.

Keyboard shortcuts

| Key | Action | | ------------------------- | --------------------------------------------------------------------- | | 1–4, Tab | Switch tabs | | ↑/↓ | Move selection · ←/→ switch My Music sub-tab | | Enter | Play / open · Space play/pause · n/p next/prev | | +/− | Volume · s shuffle · r/o/0 repeat all/one/off | | a · N/L · i · P | Play album · play next/last · insert-mode menu · play only this track | | f · ; | Like / unlike · add track to a playlist | | / · Q · e | Search · queue · equalizer & sound | | C · R · A · ? | Track cache · refresh feeds · sign in/out · help | | q | Quit |

Playback preferences (volume, EQ, crossfade, ReplayGain) are saved to ~/.rocksky/settings.toml, and the current queue/position is restored on restart.

Audio output

By default audio plays on your system's default device. You can route the raw PCM stream elsewhere with the output setting, so another process (or another machine) does the actual playback:

output = ""                     # default audio device (cpal)
# output = "stdout"             # raw S16LE stereo PCM on stdout (or "-")
# output = "fifo:/tmp/rocksky"  # write to a named pipe
# output = "unix:/tmp/rk.sock"  # listen on a Unix socket (blocks until a client connects)
# output = "unix-connect:/tmp/rk.sock"
# output = "tcp:0.0.0.0:9000"   # listen on TCP (blocks until a client connects)
# output = "tcp-connect:host:9000"

Both rocksky tui and rocksky mpd accept -o, --output <spec> to override the persisted value for a single run (without writing it back to settings.toml):

# headless daemon: pipe raw PCM straight into a player
rocksky mpd --output stdout | ffplay -f s16le -ar 44100 -ac 2 -

# TUI: use a fifo/socket, since the TUI itself renders to stdout
rocksky tui --output unix:/tmp/rocksky.sock
ffplay -f s16le -ar 44100 -ac 2 unix:///tmp/rocksky.sock   # in another shell

The stream is raw, headerless S16LE stereo PCM, pinned to 44.1 kHz for the socket/stdout sinks, so the consumer must be told the format explicitly (-f s16le -ar 44100 -ac 2) — there is no container to autodetect. If audio plays too slow or too fast, the -ar value doesn't match: the raw sinks are always 44100 Hz. Two more things to remember:

• stdout is only for the headless rocksky mpd — the tui renders to stdout, so use fifo: / unix: / tcp: there instead.
• unix: / tcp: are listen sockets: rocksky blocks until a client connects. Start rocksky first, then connect your player (or use the unix-connect: / tcp-connect: variants to have rocksky connect out).

MPD Server

Rocksky speaks the Music Player Daemon protocol, so any MPD client — ncmpcpp, rmpc, mpc, MALP, … — can control playback and browse your uploaded library.

Running it

Standalone daemon (works without the TUI):

rocksky mpd            # listens on 127.0.0.1:6600 by default
rocksky mpd -p 6601    # custom port
rocksky mpd -b 0.0.0.0 # bind address (for remote clients)

Then point a client at it:

mpc -p 6600 status
mpc -p 6600 play
ncmpcpp -h 127.0.0.1 -p 6600

You can also run the server inside the TUI by enabling it in settings (see below); it then shares the exact session you see in the TUI.

Configuration

Port and bind address come from the [mpd] section of ~/.rocksky/settings.toml, and are overridable with -p / -b:

[mpd]
enabled = false      # true also starts the server inside the TUI
port = 6600
bind = "127.0.0.1"

If the port is already in use, the server automatically falls back to the next free one (and logs which port it bound).

What you get

• Transport & options — play/pause/stop, next/previous, seek, volume, random (shuffle), repeat, single.
• Queue — view, add, delete, clear; songs use a stable rocksky:upload:… / rocksky:track:… URI.
• Library browse — Artists, Album Artists, Albums, and a Directory tree; tag filters (find/search/list) and stored playlists.
• Cover art — real album covers via albumart / readpicture.
• Live updates — idle change events (player, mixer, options, playlist, database), so clients refresh instantly.
• Resume — the session restored on startup shows as paused on the last track, so clients render it right away.
• Fast browsing — your whole library is preloaded into memory and cached on disk (~/.rocksky/mpd-cache), so browsing is instant and survives restarts. The cache is kept in sync with the API in the background; update / rescan triggers a fresh scan.

The server shares the same Rockbox-powered player as the TUI, so playback stays in sync between the two.

Note: reordering the play queue (move / in-queue shuffle) isn't supported by the underlying engine, and song ids track queue position.

Available Commands

login - Initiates a browser-based OAuth login flow and saves your access token securely on your machine.

rocksky login

nowplaying - Displays the currently playing track on your/other Rocksky account.

rocksky nowplaying

scrobble - Manually scrobbles a track.

rocksky scrobble "Karma Police" "Radiohead"

scrobbles - Lists all recently scrobbled tracks.

rocksky scrobbles

search - Searches for tracks, albums, artists or Rocksky users.

rocksky search <query>

stats - Displays your Rocksky account statistics.

rocksky stats [did]

artists - Lists the user's top artists.

rocksky artists [did]

albums - Lists the user's top albums.

rocksky albums [did]

tracks - Lists the user's top tracks.

rocksky tracks [did]

tui - Launch the interactive terminal UI (also the default when run with no command).

rocksky tui

upload - Upload audio files (or whole folders) to your private Rocksky library, with live progress.

rocksky upload track.flac ./my-album

scrobble-api - Start a local listenbrainz/lastfm compatibility server

rocksky scrobble-api

mpd - Start an MPD-protocol server to control playback and browse your library (see MPD Server).

rocksky mpd -p 6600

sync - Sync your local Rocksky data from AT Protocol

rocksky sync

whoami - Displays the current user's information.

rocksky whoami

mcp - Starts the Rocksky MCP server.

rocksky mcp

Rocksky MCP Server Tools

Here is a list of tools provided by the Rocksky MCP server:

whoami

Get the current user's information.

Example:

{
  "name": "whoami"
}

Returns:

The current user's information, including their DID, handle, and other relevant details.

nowplaying

Get the currently playing track.

Parameters:

• did (optional): The DID or handle of the user to get the now playing track for. If not provided, it defaults to the current user.

Example:

{
  "name": "nowplaying",
  "args": {
    "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
  }
}

Returns:

The currently playing track for the specified user.

scrobbles

Display recently played tracks (recent scrobbles).

Parameters:

• did (optional): The DID or handle of the user to get scrobbles for. If not provided, it returns all recent scrobbles from Rocksky.

Example:

{
  "name": "scrobbles",
  "args": {
    "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
  }
}

Returns:

A list of recently played tracks for the specified user.

my-scrobbles

Display recently played tracks (recent scrobbles) for the current user.

Example:

{
  "name": "my-scrobbles"
}

Returns:

A list of recently played tracks for the current user.

search

Search for tracks, albums, artists, or Rocksky users.

Parameters:

• query: The search query string.
• limit (optional): The maximum number of results to return. Defaults to 10.
• albums (optional): If true, search for albums. Defaults to false.
• artists (optional): If true, search for artists. Defaults to false.
• tracks (optional): If true, search for tracks. Defaults to false.
• users (optional): If true, search for Rocksky users. Defaults to false.

Example:

{
  "name": "search",
  "args": {
    "query": "Radiohead",
    "limit": 5,
    "albums": false,
    "artists": false,
    "tracks": false,
    "users": false
  }
}

Returns:

A list of search results based on the specified query and filters.

artists

List the user's top artists or current user's top artists if no did is provided.

Parameters:

• did (optional): The DID or handle of the user to get top artists for. If not provided, it defaults to the current user.
• limit (optional): The maximum number of artists to return. Defaults to 20.

Example:

{
  "name": "artists",
  "args": {
    "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
    "limit": 20
  }
}

Returns:

A list of the user's top artists, including their names and play counts.

albums

List the user's top albums or current user's top albums if no did is provided.

Parameters:

• did (optional): The DID or handle of the user to get top albums for. If not provided, it defaults to the current user.
• limit (optional): The maximum number of albums to return. Defaults to 20.

Example:

{
  "name": "albums",
  "args": {
    "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
    "limit": 20
  }
}

Returns:

A list of the user's top albums, including their names and play counts.

tracks

List the user's top tracks or current user's top tracks if no did is provided.

Parameters:

• did (optional): The DID or handle of the user to get top tracks for. If not provided, it defaults to the current user.
• limit (optional): The maximum number of tracks to return. Defaults to 20.

Example:

{
  "name": "tracks",
  "args": {
    "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
    "limit": 20
  }
}

Returns:

A list of the user's top tracks, including their names and play counts.

stats

Display the user's Rocksky account statistics or current user's statistics if no did is provided.

Parameters:

• did (optional): The DID or handle of the user to get statistics for. If not provided, it defaults to the current user.

Example:

{
  "name": "stats",
  "args": {
    "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
  }
}

create-apikey

Create a new API key for the current user.

Parameters:

• name: The name of the API key.
• description (optional): A description of the API key.

Example:

{
  "name": "create-apikey",
  "args": {
    "name": "My API Key",
    "description": "This is my API key."
  }
}

Returns:

A confirmation message indicating that the API key was created successfully.