bjarneo--cliamp/docs/cli.md

CLI Flags

Override any config option for a single session without editing ~/.config/cliamp/config.toml. Flags can appear before or after file/URL arguments.

Playback

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 (add --auto-play to start playback)

Audio engine

cliamp --sample-rate 48000 track.mp3      # output sample rate (22050, 44100, 48000, 96000, 192000)
cliamp --buffer-ms 2000 track.mp3         # speaker buffer in ms (50-5000; useful for unstable radio)
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)

Appearance

cliamp --compact ~/Music                     # cap width at 80 columns
cliamp --eq-preset "Bass Boost" ~/Music

Diagnostics

cliamp --log-level debug                     # raise log verbosity for one session

Logs are written to ~/.config/cliamp/cliamp.log. Levels: debug, info (default), warn, error.

Low-power mode

cliamp --low-power track.mp3                 # reduce CPU load for this session

Reduces CPU load by lowering UI/render cadence and forcing the visualizer to none. Useful on battery, slow terminals, or SSH sessions. Press v in the player to cycle visualizers back on at any time.

To make this persistent, set it in ~/.config/cliamp/config.toml:

low_power = true

Headless daemon mode

cliamp --daemon                              # no TUI, IPC only
cliamp --daemon --auto-play --playlist Lofi  # start playing on launch
cliamp -d ~/Music --auto-play                # short flag form

Runs cliamp without rendering a UI, listening on the same Unix socket the TUI uses. All cliamp <subcommand> IPC clients keep working. UI-specific commands (theme, vis) return an error in this mode. See Headless Daemon Mode for use cases and example configs (Waybar, Hyprland, systemd, cron).

Search

Search 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 SoundCloud

Press Ctrl+F in the player for context-aware search: it runs the active provider's native search when available or falls back to YouTube search.

General

Flag	Short	Description
--help	-h	Show help and exit
--version	-v	Print version and exit
--upgrade		Update to the latest release

Shell completion

Generate shell completion scripts for supported shells.

cliamp completion bash
cliamp completion zsh
cliamp completion fish
cliamp completion pwsh

The generated script can be sourced directly or installed according to your shell's documentation.

Mixing flags and files

Flags can appear before, after, or between positional arguments:

cliamp --shuffle track.mp3 --volume -5
cliamp track.mp3 --repeat all --mono ~/Music

Flag reference

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	250	50-5000
--resample-quality	int	4	1–4
--bit-depth	int	16	16, 32
--playlist	string		local TOML playlist name
--log-level	string	info	debug, info, warn, error
--low-power	bool	false	lowers UI cadence; disables visualization
--daemon / -d	bool	false	run headless; IPC only, no TUI

CLI flags override config file values for the current session only. They are not persisted.

Setup wizard

Configure remote providers (Navidrome, Plex, Jellyfin, Emby, Spotify, Qobuz, NetEase, Audiobookshelf, YouTube Music) through a small TUI. Each provider page links to where to find the required credentials, validates the connection live, and writes the resulting [provider] block to ~/.config/cliamp/config.toml without disturbing the rest of the file.

cliamp setup

Keys: ↑/↓ to navigate, Enter to confirm or submit, Esc to back out, q from the menu to quit. Passwords and tokens are masked. Running setup again for an already-configured provider replaces its section in place.

Playlist Management

Manage local TOML playlists from the command line without opening the TUI.

cliamp playlist list                          # list playlists with track counts
cliamp playlist create "Name"                 # create an empty playlist
cliamp playlist create "Name" file1 dir/ ...  # create from files/folders (recursive, skips duplicate paths)
cliamp playlist create "Name" --ssh HOST dir/ # create from remote machine via SSH
cliamp playlist create "Name" --dir ~/Music   # reference a directory as a [[dir]] source (scanned at load)
cliamp playlist add "Name" file1 ...          # append tracks to existing playlist, skipping duplicates
cliamp playlist add "Name" --dir ~/Music      # add another directory source
cliamp playlist dirs "Name"                   # list directory sources
cliamp playlist rename "Old" "New"            # rename a 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 dedupe "Name"                 # remove duplicate paths, keeping the first
cliamp playlist sort "Name" --by album         # sort in place
cliamp playlist doctor [Name]                  # report missing local files
cliamp playlist doctor "Name" --fix            # prune missing local files
cliamp playlist export "Name" -o mix.m3u       # export as M3U
cliamp playlist export "Name" --format pls     # export as PLS to stdout
cliamp playlist import mix.m3u --name "Name"   # import local M3U/M3U8/PLS
cliamp playlist bookmark "Name" --index 3      # toggle bookmark flag
cliamp playlist bookmarks                       # list bookmarked tracks
cliamp playlist enrich "Name"                   # probe duration/album 
cliamp playlist enrich "Name" --source metadata   # probe duration/album (forces to use the file's metadata as source)
cliamp playlist delete "Name"                   # delete entire playlist

Sort keys: track, title, artist, album, artist+album, path.

See playlists.md for the TOML format and ssh-streaming.md for remote playback.

Recently Played

cliamp history                                # show the 50 most recent plays
cliamp history --limit 200                    # change the cap
cliamp history --json                         # machine-readable output
cliamp history clear                          # wipe ~/.config/cliamp/history.toml

A play is recorded once you've listened to a track for at least 50% of its duration. Inside the TUI, the same data appears as the virtual "Recently Played" entry in the Local Playlists provider. See history.md.

Spotify

cliamp spotify reset                          # clear stored Spotify credentials

Use spotify reset if you see persistent rate-limited on /v1/me warnings or stale auth errors. After running it, relaunch cliamp and select Spotify to sign in again. See spotify.md for the full setup guide.

Remote Control (IPC)

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 device

See remote-control.md for the full protocol specification.