# 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

```sh
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

```sh
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

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

## Diagnostics

```sh
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

```sh
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`:

```toml
low_power = true
```

## Headless daemon mode

```sh
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](headless.md) for use cases and example configs (Waybar, Hyprland, systemd, cron).

## Search

Search and play a track directly from the command line (requires [yt-dlp](https://github.com/yt-dlp/yt-dlp)):

```sh
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.

```sh
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:

```sh
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, 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.

```sh
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.

```sh
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 add "Name" file1 ...          # append tracks to existing playlist, skipping duplicates
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 metadata
cliamp playlist delete "Name"                 # delete entire playlist
```

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

See [playlists.md](playlists.md) for the TOML format and [ssh-streaming.md](ssh-streaming.md) for remote playback.

## Recently Played

```sh
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](history.md).

## Spotify

```sh
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](spotify.md) for the full setup guide.

## Remote Control (IPC)

Control a running cliamp instance from another terminal:

```sh
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](remote-control.md) for the full protocol specification.
