Merge branch 'cli-docs' into 'master'
Cli docs See merge request funkwhale/funkwhale!863
This commit is contained in:
Eliot Berriot
commit
21b4bcca25
|
|
@ -20,91 +20,73 @@ review_front:
|
|||
image: node:11
|
||||
when: manual
|
||||
allow_failure: true
|
||||
variables:
|
||||
BASE_URL: /-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/front-review/
|
||||
VUE_APP_ROUTER_BASE_URL: /-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/front-review/
|
||||
VUE_APP_INSTANCE_URL: $REVIEW_INSTANCE_URL
|
||||
before_script:
|
||||
- curl -L -o /usr/local/bin/jq https://github.com/stedolan/jq/releases/download/jq-1.5/jq-linux64
|
||||
- chmod +x /usr/local/bin/jq
|
||||
- rm -rf front-review
|
||||
- mkdir front-review
|
||||
- cd front
|
||||
script:
|
||||
- yarn install
|
||||
- yarn run i18n-compile
|
||||
# this is to ensure we don't have any errors in the output,
|
||||
# cf https://dev.funkwhale.audio/funkwhale/funkwhale/issues/169
|
||||
- VUE_APP_INSTANCE_URL=$REVIEW_INSTANCE_URL yarn run build | tee /dev/stderr | (! grep -i 'ERROR in')
|
||||
- mkdir -p /static/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
|
||||
- cp -r dist/* /static/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
|
||||
- yarn run build | tee /dev/stderr | (! grep -i 'ERROR in')
|
||||
- cp -r dist/* ../front-review
|
||||
artifacts:
|
||||
expire_in: 2 weeks
|
||||
paths:
|
||||
- front-review
|
||||
cache:
|
||||
key: "funkwhale__front_dependencies"
|
||||
paths:
|
||||
- front/node_modules
|
||||
- front/yarn.lock
|
||||
environment:
|
||||
name: review/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
|
||||
url: http://front-$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG.$REVIEW_DOMAIN
|
||||
on_stop: stop_front_review
|
||||
only:
|
||||
- branches
|
||||
tags:
|
||||
- funkwhale-review
|
||||
- docker
|
||||
environment:
|
||||
name: review/front/$CI_COMMIT_REF_NAME
|
||||
url: http://$CI_PROJECT_NAMESPACE.pages.funkwhale.audio/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/front-review/index.html
|
||||
|
||||
stop_front_review:
|
||||
stage: review
|
||||
script:
|
||||
- rm -rf /static/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG/
|
||||
variables:
|
||||
GIT_STRATEGY: none
|
||||
when: manual
|
||||
only:
|
||||
- branches
|
||||
environment:
|
||||
name: review/front/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
|
||||
action: stop
|
||||
tags:
|
||||
- funkwhale-review
|
||||
|
||||
review_docs:
|
||||
stage: review
|
||||
image: python:3.6
|
||||
when: manual
|
||||
allow_failure: true
|
||||
image: python:3.6
|
||||
variables:
|
||||
BUILD_PATH: "../public"
|
||||
BUILD_PATH: "../docs-review"
|
||||
before_script:
|
||||
- rm -rf docs-review
|
||||
- mkdir docs-review
|
||||
- cd docs
|
||||
- apt-get update
|
||||
- apt-get install -y graphviz
|
||||
- pip install sphinx
|
||||
|
||||
script:
|
||||
- ./build_docs.sh
|
||||
cache:
|
||||
key: "$CI_PROJECT_ID__sphinx"
|
||||
paths:
|
||||
- "$PIP_CACHE_DIR"
|
||||
script:
|
||||
- ./build_docs.sh
|
||||
- mkdir -p /static/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
|
||||
- cp -r $CI_PROJECT_DIR/public/* /static/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
|
||||
environment:
|
||||
name: review/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
|
||||
url: http://docs-$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG.$REVIEW_DOMAIN
|
||||
on_stop: stop_docs_review
|
||||
artifacts:
|
||||
expire_in: 2 weeks
|
||||
paths:
|
||||
- docs-review
|
||||
only:
|
||||
- branches
|
||||
tags:
|
||||
- funkwhale-review
|
||||
- docker
|
||||
environment:
|
||||
name: review/docs/$CI_COMMIT_REF_NAME
|
||||
url: http://$CI_PROJECT_NAMESPACE.pages.funkwhale.audio/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/docs-review/index.html
|
||||
|
||||
stop_docs_review:
|
||||
stage: review
|
||||
script:
|
||||
- rm -rf /static/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG/
|
||||
variables:
|
||||
GIT_STRATEGY: none
|
||||
when: manual
|
||||
only:
|
||||
- branches
|
||||
environment:
|
||||
name: review/docs/$CI_PROJECT_PATH_SLUG-$CI_BUILD_REF_SLUG
|
||||
action: stop
|
||||
tags:
|
||||
- funkwhale-review
|
||||
|
||||
black:
|
||||
image: python:3.6
|
||||
|
|
|
|||
|
|
@ -0,0 +1,64 @@
|
|||
Funkwhale CLI 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 -
|
||||
|
|
@ -0,0 +1,252 @@
|
|||
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/master/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"
|
||||
|
||||
More examples
|
||||
-------------
|
||||
|
||||
You should find enough in this reference document to start using the CLI on your own.
|
||||
|
||||
However, we've compiled :doc:`a list of example uses of the CLI <examples>` with advice and explanations, if you want to check it out ;)
|
||||
|
||||
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 JWT tokens to interact with the API. You can either:
|
||||
|
||||
1. Run ``funkwhale login``, which will ask you your Funkwhale username and password and store a JWT token in your local keyring. This token will be used automatically afterwards.
|
||||
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, or from ``~/.config/funkwhale/env``.
|
||||
|
||||
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 |
|
||||
+--------------------------------------+------------------------------------------------+--------------------------------------------+---------------------------------------------------------------+
|
||||
|
||||
Listing results
|
||||
---------------
|
||||
|
||||
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.
|
||||
|
||||
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/
|
||||
|
|
@ -28,6 +28,7 @@ Using Funkwhale
|
|||
radios
|
||||
follow
|
||||
apps
|
||||
../cli/index
|
||||
|
||||
Troubleshooting Issues
|
||||
----------------------
|
||||
|
|
|
|||
|
|
@ -3,9 +3,11 @@ import Router from 'vue-router'
|
|||
|
||||
Vue.use(Router)
|
||||
|
||||
console.log('PROCESS', process.env)
|
||||
export default new Router({
|
||||
mode: 'history',
|
||||
linkActiveClass: 'active',
|
||||
base: process.env.VUE_APP_ROUTER_BASE_URL || '/',
|
||||
routes: [
|
||||
{
|
||||
path: '/',
|
||||
|
|
@ -552,6 +554,10 @@ export default new Router({
|
|||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
path: '*/index.html',
|
||||
redirect: '/'
|
||||
},
|
||||
{
|
||||
path: '*',
|
||||
component: () =>
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ if (process.env.BUNDLE_ANALYZE === '1') {
|
|||
plugins.push(new BundleAnalyzerPlugin())
|
||||
}
|
||||
module.exports = {
|
||||
baseUrl: '/front/',
|
||||
baseUrl: process.env.BASE_URL || '/front/',
|
||||
pages: {
|
||||
embed: {
|
||||
entry: 'src/embed.js',
|
||||
|
|
|
|||
Loading…
Reference in New Issue