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

• 🔐 Authenticate with your Rocksky account using OAuth
• 🎵 View your currently playing track
• 📈 See your recent scrobbles
• 📤 Manually scrobble tracks
• 🛠️ Useful developer tools for integrating Rocksky into your workflows
• 🤖 MCP Server

Table of Contents

• Documentation
• Installation
• Run in development
• Usage
• 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]

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]

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

rocksky scrobble-api

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.