NYXMMS2(1)

NAME
nycli - New Korving CLI

SYNOPSIS
nyxmms2 [command] [arguments]

DESCRIPTION
nycli is the new official CLI XMMS2 client, replacing xmms2(1).

INVOCATION

  INLINE MODE
If nycli is passed a command as an argument, that command will be interpreted and nycli will exit after it is finished.

  INTERACTIVE MODE
nycli features a powerful shell-like environment via readline that allows the user to enter commands at a prompt and have the usual cool features such as pathname expansion and line editing.

GENERAL COMMANDS

play

    Start playback.

    -h | --help
    Display command help.

pause

    Pause playback.

    -h | --help
    Display command help.

stop [-n <tracks> | -t <time>]

    Stop playback.

    -n | --tracks
    Number of tracks after which to stop playback.

    -t | --time
    Duration after which to stop playback.

    -h | --help
    Display command help.

toggle

    Toggle playback.

    -h | --help
    Display command help.

seek <time|offset>

    Seek to a relative or absolute position.

    -h | --help
    Display command help.

status [-r <time>] [-f <format>]

    Display playback status, either continuously or once.

    -r | --refresh
    Delay between each refresh of the status. If 0, the status is only printed once (default).

    -f | --format
    Format string used to display status.

    -h | --help
    Display command help.

prev [offset]

    Jump to previous song.

    -h | --help
    Display command help.

next [offset]

    Jump to next song.

    -h | --help
    Display command help.

jump [-b] <pattern|positions>

    Jump to the first media maching the pattern.

    -b | --backward
    Jump backward to the first media matching the pattern

    -h | --help
    Display command help.

info <pattern|positions>

    Display all the properties for all media matching the pattern.

    -h | --help
    Display command help.

search [-p <name> | -c <name>] [-o <prop1[,prop2...]>] [-l <prop1[,prop2...]>] <pattern>

    Search and print all media matching the pattern. Search can be restricted to a collection or a playlist by using the corresponding flag.

    -p | --playlist
    Search in the given playlist.

    -c | --collection
    Search in the given collection.

    -o | --order
    List of properties to order by (prefix by '-' for reverse ordering).

    -l | --columns
    List of properties to use as columns.

    -h | --help
    Display command help.

list [-p <name>] [pattern]

    List the contents of a playlist (the active playlist by default). If a pattern is provided, contents are further filtered and only the matching media are displayed.

    -p | --playlist
    List the given playlist.

    -h | --help
    Display command help.

add [-f [-N] [-P]] [-p <playlist> | -c <collection>] [-n | -a <pos|offset>] [pattern | paths]

    Add the matching media or files to a playlist.

    -f | --file
    Treat the arguments as file paths instead of a pattern.

    -P | --pls
    Treat the files as playlist files (implies --file.)

    -t | --pattern
    Force treating arguments as pattern.

    -N | --non-recursive
    Do not add directories recursively.

    -p | --playlist
    Add to the given playlist.

    -n | --next
    Add after the current track.

    -a | --at
    Add media at a given position in the playlist, or at a given offset from the current track.

    -h | --help
    Display command help.

remove [-p <playlist>] <pattern|positions>

    Remove the matching media from a playlist.

    -p | --playlist
    Remove from the given playlist, instead of the active playlist.

    -h | --help
    Display command help.

move [-p <playlist>] [-n | -a <pos|offset>] <pattern|positions>

    Move entries inside a playlist.

    -p | --playlist
    Playlist to act on.

    -n | --next
    Move the matching tracks after the current track.

    -a | --at
    Move the matching tracks by an offset or to a position.

    -h | --help
    Display command help.

exit

    Exit the shell-like interface.

    -h | --help
    Display command help.

help [-a] [command]

    List all commands, or help on one command.

    -a | --alias
    List aliases, or alias definition.

    -h | --help
    Display command help.

PLAYLIST COMMANDS

