Skip to content

Getting Started

Installation

Personal

The cli can easily be installed following one of the options described in the cli repository.

Institution wise (e.g. EMBL)

When a LabID instance is globally available for an institution, like at EMBL, it makes sense to have a global cli installation.

On a unix system, the procedure is similar to having a personal installation with a few tricks:

  • use a technical user to install the cli
  • install in a shared folder on the local network
  • follow the 'Development' install procedure i.e. 
    # create a virtualenv/conda env 
conda create -n labid-cli python=3.10 && conda activate labid-cli
# clone repo
git clone https://gitlab.com/lab-integrated-data/labid-cli.git
cd labid-cli
# install
pip install -e .
  • create a labid shell script wrapper (adapt to your settings) 
    #! /usr/bin/env bash
set -e
#enable conda --if needed
source path/to/conda.sh
# activate conda env 
conda activate path/to/conda/envs/labid-cli
# fwd args to labid executable
labid "$@"
  • store it on a globally accessible share (e.g. /shared/labid) and chmod 755 /shared/labid
  • Rename labidcli.ini.template to labidcli.ini and edit values to reflect your installation
  • Voila! The cli can be executed from any server mounting /shared/ by simply calling /shared/labid --help

Executing cli commands

The labid CLI articulate around different modules that in turn offer different commands.

A command line will look like: 

> labid [GLOBAL_OPTIONS] <MODULE> <COMMAND> [ARGS]...

The different cli modules and commands

The different modules are listed when executing labid --help:

  • config Create and manage your connection configurations
  • export Export links and dataset metadata
  • get Get items of any types as JSON representation
  • register Register raw and derived datasets
  • validate Validate 'initialized' assays

To learn the different commands offered by a module, execute labid <module> --help. Commands are listed under the 'commands' section.

For example, the commands of the config module are clean, refresh, setup,...:

> labid config --help

Usage: labid config [OPTIONS] COMMAND [ARGS]...

  Create and manage your connection configurations

Options:
  --help  Show this message and exit.

Commands:
  clean    wipe the config file
  refresh  Refresh the login token of the default connection
  setup    Set up a configuration file containing important LabID...
  show     Show current configuration information
  switch   Switch the server to connect

Global options

Global options must be placed before the command name; and can be discovered in output of labid --help under the 'Options' section.

> labid --help
[...]
Options:
  --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Sets the verbose level  [default: WARNING]
  --log-file TEXT                 file path to redirect logging events (by
                                  default logging goes to stderr)
  -v, --version                   Show the application's version and exit.
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.
  --help                          Show this message and exit.

[...]

First time use (setting up)

To start using the labid CLI, you'll first need to run labid config setup to save your LabID connection parameters.

  • answer the questions at the prompt (or accept the default).
  • this will create a .labid/labidapi.yml in your home folder.
  • This ~/.labid/labidapi.yml stores your connection details
    • this file stores a 'JWT' token i.e. not your password
    • labid should have created this files with permissions restricted to you.
    • It is always a good idea to double-check the permissions on this file and make sure no one else can read it

JWT tokens expire...

The JWT expire after some time (this depends on how your admin has setup the LabID server). When this happens please use labid config refresh and follow instructions to renew your JWT. If you need a token that never expire (or lives longer than a JWT), please ask your admin to generate an API KEY for your user; then replace the JWT token in the ~/.labid/labidapi.yml with this API Key