Command Line
Arguments passed to festival-cli will always take priority over the same configuration options read from disk.
See JSON-RPC for method command-line syntax.
Usage: festival-cli [--OPTIONS] <METHOD> [--PARAM <VALUE>]
Arguments passed to `festival-cli` will always take
priority over configuration options read from disk.
Commands:
collection_new Create a new Collection (and replace the current one)
collection_brief Retrieve some brief metadata about the current Collection
collection_full Retrieve full metadata about the current Collection
collection_brief_artists Retrieve an array of every Artist name in the current Collection
collection_brief_albums Retrieve an array of every Album title in the current Collection
collection_brief_songs Retrieve an array of every Song title in the current Collection
collection_full_artists Retrieve an array of every Artist in the current Collection
collection_full_albums Retrieve an array of every Album in the current Collection
collection_full_songs Retrieve an array of every Song in the current Collection
collection_entries Retrieve an array of every Song in the current Collection, with its relational data
collection_perf View some performance stats about the latest Collection construction
collection_health View the health of the Collection (underlying files)
collection_resource_size View the size of the current Collection's underlying resources (audio files and art)
daemon_config Retrieve the active configuration of `festivald`
daemon_methods Retrieve all JSON-RPC methods this `festivald` knows about
daemon_no_auth_rpc Retrieve all no_auth_rpc JSON-RPC methods this `festivald` allows
daemon_no_auth_rest Retrieve all no_auth_rest REST resources this `festivald` allows
daemon_remove_cache Remove `festivald` cache from disk
daemon_save Save `festivald` data to disk
daemon_seen_ips Retrieve an array of the IP addresses `festivald` has seen
daemon_shutdown Shutdown `festivald`
daemon_state Retrieve brief state of `festivald`
state_audio Retrieve audio state
state_queue_key Retrieve state of the queue as Keys
state_queue_song Retrieve state of the queue as Song objects
state_queue_entry Retrieve state of the queue as Entry objects
state_playing Retrieve the current playback status
state_repeat Retrieve the currently set Repeat mode
state_runtime Retrieve the elapsed runtime & total runtime of the currently set Song
state_volume Retrieve the current volume level
key_artist Input an Artist key, retrieve an Artist
key_album Input an Album key, retrieve an Album
key_song Input a Song key, retrieve a Song
key_entry Input a Song key, retrieve an Entry
key_artist_albums Input an Artist key, retrieve all their Albums
key_artist_songs Input an Artist key, retrieve all their Songs
key_artist_entries Input an Artist key, retrieve all their Songs in Entry form
key_album_artist Input an Album key, retrieve its Artist
key_album_songs Input an Album key, retrieve all its Songs
key_album_entries Input an Album key, retrieve all its Songs in Entry form
key_song_artist Input an Song key, retrieve its Artist
key_song_album Input an Song key, retrieve its Album
key_other_albums Input an Album key, retrieve all Albums by the same Artist
key_other_songs Input an Song key, retrieve all Songs by the same Artist
key_other_entries Input an Song key, retrieve all Songs by the same Artist in Entry form
map_artist Input an Artist name, retrieve an Artist
map_album Input an Artist name and Album title, retrieve an Album
map_song Input an Artist name, Album title, and Song title, retrieve a Song
map_entry Input an Artist name, Album title, and Song title, retrieve an Entry
map_artist_albums Input an Artist name, retrieve all their Albums
map_artist_songs Input an Artist name, retrieve all their Songs
map_artist_entries Input an Artist name, retrieve all their Songs in Entry form
map_album_songs Input an Artist name and Album title, retrieve all its Songs
map_album_entries Input an Artist name and Album title, retrieve all its Songs in Entry form
current_artist Access the Artist of the currently set Song
current_album Access the Album of the currently set Song
current_song Access the currently set Song
current_entry Access the currently set Song, as an Entry
rand_artist Access a random Artist
rand_album Access a random Album
rand_song Access a random Song
rand_entry Access a random Song, as an Entry
search Input a string, retrieve arrays of Artist's, Album's, and Song's, sorted by how similar their names/titles are to the input
search_artist Input a string, retrieve an array of Artist's, sorted by how similar their names are to the input
search_album Input a string, retrieve an array of Album's, sorted by how similar their titles are to the input
search_song Input a string, retrieve an array of Song's, sorted by how similar their titles are to the input
search_entry Input a string, retrieve an array of Song's (in Entry form), sorted by how similar their titles are to the input
toggle Toggle playback
play Start playback
pause Pause playback
next Skip to the next song in the queue
stop Clear the queue and stop playback
previous Set the current Song to the previous in the queue
clear Clear the queue
seek Seek forwards/backwards or to an absolute second in the current Song
skip Skip forwards a variable amount of Song's in the current queue
back Go backwards a variable amount of Song's in the current queue
shuffle Shuffle the current queue, then start playing from the 1st Song in the queue
repeat Set a repeat mode
volume Set the playback volume
volume_up Raise the playback volume
volume_down Lower the playback volume
queue_add_key_artist Add an Artist to the queue with an Artist key
queue_add_key_album Add an Album to the queue with an Album key
queue_add_key_song Add an Song to the queue with an Song key
queue_add_map_artist Add an Artist to the queue with an Artist name
queue_add_map_album Add an Album to the queue with an Artist name and Album title
queue_add_map_song Add a Song to the queue with an Artist name Album title, and Song title
queue_add_rand_artist Add a random Artist to the queue
queue_add_rand_album Add a random Album to the queue
queue_add_rand_song Add a random Song to the queue
queue_add_rand_entry Add a random Song to the queue, receive it back in Entry form
queue_add_playlist Add a playlist to the queue
queue_set_index Set the current Song to a queue index
queue_remove_range Remove a range of queue indices
playlist_new Create a new empty playlist
playlist_remove Remove a playlist
playlist_clone Clone a playlist into a new one
playlist_get_index Get a Playlist Entry in a Playlist, using its index number
playlist_remove_index Remove a Playlist Entry in a Playlist, using its index number
playlist_add_key_artist Add an artist to a playlist
playlist_add_key_album Add an album to a playlist
playlist_add_key_song Add a song to a playlist
playlist_add_map_artist Add an artist to a playlist
playlist_add_map_album Add an album to a playlist
playlist_add_map_song Add a song to a playlist
playlist_single Retrieve a single playlist
playlist_brief Retrieve all playlist names
playlist_full Retrieve full data of all playlists
help Print this message or the help of the given subcommand(s)
Options:
-f, --festivald <URL>
URL of the `festivald` to connect to
The protocol, IPv4 address, and port of the
`festivald` that `festival-cli` will connect
to by default.
Protocol must be:
- http
- https
IP address must be IPv4.
Default is: `http://127.0.0.1:18425`
-t, --timeout <SECONDS>
Set a timeout for a non-responding `festivald`
If `festivald` does not respond with _at least_
a basic HTTP header within this time (seconds),
`festival-cli` will disconnect.
0 means never disconnect.
-i, --id <ID>
The `JSON-RPC 2.0` ID to send to `festivald`.
See below for more info:
<https://jsonrpc.org/specification>
-a, --authorization <USER:PASS or FILE>
Authorization sent to `festivald`
This matches the `authorization` config
in `festivald`, see here for more info:
<https://docs.festival.pm/daemon/authorization/authorization.html>
A `festivald` with `HTTPS` or `.onion` must be
used or `festival-cli` will refuse to start.
An empty string disables this feature.
Alternatively, you can input an absolute PATH to a file
`festival-cli` can access, containing the string, e.g:
```
authorization = "/path/to/user_and_pass.txt"
```
In this case, `festival-cli` will read the file and attempt
to parse it with the same syntax, i.e, the file should contain:
```
my_user:my_pass
```
-p, --proxy <PROXY>
Route connections through a proxy
Requests/responses will be routed via this proxy.
Supported proxies are: `HTTP`, `SOCKS4`, and `SOCKS5`.
The input must be:
- Proxy protocol (`http://`, `socks4://`, `socks5://`)
- Proxy IP
- Proxy port
For example: `festival-cli --proxy socks5://127.0.0.1:9050`
-d, --debug
Print debug information about the config/request/response
--confirm-no-tls-auth
Allow `--authorization` even without TLS
This will let you set the authorization
setting even if TLS is disabled.
This means your `user:pass` will be sent in clear-text HTTP,
unless you are wrapping HTTP in something else, like SSH
port forwarding, or Tor.
--dry-run
Print debug information, but don't actually connect to `festivald`
This implies `--debug`.
--docs
Open `festival-cli` documentation locally in browser
--delete
Delete all `festival-cli` files that are on disk
This deletes all `cli` Festival folders.
The PATHs deleted will be printed on success.
--path
Print the PATHs used by `festival-cli`
All data saved by `festival-cli` is saved in these directories.
For more information, see: <https://docs.festival.pm/cli/disk.html>
-r, --reset-config
Reset the current `festival-cli.toml` config file to the default
Exits with `0` if everything went ok, otherwise shows error.
-m, --methods
Print all the JSON-RPC methods available
-v, --version
Print version
-h, --help
Print help (see a summary with '-h')