Elabapy-CLI

elabapy-cli is a library for use in tandem with elabFTW. It uses the official elabapy and adds a user-friendly command line interface (CLI). The library is written in Python 3 and works under both Linux and Windows. The functionality and parts of the code are adapted from the Kadi-APY.

Installation

The library can be installed using pip3 (or pip, if there is no dedicated version of pip for Python 3 installed), which generally comes bundled with Python installations. Python version >= 3.6 is required.

pip3 install elabapy-cli

When installing the library from source for development, it is recommended to install the library in editable mode, which simply creates a link to the sources so all changes are reflected in the installed package immediately. The command will also install some additional development dependencies as defined in setup.py.

pip3 install -e .[dev]

Running the installations inside a virtual environment is recommended, see Virtualenv for more information.

Make sure the elabapy command is runnable from anywhere. Depending on the type of installation and if a virtual environment is used or not, the PATH system variable may need to be adapted accordingly to include the path the executable resides in. For example, the following command can be used on Linux, assuming the executable resides in ~/.local/bin:

export PATH=${HOME}/.local/bin:${PATH}

This line can also be added to .bashrc so it will be executed each time a new terminal is opened:

echo 'export PATH=${HOME}/.local/bin:${PATH}' >> ${HOME}/.bashrc

On Windows, the PATH can be modified permanently by editing the respective environment variable in the advanced system settings of the control panel.

Usage

The CLI can be used directly in the terminal. The first entry point to the CLI is given by running:

elabapy

All commands concerning different resources are available as various subcommands. For example, all subcommands to work with experiments can be listed by running:

elabapy experiments

The information on how to create an experiment can be accessed via:

elabapy experiments create --help

Autocomplete can be activated via

elabapy config activate-autocompletion

for fish, Zsh, Bash and PowerShell.

Connecting an elabFTW instance

To connect an instance of elabFTW to a local installation of this library, the host of the elabFTW instance as well as a personal access token (PAT) are required.

The host is the fully qualified domain name of the elabFTW instance with the ending /api/v1/.

A PAT (API key) can be created via the web interface of an elabFTW instance in the menu found in User panel > API KEYS and will operate with the same permissions as the user that created the token.

You can run

elabapy config create

which creates the file .elabconfig in you home directory. Open the file to fill in the host and PAT information. E.g.:

[global]
verify = True
default = my_instance

[my_instance]
host = https://example.com/api/v1/
pat = <your PAT>

[my_second_instance]
host = https://example2.com/api/v1/
pat = <your second PAT>

When using the CLI, you can choose the instance to use. The default is defined by the key default in the section [global].