Soulseek client · terminal · Rust

A Soulseek client for the terminal. Built for agents and people who live there.

Search the network, share your files, browse someone’s collection, join a room. It runs over ssh on the machine where your music already lives.

Install Read the docs GitHub

Status

soulseek-rs 🦀 v13.0.0Downloads: 3 active, 2 completed, 2 failed, 0 queued, 0 paused67.7/205.2 MB · 33.38 MB/s0%

[1] Searches

StatusQueryResults

[2] Results: public domain field recordings

✓FilenameSizeUserBitrateSpeedSlots

searching the network

[3] Downloads/Uploads

StatusFilenameUserProgressSpeed

✓@@lrfkq\Contents\RotterdamDan DillionCompleted-

✓@@lrfkq\Contents\JournalDan DillionCompleted-

↯@@lrfkq\Contents\ContextDan Dillion37.5 MB/53.4 MB (70%)12.4 MB/s

✗@@gufoo\put all musicspublicdomainbotFailed-

↯02-RawMusic\Embark Studiotapehiss10.4 MB/14.3 MB (72%)11.5 MB/s

✗@@medvw\Soulseek\completex100Failed-

↯@@hnttf\complete\(2004 netlabel)nectoUA10.5 MB/25.5 MB (41%)9.3 MB/s

Info

—

User—

Size—

StatusAvailable

Bitrate-

Queue positionunknownFree slots0

Shortcuts · Sharing

Sharing: ~/Downloads/Soulseek

[Space → select][Enter → download][b → browse owner][c → chat][/ → filter][a/A → select all/none][1-3 → focus pane][q → quit]

Runs on

what it is

A client for a network that runs on people.

No charts, no recommendations. You search, you find the person who has it, you download it from them.

Soulseek is a peer-to-peer network from the early 2000s. People still use it to share niche music by hand: the album that exists in one person’s folder and nowhere else.

soulseek-rs speaks that protocol, as a third-party client rather than the official app. It shares, browses, does rooms and private messages, because a client that only downloads makes you a leech on people who left their machines on for you. What sharing asks of you

build your own

Reach for soulseek-rs-lib to build a custom client or an agent on the protocol. Use the library

agents and automation

Every command runs as a one-off. Point a script or an agent at it and read JSON records off stdout. Start soulseek-rs daemon first when several run at once, so they share one login instead of cutting each other off. skills install hands your agent that habit, plus the JSON keys and exit codes --help leaves out. See the commands

features

What it does.

Everything happens in the TUI, and every command also runs as a one-off.

Agent native

Run it once and your agent knows the record shapes, the exit codes, and the filters, so “find the 1998 pressing, lossless only” becomes a pipeline it writes itself. The skill ships in the binary and finds your coding agents on its own. No MCP server.

Search & download

Queue downloads in the TUI with pause, resume, and retry, or let get search, pick the best, and download in one command.

Sharing

Point shares add at a directory and your files show up in searches; serve stays online so peers can browse and download them.

Daemon mode

One session every other command borrows. Leave it on a NAS to share and download around the clock, or let an agent fan out twenty commands on one login. It speaks JSON-RPC, so your own tools can drive it too.

Browse

List any user’s shared files and download straight from the tree.

Chat rooms

List, join, and talk in public rooms, several open at once as tabs.

Private messages

Send and receive PMs, with an inbox and an unread counter in the TUI.

Firewalled peers

Downloads and browsing fall back to a server-brokered connection when a peer can’t be reached directly.

Automatic port mapping

Opens your listen port via UPnP-IGD and NAT-PMP, with a portmap subcommand to test your router.

TUI and CLI

A full terminal interface, plus scriptable subcommands: stdout is data, stderr is progress, the exit code is the verdict.

agent native

Ask for the record. Skip the pipeline.

An agent can run any CLI. skills install teaches it to run this one well.

--help lists flags. It cannot say which JSON keys a record carries, or that exit 4 means widen the query rather than retry it. An agent guesses instead, and guessing against a stranger’s file server hangs the job.

skills install fills that in, so you ask for outcomes instead of writing pipelines: fill the gaps in a discography from whoever has a free slot, or read a peer’s profile for their limits before queueing 2 GB behind them.

Still a CLI: no MCP server, no API key. The skill tells your agent to start a daemon first, so a batch of parallel requests is one login rather than one per command. Upgrading the binary upgrades the skill; rerun skills install to take it. See the commands

get started

Install it, then press s to search.

One command on macOS or Linux, then the TUI opens. No Rust toolchain needed.

Read the docs Install options

quick start

$ curl -fsSL https://re-invention.nl/soulseek-rs/install.sh | sh$ soulseek-rs