Introduction

The user objects (data formats, toolchains, experiments, etc) are stored locally in a directory with specific structure that is commonly referred to as a prefix (see “The Prefix” in section “A Hands-On-Tutorial” of BEAT documentation). The user objects on the web platform are also stored in a similar directory structure. It is possible to extract a representation from the objects on the BEAT web server and interact with them locally. Local object copies contain the same amount of information that is displayed through the web interface.

The BEAT command-line utility can be used for simple functionalities (e.g. deleting an existing algorithm or making small modifications) or advanced tasks (e.g. database development, experiment debugging) both for local objects and remote objects. In order to make this possible for the remote objects, the web platform provides a RESTful API which third-party applications can use to list, query and modify existing remote objects.

The beat command-line utility bridges user interaction with a remote BEAT web platform and locally available objects in a seamless way:

$ beat --help
Usage: beat [OPTIONS] COMMAND [ARGS]...

  The main command line interface for beat cmdline. Look below for available
  commands.

Options:
  -T, --test-mode      Assume test mode and doesn't setup the logging module
  -p, --prefix TEXT    Overrides the prefix of your local data. If not set use
                       the value from your RC file
  -c, --cache TEXT     Overrides the cache prefix. If not set, use the value
                       from your RC file
  -t, --token TEXT     Overrides the user token for server operations. If not
                       set, use the value from your RC file.
  -u, --user TEXT      Overrides the user name on the remote platform. If not
                       set, use the value from your RC file.
  -m, --platform TEXT  The URL of the BEAT platform to access.
  -e, --editor TEXT    Overrides the user editor to edit local files. If not
                       set, use the value from your environment. There are no
                       defaults for this option.
  --version            Show the version and exit.
  -v, --verbose        Increase the verbosity level from 0 (only error
                       messages) to 1 (warnings), 2 (log messages), 3 (debug
                       information) by adding the --verbose option as often as
                       desired (e.g. '-vvv' for debug).
  -?, -h, --help       Show this message and exit.

Commands:
  algorithms         Configuration and manipulation of algorithms
  cache              Configuration manipulation and display
  config             The manager for beat cmdline configuration.
  databases          Database commands
  dataformats        Configuration manipulation of data formats
  editor             † Warning: could not load plugin. See `beat editor
                     --help`.
  environments       Execution environment related commands
  experiments        experiments commands
  libraries          Configuration and manipulation of libraries
  plotterparameters  Plotterparameters commands
  plotters           Plotters commands
  protocoltemplates  Protocol template commands
  status             Shows the working folder status for different objects
  toolchains         toolchains commands

The command-line interface is separated in subcommands, for acting on specific objects. Actions can be driven to operate on locally installed or remotely available objects. You’ll find detailed information about sub-commands on specific sub-sections of this documentation dedicated to that particular type of object. In Configuration, we cover basic usage and configuration only.