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 the [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`scrobbles` - Lists all recently scrobbled tracks.
75
76```bash
77rocksky scrobbles
78```
79
80`search` - Searches for tracks, albums, artists or Rocksky users.
81
82```bash
83rocksky search <query>
84```
85
86`stats` - Displays your Rocksky account statistics.
87
88```bash
89rocksky stats [did]
90```
91
92`artists` - Lists the user's top artists.
93
94```bash
95rocksky artists [did]
96```
97
98`albums` - Lists the user's top albums.
99
100```bash
101rocksky albums [did]
102```
103
104`tracks` - Lists the user's top tracks.
105
106```bash
107rocksky tracks [did]
108```
109
110`scrobble` - Manually scrobbles a track.
111
112```bash
113rocksky scrobble "Karma Police" "Radiohead"
114```
115
116`whoami` - Displays the current user's information.
117
118```bash
119rocksky whoami
120```
121
122`mcp` - Starts the Rocksky MCP server.
123
124```bash
125rocksky mcp
126```
127
128## Rocksky MCP Server Tools
129
130Here is a list of tools provided by the Rocksky MCP server:
131
132### whoami
133
134Get the current user's information.
135
136**Example:**
137```json
138{
139 "name": "whoami"
140}
141```
142
143**Returns:**
144
145The current user's information, including their DID, handle, and other relevant details.
146
147### nowplaying
148
149Get the currently playing track.
150
151**Parameters:**
152
153- `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.
154
155**Example:**
156```json
157{
158 "name": "nowplaying",
159 "args": {
160 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
161 }
162}
163```
164
165**Returns:**
166
167The currently playing track for the specified user.
168
169### scrobbles
170
171Display recently played tracks (recent scrobbles).
172
173**Parameters:**
174- `did` (optional): The DID or handle of the user to get scrobbles for. If not provided, it returns all recent scrobbles from Rocksky.
175
176**Example:**
177```json
178{
179 "name": "scrobbles",
180 "args": {
181 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
182 }
183}
184```
185
186**Returns:**
187
188A list of recently played tracks for the specified user.
189
190### my-scrobbles
191
192Display recently played tracks (recent scrobbles) for the current user.
193
194**Example:**
195```json
196{
197 "name": "my-scrobbles"
198}
199```
200
201**Returns:**
202
203A list of recently played tracks for the current user.
204
205### search
206Search for tracks, albums, artists, or Rocksky users.
207
208**Parameters:**
209- `query`: The search query string.
210- `limit` (optional): The maximum number of results to return. Defaults to 10.
211- `albums` (optional): If true, search for albums. Defaults to false.
212- `artists` (optional): If true, search for artists. Defaults to false.
213- `tracks` (optional): If true, search for tracks. Defaults to false.
214- `users` (optional): If true, search for Rocksky users. Defaults to false.
215
216**Example:**
217```json
218{
219 "name": "search",
220 "args": {
221 "query": "Radiohead",
222 "limit": 5,
223 "albums": false,
224 "artists": false,
225 "tracks": false,
226 "users": false
227 }
228}
229```
230
231**Returns:**
232
233A list of search results based on the specified query and filters.
234
235### artists
236List the user's top artists or current user's top artists if no `did` is provided.
237
238**Parameters:**
239- `did` (optional): The DID or handle of the user to get top artists for. If not provided, it defaults to the current user.
240- `limit` (optional): The maximum number of artists to return. Defaults to 20.
241
242**Example:**
243```json
244{
245 "name": "artists",
246 "args": {
247 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
248 "limit": 20
249 }
250}
251```
252
253**Returns:**
254
255A list of the user's top artists, including their names and play counts.
256
257### albums
258List the user's top albums or current user's top albums if no `did` is provided.
259
260**Parameters:**
261- `did` (optional): The DID or handle of the user to get top albums for. If not provided, it defaults to the current user.
262- `limit` (optional): The maximum number of albums to return. Defaults to 20.
263
264**Example:**
265```json
266{
267 "name": "albums",
268 "args": {
269 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
270 "limit": 20
271 }
272}
273```
274
275**Returns:**
276
277A list of the user's top albums, including their names and play counts.
278
279### tracks
280List the user's top tracks or current user's top tracks if no `did` is provided.
281
282**Parameters:**
283- `did` (optional): The DID or handle of the user to get top tracks for. If not provided, it defaults to the current user.
284- `limit` (optional): The maximum number of tracks to return. Defaults to 20.
285
286**Example:**
287```json
288{
289 "name": "tracks",
290 "args": {
291 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr",
292 "limit": 20
293 }
294}
295```
296
297**Returns:**
298
299A list of the user's top tracks, including their names and play counts.
300
301### stats
302Display the user's Rocksky account statistics or current user's statistics if no `did` is provided.
303
304**Parameters:**
305- `did` (optional): The DID or handle of the user to get statistics for. If not provided, it defaults to the current user.
306
307**Example:**
308```json
309{
310 "name": "stats",
311 "args": {
312 "did": "did:plc:7vdlgi2bflelz7mmuxoqjfcr"
313 }
314}
315```
316
317### create-apikey
318Create a new API key for the current user.
319
320**Parameters:**
321- `name`: The name of the API key.
322- `description` (optional): A description of the API key.
323
324**Example:**
325```json
326{
327 "name": "create-apikey",
328 "args": {
329 "name": "My API Key",
330 "description": "This is my API key."
331 }
332}
333```
334
335**Returns:**
336
337A confirmation message indicating that the API key was created successfully.
338
339
340