# the executable will be available at ~/.local/bin/funkwhale
..note::
Installing from source requires you have Python 3.6 or higher available.
You can check the installation was successful by running ``funkwhale --help``. This should output
the list of available commands and the CLI description.
Basic usage
-----------
Here are a couple of commands you can try to get started:
..code-block:: shell
# Display public server info of demo.funkwhale.audio
funkwhale -H https://demo.funkwhale.audio server info
# List tracks from open.audio
funkwhale -H https://open.audio tracks ls
# Search artists matching "zebra" on open.audio
funkwhale -H https://open.audio artists ls "zebra"
Getting help
------------
The most basic way to get help is to run ``funkwhale --help``. It will list available commands, namespaces and arguments that are common to all commands.
You can also append the ``--help`` flag after any command to get more information about its arguments and options, like this: ``funkwhale albums ls --help``
The CLI offers nested commands. For instance, ``funkwhale albums`` isn't a valid command in itself, but a namespace for all albums-related commands.
To get the help of a specific namespace and list all its available commands, simply run ``funkwhale <namespace> --help``.
The CLI will try to read configuration options from a ``.env`` file in the current directory. If this file is not present, it will read the configuration options from ``~/.config/funkwhale/env`` on Linux or ``~/Library/Application Support/funkwhale/env`` on macOS.
All commands that list results - such as ``funkwhale albums ls`` or ``funkwhale tracks ls`` - share similar behaviors and sets of arguments.
Filtering
^^^^^^^^^
Results can be filtered using the ``-f`` or ``--filter`` flag. Provided values are transmitted directly in the querystring when the requests to the API is made::
# retrieve playable tracks
funkwhale tracks ls -f "playable=true"
The flag can be provided multiple times, to add multiple filter conditions::
# retrieve playable tracks with a CC-BY-SA 4.0 license
funkwhale tracks ls -f "playable=true" -f "license=cc-by-sa-4.0"
..note::
The list of supported fields for filtering depends on the resource being queried, and can be found in our `API documentation`_.
Searching
^^^^^^^^^
Any text provided after the ``ls`` command will be considered a search query and transmitted to the API::
# retrieve tracks matching the search query "Electro Swing"
funkwhale tracks ls Electro Swing
..note::
This is technically equivalent to filtering with a ``q`` parameter as described above::
funkwhale tracks ls -f "q=Electro Swing"
Ordering
^^^^^^^^
You can control the ordering of the results with the `-o` or ``--ordering`` flag::
# retrieve albums by creation date, in ascending order
funkwhale albums ls -o creation_date
..note::
Ordering in descending order is supported by prefixing the field name with ``-``, e.g: ``-o -creation_date``
..note::
The list of supported fields for ordering depends on the resource being queried, and can be found in our `API documentation`_.
Pagination
^^^^^^^^^^
You can retrieve a specific result page using the ``-p`` or ``--page`` flag::
# retrieve the second page of albums
funkwhale albums ls -p 2
You can also alter the size of the pages using the ``-s`` or ``--page-size`` flag::
# retrieve five albums
funkwhale albums ls -s 5
Sometimes, you may want to retrieve multiple pages of results at once. This is supported using the ``-l`` or ``--limit`` flag::
# retrieve the first 3 pages of albums
funkwhale albums ls -l 3
You can, of course, combine these flags::
# retrieve 3 pages of 12 albums, starting on the 4th page
funkwhale albums ls --limit 3 --page-size 12 --page 4
Output
^^^^^^
While the default output displays a human-readable table, you can customize it.
The ``--raw`` flag will simply output the raw JSON payload returned by the API server::
funkwhale artists ls --raw
The ``-h`` or ``--no-headers`` flag simply removes the table column headers.
The ``-t`` or ``--format`` flag alters the rendering of result, depending on the provided value::