playlist list [-a] [pattern]

    List all playlists.

    -a | --all
    Include hidden playlists.

    -h | --help
    Display command help.

playlist

    No description

    -h | --help
    Display command help.

playlist switch <playlist>

    Change the active playlist.

    -h | --help
    Display command help.

playlist create [-p <playlist>] <name>

    Change the active playlist.

    -p | --playlist
    Copy the content of the playlist into the new playlist.

    -h | --help
    Display command help.

playlist rename [-f] [-p <playlist>] <newname>

    Rename a playlist. By default, rename the active playlist.

    -f | --force
    Force the rename of the collection, overwrite an existing collection if needed.

    -p | --playlist
    Rename the given playlist.

    -h | --help
    Display command help.

playlist remove <playlist>

    Remove the given playlist.

    -h | --help
    Display command help.

playlist clear [playlist]

    Clear a playlist. By default, clear the active playlist.

    -h | --help
    Display command help.

playlist shuffle [playlist]

    Shuffle a playlist. By default, shuffle the active playlist.

    -h | --help
    Display command help.

playlist sort [-o <order>] [playlist]

    Sort a playlist. By default, sort the active playlist.

    -o | --order
    List of properties to sort by (prefix by '-' for reverse sorting).

    -h | --help
    Display command help.

playlist config [-t <type>] [-s <history>] [-u <upcoming>] [-i <coll>] [playlist]

    Configure a playlist by changing its type, attributes, etc. By default, configure the active playlist.

    -t | --type
    Change the type of the playlist: list, queue, pshuffle.

    -s | --history
    Size of the history of played tracks (for queue, pshuffle).

    -u | --upcoming
    Number of upcoming tracks to maintain (for pshuffle).

    -i | --input
    Input collection for the playlist (for pshuffle). Default to 'All Media'.

    -h | --help
    Display command help.

COLLECTION COMMANDS

collection list

    List all collections.

    -h | --help
    Display command help.

collection

    No description

    -h | --help
    Display command help.

collection show <collection>

    Display a human-readable description of a collection.

    -h | --help
    Display command help.

collection create [-f] [-a | -e] [-c <collection>] <name> [pattern]

    Create a new collection. If pattern is provided, it is used to define the collection. Otherwise, the new collection contains the whole media library.

    -f | --force
    Force creating of the collection, overwrite an existing collection if needed.

    -c | --collection
    Copy an existing collection to the new one.

    -e | --empty
    Initialize an empty collection.

    -h | --help
    Display command help.

collection rename [-f] <oldname> <newname>

    Rename a collection.

    -f | --force
    Force renaming of the collection, overwrite an existing collection if needed.

    -h | --help
    Display command help.

collection remove <collection>

    Remove a collection.

    -h | --help
    Display command help.

collection config <collection> [attrname [attrvalue]]

    Get or set attributes for the given collection. If no attribute name is provided, list all attributes. If only an attribute name is provided, display the value of the attribute. If both attribute name and value are provided, set the new value of the attribute.

    -h | --help
    Display command help.

SERVER COMMANDS

server import [-N] <path>

    Import new files into the media library. By default, directories are imported recursively.

    -N | --non-recursive
    Do not import directories recursively.

    -h | --help
    Display command help.

server

    No description

    -h | --help
    Display command help.

server remove <pattern>

    Remove the matching media from the media library.

    -h | --help
    Display command help.

server rehash [pattern]

    Rehash the media matched by the pattern, or the whole media library if no pattern is provided

    -h | --help
    Display command help.

server config [name [value]]

    Get or set configuration values. If no name or value is provided, list all configuration values. If only a name is provided, display the content of the corresponding configuration value. If both name and a value are provided, set the new content of the configuration value.

    -h | --help
    Display command help.

