Black Candy CLI

A Rust command-line client for Black Candy.

Install

Install the latest release with Cargo from the Git tag:

cargo install --git https://github.com/blackcandy-org/cli --tag v0.1.0 blackcandy-cli

Or install with Homebrew:

brew tap blackcandy-org/cli https://github.com/blackcandy-org/cli
brew install blackcandy-cli

To install from a local checkout:

cargo install --path .

All install methods provide the blackcandy command.

Playback is built in, so no external player is required. On Linux the ALSA development headers are needed to build the audio backend:

sudo apt install libasound2-dev

This is a build-time dependency only. At runtime the binary just needs the libasound2 runtime library, which any Linux system with working audio already has.

Quick Start

Run a local Black Candy server:

docker run --rm --name blackcandy-dev -p 3000:80 ghcr.io/blackcandy-org/blackcandy:edge

Log in with the default development account:

blackcandy login http://localhost:3000 --email admin@admin.com

The server address may omit the scheme; localhost:3000 is treated as http://localhost:3000.

The default password is foobar. Any argument you omit (including the server address) is prompted for interactively, so blackcandy login on its own walks through each field.

Check the server and browse songs:

blackcandy system
blackcandy songs list --limit 20
blackcandy search "love"

Play a song:

blackcandy play 1

To print the stream URL without playing it:

blackcandy play 1 --dry-run

Common Commands

blackcandy system
blackcandy search "love"
blackcandy songs list --limit 20
blackcandy songs show 1
blackcandy play 1
blackcandy queue list
blackcandy queue add 1 --last
blackcandy favorite list
blackcandy favorite add 1
blackcandy playlist list
blackcandy playlist create "Road Trip"
blackcandy playlist add-song 3 1

Most read commands support --json for scripting:

blackcandy songs list --limit 10 --json
blackcandy playlist list --json

Configuration

Login stores the server URL, email, and API token in:

blackcandy config

The config file is written with user-only permissions on Unix systems.

For isolated test runs, point BLACKCANDY_CONFIG at a temporary file:

BLACKCANDY_CONFIG=/tmp/blackcandy-cli.toml \
  blackcandy login http://localhost:3000 --email admin@admin.com --password foobar

Login can also read credentials from environment variables:

BLACKCANDY_EMAIL=admin@admin.com \
BLACKCANDY_PASSWORD=foobar \
  blackcandy login http://localhost:3000

Development

cargo build
cargo run -- --help
cargo fmt -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

For local development without installing the binary, prefix commands with cargo run --:

cargo run -- songs list --limit 20