---
name: "cmus-remote"
section: "1"
platform: "linux"
package: "cmus"
version: "2.12.0-7"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/cmus-remote"
---

# cmus-remote(1)

control cmus

## NAME

cmus-remote - control cmus

## SYNOPSIS

cmus-remote \[**OPTION**\]... \[*FILE*\|*DIR*\|*PLAYLIST*\]...\
 cmus-remote **-C** *COMMAND*...\
 cmus-remote

## DESCRIPTION

Add *FILE/DIR/PLAYLIST* to playlist, library (**-l**) or play queue (**-q**).

If no arguments are given cmus-remote reads raw commands from stdin (one command per line).  Raw commands are cmus' command mode commands.  These same commands are used in configuration files and key bindings.  [**cmus**(1)](/cmus/1.md) contains full list of commands.  For consistency also searching is supported: **-C /text**.

If **-C** is given, all command line arguments are treated as raw commands.

## OPTIONS

- \--server SOCKET

  Connect using socket **SOCKET** instead of *$XDG\_RUNTIME\_DIR/cmus-socket*.

- \--passwd PASSWD

  password to use for TCP/IP connection

- \--help

  Display usage information and exit.

- \--version

  Display version information and exit.

- \-p, --play

  Start playing.

- \-u, --pause

  Toggle pause.

- \-U, --pause-playback

  Pause if currently playing.

- \-s, --stop

  Stop playing.

- \-n, --next

  Skip forward in playlist.

- \-r, --prev

  Skip backward in playlist.

- \-R, --repeat

  Toggle repeat.

- \-S, --shuffle

  Toggle shuffle.

- \-v, --volume VOL

  Change volume. See **vol** command in [**cmus**(1)](/cmus/1.md).

- \-k, --seek SEEK

  Seek. See **seek** command in [**cmus**(1)](/cmus/1.md).

- \-f, --file FILE

  Play from file.

- \-Q

  Get player status information.  Same as **-C status**.  Note that **status** is a special command only available to cmus-remote.

- \-l, --library

  Modify library instead of playlist.

- \-P, --playlist

  Modify playlist (default).

- \-q, --queue

  Modify play queue instead of playlist.

- \-c, --clear

  Clear playlist, library (**-l**) or play queue (**-q**).

- \-C, --raw

  Treat arguments (instead of stdin) as raw commands.

## REMOTE COMMANDS

Special commands only available to cmus-remote.

status

Print information about currently playing track.

format\_print

Print arguments as *Format Strings*. Each argument starts a new line.

## EXAMPLES

Add playlists/files/directories/URLs to library view (1 & 2):

```
$ cmus-remote -l music.m3u \
http://live.urn1350.net:8080/urn_high.ogg
```

Load (clear and add) playlist to playlist view (3):

```
$ cmus-remote -c music.m3u
```

Three different ways to toggle repeat:

```
$ cmus-remote -R
$ cmus-remote -C "toggle repeat"
$ cmus-remote
toggle repeat
^D
```

Query settings or key bindings:

```
$ cmus-remote -C "set repeat?"
setting: 'repeat=false'
$ cmus-remote -C "showbind common a"
bind common a win-add-l
```

Dump the playlist to stdout:

```
$ cmus-remote -C "save -p -"
[...]
```

Search works too:

```
$ cmus-remote -C /beatles
```

## SEE ALSO

[**cmus**(1)](/cmus/1.md)

## AUTHOR

Written by Timo Hirvonen \<tihirvon@gmail.com\>