server property [-i | -s | -D] [-S] <mid> [name [value]]

    Get or set properties for a given media. If no name or value is provided, list all properties. If only a name is provided, display the value of the property. If both a name and a value are provided, set the new value of the property. By default, set operations use client specific source and list, display operations use source-preference. Use the --source option to override this behaviour. By default, the value will be used to determine whether it should be saved as a string or an integer. Use the --int or --string flag to override this behaviour.

    -i | --int
    Force the value to be treated as integer.

    -s | --string
    Force the value to be treated as a string.

    -D | --delete
    Delete the selected property.

    -S | --source
    Property source.

    -h | --help
    Display command help.

server plugins

    List the plugins loaded in the server.

    -h | --help
    Display command help.

server volume [-c <name>] [value]

    Get or set the audio volume (in a range of 0-100). If a value is provided, set the new value of the volume. Otherwise, display the current volume. By default, the command applies to all audio channels. Use the --channel flag to override this behaviour.

    -c | --channel
    Get or set the volume only for one channel.

    -h | --help
    Display command help.

server stats

    Display statistics about the server: uptime, version, size of the medialib, etc

    -h | --help
    Display command help.

server sync

    Force the saving of collections to the disk (otherwise only performed on shutdown)

    -h | --help
    Display command help.

server shutdown

    Shutdown the server.

    -h | --help
    Display command help.

ALIASES

A list of command aliases are read from the configuration file in the section [alias] at runtime. The syntax of nycli aliases are somewhat similar to bash and other shells. An alias is defined by a list of semi-colon separated commands and arguments. Parameter expansion is supported (see EXPANSION below).

The default configuration includes the following aliases:

addpls

    add -f -P $@

    -h | --help
    Display command help.

current

    status -f $1

    -h | --help
    Display command help.

server kill

    server shutdown

    -h | --help
    Display command help.

mute

    server volume 0

    -h | --help
    Display command help.

repeat

    seek 0

    -h | --help
    Display command help.

ls

    list

    -h | --help
    Display command help.

quit

    exit

    -h | --help
    Display command help.

clear

    playlist clear

    -h | --help
    Display command help.

scap

    stop ; playlist clear ; add $@ ; play

    -h | --help
    Display command help.

  EXPANSION
    Positional Parameters
    An alias can use positional parameters, for example:

    foo = add -f $1 $3

    foo ctkoz.ogg and slre.ogg

    Will result in:

    add -f ctkoz.ogg slre.ogg

    Special Parameters
    $@
        This expands to all parameters passed to the alias.

CONFIGURATION

All control characters are interpreted as expected, including ANSI escape sequences.

PROMPT
    String to use as a prompt in INTERACTIVE MODE

SHELL_START_MESSAGE
    Boolean, if true, nycli will display a greeting message and basic help when started in INTERACTIVE MODE

SERVER_AUTOSTART
    Boolean, if true nycli will attempt to start xmms2d(1) if it's not running already.

AUTO_UNIQUE_COMPLETE
    Boolean, complete an abbreviation of a command and it's arguments. For example: `serv vol 42' will complete to `server volume 42'. (Note: Abbreviations must be non-ambiguous)

PLAYLIST_MARKER
    String to use to mark the current active entry in the playlist

GUESS_PLS
    Boolean, try to guess if the URL is a playlist and add accordingly. (Not reliable)

CLASSIC_LIST
    Boolean, format list output similar to the classic cli.

CLASSIC_LIST_FORMAT
    String to format classic list output with.

STATUS_FORMAT
    String to format status output with.

HISTORY_FILE
    File to save command history to.

FILES
$XDG_CONFIG_HOME/xmms2/clients/nycli.conf
    The configuration file for nycli

$XDG_CACHE_HOME/xmms2/nyxmms2_history
    Default command history file if HISTORY_FILE is unset.

BUGS
Please report all bugs at http://bugs.xmms2.xmms.se

AUTHORS
Igor Assis, Anders Waldenborg, Anthony Garcia, Sebastien Cevey, and Jonne Lehtinen

See the AUTHORS file in the XMMS2 source distribution for more info.

The blame for this man page is on Anthony.

If you contributed and feel you should be listed here please send me a mail.