t1c.dev
forked from
rocksky.app/rocksky
A decentralized music tracking and discovery platform built on AT Protocol 🎵
tsiry-sandratraina.com
1## Rocksky CLI
2
3🎧 The official command-line interface for [Rocksky](https://rocksky.app) — a modern, decentralized music tracking and discovery platform built on [AT Protocol](https://atproto.com).
4
5## Features
6- 🔐 Authenticate with your Rocksky account using OAuth
7- 🎵 View your currently playing track
8- 📈 See your recent scrobbles
9- 📤 Manually scrobble tracks
10- 🛠️ Useful developer tools for integrating Rocksky into your workflows
11- 🤖 MCP Server
12
13## Table of Contents
14- [Installation](#installation)
15- [Run in development](#run-in-development)
16- [Usage](#usage)
17- [Available Commands](#available-commands)
18- [Rocksky MCP Server Tools](#rocksky-mcp-server-tools)
19 - [whoami](#whoami)
20 - [nowplaying](#nowplaying)
21 - [scrobbles](#scrobbles)
22 - [search](#search)
23 - [stats](#stats)
24 - [artists](#artists)
25 - [albums](#albums)
26 - [tracks](#tracks)
27
28## Installation
29
30```sh
31npm install -g @rocksky/cli
32```
33
34You can also use the CLI without installing it globally by running `npx`:
35
36```sh
37npx @rocksky/cli --help
38```
39
40## Run in development
41To run the CLI in development mode, install the dependencies:
42
43```bash
44bun install
45```
46
47Then, run the CLI with:
48
49```bash
50bun run dev --help
51```
52
53
54## Usage
55
56```bash
57rocksky <command> [options]
58```
59
60## Available Commands
61
62`login` - Initiates a browser-based OAuth login flow and saves your access token securely on your machine.
63
64```bash
65rocksky login
66```
67
68`nowplaying` - Displays the currently playing track on your/other Rocksky account.
69
70```bash
71rocksky nowplaying
72```
73
74`scrobble` - Manually scrobbles a track.
75
76```bash
77rocksky scrobble "Karma Police" "Radiohead"
78```
79
80`scrobbles` - Lists all recently scrobbled tracks.
81
82```bash
83rocksky scrobbles
84```
85
86`search` - Searches for tracks, albums, artists or Rocksky users.
87
88```bash
89rocksky search <query>
90```
91
92`stats` - Displays your Rocksky account statistics.
93
94```bash
95rocksky stats [did]
96```
97
98`artists` - Lists the user's top artists.
99
100```bash
101rocksky artists [did]
102```
103
104`albums` - Lists the user's top albums.
105
106```bash
107rocksky albums [did]
108```
109
110`tracks` - Lists the user's top tracks.
111
112```bash
113rocksky tracks [did]
114```
115
116`scrobble-api` - Start a local listenbrainz/lastfm compatibility server
117
118```bash
119rocksky scrobble-api
120```
121
122`sync` - Sync your local Rocksky data from AT Protocol
123
124```bash
125rocksky sync
126```
127
128`whoami` - Displays the current user's information.
129
130```bash
131rocksky whoami
132```
133
134`mcp` - Starts the Rocksky MCP server.
135
136```bash
137rocksky mcp
138```
139
140## Rocksky MCP Server Tools
141
142Here is a list of tools provided by the Rocksky MCP server:
143
144### whoami
145
146Get the current user's information.
147
148**Example:**
149```json
150{
151 "name": "whoami"
152}
153```
154
155**Returns:**
156
157The current user's information, including their DID, handle, and other relevant details.
158
159### nowplaying
160
161Get the currently playing track.
162
163**Parameters:**
164
165- `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.
166
167**Example:**
168```json
169{
170 "name": "nowplaying",
171 "args": {
172 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
173 }
174}
175```
176
177**Returns:**
178
179The currently playing track for the specified user.
180
181### scrobbles
182
183Display recently played tracks (recent scrobbles).
184
185**Parameters:**
186- `did` (optional): The DID or handle of the user to get scrobbles for. If not provided, it returns all recent scrobbles from Rocksky.
187
188**Example:**
189```json
190{
191 "name": "scrobbles",
192 "args": {
193 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
194 }
195}
196```
197
198**Returns:**
199
200A list of recently played tracks for the specified user.
201
202### my-scrobbles
203
204Display recently played tracks (recent scrobbles) for the current user.
205
206**Example:**
207```json
208{
209 "name": "my-scrobbles"
210}
211```
212
213**Returns:**
214
215A list of recently played tracks for the current user.
216
217### search
218Search for tracks, albums, artists, or Rocksky users.
219
220**Parameters:**
221- `query`: The search query string.
222- `limit` (optional): The maximum number of results to return. Defaults to 10.
223- `albums` (optional): If true, search for albums. Defaults to false.
224- `artists` (optional): If true, search for artists. Defaults to false.
225- `tracks` (optional): If true, search for tracks. Defaults to false.
226- `users` (optional): If true, search for Rocksky users. Defaults to false.
227
228**Example:**
229```json
230{
231 "name": "search",
232 "args": {
233 "query": "Radiohead",
234 "limit": 5,
235 "albums": false,
236 "artists": false,
237 "tracks": false,
238 "users": false
239 }
240}
241```
242
243**Returns:**
244
245A list of search results based on the specified query and filters.
246
247### artists
248List the user's top artists or current user's top artists if no `did` is provided.
249
250**Parameters:**
251- `did` (optional): The DID or handle of the user to get top artists for. If not provided, it defaults to the current user.
252- `limit` (optional): The maximum number of artists to return. Defaults to 20.
253
254**Example:**
255```json
256{
257 "name": "artists",
258 "args": {
259 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
260 "limit": 20
261 }
262}
263```
264
265**Returns:**
266
267A list of the user's top artists, including their names and play counts.
268
269### albums
270List the user's top albums or current user's top albums if no `did` is provided.
271
272**Parameters:**
273- `did` (optional): The DID or handle of the user to get top albums for. If not provided, it defaults to the current user.
274- `limit` (optional): The maximum number of albums to return. Defaults to 20.
275
276**Example:**
277```json
278{
279 "name": "albums",
280 "args": {
281 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
282 "limit": 20
283 }
284}
285```
286
287**Returns:**
288
289A list of the user's top albums, including their names and play counts.
290
291### tracks
292List the user's top tracks or current user's top tracks if no `did` is provided.
293
294**Parameters:**
295- `did` (optional): The DID or handle of the user to get top tracks for. If not provided, it defaults to the current user.
296- `limit` (optional): The maximum number of tracks to return. Defaults to 20.
297
298**Example:**
299```json
300{
301 "name": "tracks",
302 "args": {
303 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
304 "limit": 20
305 }
306}
307```
308
309**Returns:**
310
311A list of the user's top tracks, including their names and play counts.
312
313### stats
314Display the user's Rocksky account statistics or current user's statistics if no `did` is provided.
315
316**Parameters:**
317- `did` (optional): The DID or handle of the user to get statistics for. If not provided, it defaults to the current user.
318
319**Example:**
320```json
321{
322 "name": "stats",
323 "args": {
324 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
325 }
326}
327```
328
329### create-apikey
330Create a new API key for the current user.
331
332**Parameters:**
333- `name`: The name of the API key.
334- `description` (optional): A description of the API key.
335
336**Example:**
337```json
338{
339 "name": "create-apikey",
340 "args": {
341 "name": "My API Key",
342 "description": "This is my API key."
343 }
344}
345```
346
347**Returns:**
348
349A confirmation message indicating that the API key was created successfully.