Override any config option for a single session without editing ~/.config/cliamp/config.toml. Flags can appear before or after file/URL arguments.
cliamp --volume -5 track.mp3 # volume in dB [-30, +6]
cliamp --shuffle ~/Music # enable shuffle
cliamp --repeat all ~/Music # repeat mode: off, all, one
cliamp --mono track.mp3 # downmix to mono
cliamp --no-mono track.mp3 # force stereo
cliamp --auto-play ~/Music # start playback immediately
cliamp --playlist "Blade Runner" # load a local TOML playlist and start playingcliamp --sample-rate 48000 track.mp3 # output sample rate (22050, 44100, 48000, 96000, 192000)
cliamp --buffer-ms 200 track.mp3 # speaker buffer in ms (50–500)
cliamp --resample-quality 1 track.mp3 # resample quality factor (1–4)
cliamp --bit-depth 32 track.m4a # PCM bit depth: 16 (default) or 32 (lossless)cliamp --compact ~/Music # cap width at 80 columns
cliamp --eq-preset "Bass Boost" ~/MusicSearch and play a track directly from the command line (requires yt-dlp):
cliamp search "never gonna give you up" # search YouTube
cliamp search-sc "lofi beats" # search SoundCloudPress f in the player to search YouTube interactively, or F (Shift+F) to search SoundCloud.
| Flag | Short | Description |
|---|---|---|
--help |
-h |
Show help and exit |
--version |
-v |
Print version and exit |
--upgrade |
Update to the latest release |
Flags can appear before, after, or between positional arguments:
cliamp --shuffle track.mp3 --volume -5
cliamp track.mp3 --repeat all --mono ~/Music| Flag | Type | Default | Range / Values |
|---|---|---|---|
--volume |
float | 0 | -30 to +6 dB |
--shuffle |
bool | false | |
--repeat |
string | off | off, all, one |
--mono / --no-mono |
bool | false | |
--auto-play |
bool | false | |
--compact |
bool | false | |
--theme |
string | theme name | |
--eq-preset |
string | preset name | |
--sample-rate |
int | 44100 | 22050, 44100, 48000, 96000, 192000 |
--buffer-ms |
int | 100 | 50–500 |
--resample-quality |
int | 4 | 1–4 |
--bit-depth |
int | 16 | 16, 32 |
--playlist |
string | local TOML playlist name |
CLI flags override config file values for the current session only. They are not persisted.
Manage local TOML playlists from the command line without opening the TUI.
cliamp playlist list # list playlists with track counts
cliamp playlist create "Name" file1 dir/ ... # create from files/folders (recursive)
cliamp playlist create "Name" --ssh HOST dir/ # create from remote machine via SSH
cliamp playlist add "Name" file1 ... # append tracks to existing playlist
cliamp playlist show "Name" # display tracks
cliamp playlist show "Name" --json # machine-readable output
cliamp playlist remove "Name" --index 3 # remove track by index
cliamp playlist delete "Name" # delete entire playlistSee playlists.md for the TOML format and ssh-streaming.md for remote playback.
Control a running cliamp instance from another terminal:
cliamp play / pause / toggle / stop # playback control
cliamp next / prev # track navigation
cliamp status # current state
cliamp status --json # machine-readable state
cliamp volume -5 # adjust volume (dB)
cliamp seek 30 # seek to position (seconds)
cliamp load "Playlist Name" # load a playlist
cliamp queue /path/to/file.mp3 # queue a track
cliamp shuffle [on|off|toggle] # toggle or set shuffle
cliamp repeat [off|all|one|cycle] # set or cycle repeat mode
cliamp mono [on|off|toggle] # toggle or set mono output
cliamp speed 1.5 # set playback speed (0.25–2.0)
cliamp eq Rock # set EQ preset by name
cliamp eq --band 0 6.0 # set EQ band 0 to +6 dB
cliamp device list # list audio output devices
cliamp device "My DAC" # switch audio output deviceSee remote-control.md for the full protocol specification.