kopia lustrzana https://dev.funkwhale.audio/funkwhale/funkwhale
326 wiersze
14 KiB
ReStructuredText
326 wiersze
14 KiB
ReStructuredText
Funkwhale CLI
|
|
=============
|
|
|
|
`Funkwhale CLI <https://dev.funkwhale.audio/funkwhale/cli/>`_ is a command-line interface you can install on your local computer
|
|
to interact with any Funkwhale server via the REST API. It's especially useful if you need to do repetitive operations
|
|
or write scripts that interact with Funkwhale servers.
|
|
|
|
Here is a (non-exhaustive) list of operations you can perform via the CLI:
|
|
|
|
- Manage libraries
|
|
- Upload local files
|
|
- Retrieve and search tracks, albums and artists
|
|
- Download tracks
|
|
- Manage playlists
|
|
- Manage favorites
|
|
|
|
.. contents:: Table of Contents
|
|
|
|
Installation
|
|
------------
|
|
|
|
We provide a prebuilt binary for Linux::
|
|
|
|
curl -L "https://dev.funkwhale.audio/funkwhale/cli/-/jobs/artifacts/stable/raw/funkwhale?job=build-linux" -o /usr/local/bin/funkwhale
|
|
chmod +x /usr/local/bin/funkwhale
|
|
|
|
You can also install from source with::
|
|
|
|
pip3 install --user git+https://dev.funkwhale.audio/funkwhale/cli
|
|
# 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``.
|
|
|
|
Authentication
|
|
--------------
|
|
|
|
The CLI uses Oauth tokens to interact with the API.
|
|
|
|
To get started, you need to create an application for the CLI. To do this:
|
|
|
|
1. Log in to your Funkwhale pod.
|
|
2. Select the cog icon (:fa:`cog`) or your avatar to expand the user menu.
|
|
3. Select :guilabel:`Settings`.
|
|
4. Scroll down to the :guilabel:`Your applications` section.
|
|
5. Select :guilabel:`Register a new application` to create a new application.
|
|
6. Give your application an appropriate name (e.g. "Funkwhale CLI").
|
|
7. Give your application the permissions you require.
|
|
8. Select :guilabel:`Create application`. A screen appears showing :guilabel:`Application details`.
|
|
9. Copy the app's :guilabel:`Access token`.
|
|
|
|
Once you have your app's Access Token, you can either:
|
|
|
|
1. Run ``funkwhale login``. The CLI asks you for your token and stores it in your machine's keyring. The CLI uses this token to authenticate.
|
|
2. Explicitly pass a token to the command via the ``-t`` flag or the ``FUNKWHALE_TOKEN`` environment variable
|
|
|
|
If you use ``funkwhale login``, you can delete the local token with ``funkwhale logout``.
|
|
|
|
You can check that you are fully authenticated by running ``funkwhale users me``. It will display information relating to your user profile.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
To work, the CLI needs to be pointed to a Funkwhale server. This can be done in various ways:
|
|
|
|
- Via the ``-H https://funkwhale.domain`` flag when calling the CLI
|
|
- Via the ``FUNKWHALE_SERVER_URL`` environment variable
|
|
- Via an env file (see below)
|
|
|
|
Env file
|
|
^^^^^^^^
|
|
|
|
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.
|
|
|
|
You can also give it a path to another env file via the ``-e /path/to/.envfile`` flag or the ``ENV_FILE`` environment variable.
|
|
|
|
An env file simply contains a list of variables, using the same syntax as environment variables (comments starting with # are allowed). Example::
|
|
|
|
# ~/Music/.env
|
|
FUNKWHALE_SERVER_URL=https://my.funkwhale.server
|
|
|
|
|
|
List of configuration options
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
|
| CLI Flag | Environment variable | Example value | Description |
|
|
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
|
| ``-e``, ``--env-file`` | ``ENV_FILE`` | ``~/Music/.env`` | Path to a local env file to use for configuration |
|
|
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
|
| ``-H``, ``--url`` | ``FUNKWHALE_SERVER_URL`` | ``https://demo.funkwhale.audio`` | The URL of the Funkwhale server the CLI should contact |
|
|
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
|
| ``-t``, ``--token`` | ``FUNKWHALE_TOKEN`` | ``eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI`` | A JWT token to use for authentication |
|
|
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
|
| ``--no-login`` | ``FUNKWHALE_NO_LOGIN`` | ``true`` | Completely disable authentication and keyring |
|
|
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
|
| ``-v``, ``--verbosity`` | | One of ``CRITICAL``, ``ERROR``, | Control the verbosity (default is INFO) |
|
|
| | | ``WARNING``, ``INFO`` or ``DEBUG`` | |
|
|
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
|
| ``-q``, ``--quiet`` | ``FUNKWHALE_QUIET`` | ``true`` | Completely disable logging |
|
|
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
|
|
|
Read commands
|
|
-------------
|
|
|
|
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::
|
|
|
|
# list artists outputting a html table
|
|
funkwhale artists ls -t html
|
|
# output a github/markdown table
|
|
funkwhale artists ls -t github
|
|
|
|
Available formats are: ``fancy_grid``, ``github``, ``grid``, ``html``, ``jira``, ``latex``, ``latex_booktabs``, ``latex_raw``, ``mediawiki``, ``moinmoin``, ``orgtbl``, ``pipe``, ``plain``, ``presto``, ``psql``, ``rst``, ``simple``, ``textile``, ``tsv``, ``youtrack``
|
|
|
|
The ``-c`` or ``--column`` flag gives you control on the displayed columns::
|
|
|
|
# list artists, displaying only artist ID and number of tracks
|
|
funkwhale artists ls -c ID -c Tracks
|
|
|
|
For a given resource, the list of available columns can be found by running ``funkwhale <resource> ls --help``.
|
|
|
|
The ``-i`` or ``--ids`` flag displays only the IDs of results, one per line::
|
|
|
|
funkwhale artists ls --ids
|
|
|
|
This is especially useful in conjunction with other commands (like deletion commands) and piping.
|
|
Note that this is also technically equivalent to applying the ``--no-headers``, ``--format plain`` and ``--column ID`` flags.
|
|
|
|
Write commands
|
|
--------------
|
|
|
|
Deleting objects
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
Some resources support deletion, via commands such as ``funkwhale libraries rm`` or ``funkwhale playlists rm``, followed by one or more IDs::
|
|
|
|
# delete playlists 42 and 23
|
|
funkwhale playlists rm 42 23
|
|
|
|
By default, the ``rm`` command will ask for confirmation, but you can disable this behavior by providing the ``--no-input`` flag.
|
|
|
|
|
|
.. _API Documentation: https://docs.funkwhale.audio/swagger/
|
|
|
|
Examples
|
|
--------
|
|
|
|
Uploading local files
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**Goal**: create a library and upload all MP3 files from ``~/Music`` to it
|
|
|
|
**Commands**::
|
|
|
|
funkwhale libraries create --name "My awesome library" --visibility me
|
|
# copy the returned UUID
|
|
funkwhale uploads create <UUID> ~/Music/**/*.mp3
|
|
|
|
|
|
Favorite an entire album
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**Goal**: retrieve all the tracks from an album and add these to your favorites
|
|
|
|
**Commands**::
|
|
|
|
# retrieve the album ID
|
|
funkwhale albums ls "The Slip"
|
|
|
|
# Copy the ID, then retrieve 100 pages of tracks from that album
|
|
# get only the IDs and pipe those to the favorite creation command
|
|
funkwhale tracks ls -f "album=<ID>" --ids --limit 100 \
|
|
| xargs funkwhale favorites tracks create
|
|
|
|
|
|
Mirror an artist discography locally
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**Goal**: Download the discography of an artist locally, in the ``~/Music`` directory, in an ``Artist/Album/Track`` folder hierarchy
|
|
|
|
**Commands**::
|
|
|
|
# retrieve the artist ID
|
|
funkwhale artists ls "Nine Inch Nails"
|
|
|
|
# Copy the ID, then retrieve 100 pages of tracks from that artist
|
|
# get only the IDs and pipe those to the download command
|
|
funkwhale tracks ls -f "artist=<ID>" --ids --limit 100 \
|
|
| xargs funkwhale tracks download \
|
|
-f mp3 -d ~/Music -t "{artist}/{album}/{title}.{extension}"
|
|
|
|
|
|
Open a remote album in VLC
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
**Goal**: Variation of the previous example, but instead of downloading an artist discography, we listen to an album in VLC
|
|
|
|
**Commands**::
|
|
|
|
# retrieve the album ID
|
|
funkwhale albums ls "The Slip"
|
|
|
|
# Copy the ID, then retrieve 100 pages of tracks from that album
|
|
# get only the IDs, download the corresponding tracks and pipe the audio
|
|
# directly to VLC
|
|
funkwhale tracks ls -f "album=<ID>" --ids --limit 100 \
|
|
| xargs funkwhale tracks download \
|
|
| vlc -
|