Skip to content

Hands-on: CLI - Getting Started

  • 15 min
  • Moderate
Overview

The goal of this hands-on tutorial is to get the LabID Python Client installed on your machine and be able to retrieve some basic information from LabID.

  • Install the package from Gitlab
  • Setup credentials
  • Searching and listing entities
Prerequisites

We assume that you are familiar with conda or with Python Virtual Environments. For this tutorial you will need a package manager like conda, and git installed on your machine.

The client we will install can be found at LabID Python Client repository.

Step 1. Set up a conda environment

Use conda to compartment software on your computer

We advise creating a conda environment to avoid version mismatch and make sure the proper version of python is used.

  • On your computer, create a conda virtual environment with Python>=3.11
    conda create -n labid-cli python=3.11 jq=1.6
  • Activate the virtual environment
    conda activate labid-cli

Step 2. Clone the LabID Python Client

  • Open a terminal and go to a directory where you want to store the files for the python client.
    Any directory is suitable, but we recommend using your Documents
    cd ~/Documents
  • Clone the repo
    this will create a subdirectory labid-cli
    git clone https://gitlab.com/lab-integrated-data/labid-cli.git
  • Move to the labid-cli directory
    cd labid-cli

We will now select the last released version (for this project, versions are available via tags).
We first need to get the list of released versions (the list of tags).

  • Get list of released versions
    git fetch --tags
  • Select the last released version
    git checkout $(git describe --abbrev=0 --tags)
Note that to install a specific version, you can directly provide the version tag (ex with v26.01.1)
git checkout v26.01.1
  • Install the client
    pip install -e .

Note : The -e will install the package as "editable", such that the client can easily be updated by checking out the last released version.

Summarized 
conda create -n labid-cli python=3.11 jq=1.6
conda activate labid-cli
cd ~/Documents
git clone https://gitlab.com/lab-integrated-data/labid-cli.git
cd labid-cli
git fetch --tags
git checkout $(git describe --abbrev=0 --tags)
pip install -e .

Step 3. Configure the client

The client needs to be configured to communicate with the LabID.
Here we will configure our client to communicate with the training instance.

  • Execute the following command first, 
    labid config setup

It will first prompt for the url of the training instance, paste https://labid-demo.embl.de then enter.
Next step is entering the username, you can use any username in the range trainee1...trainee100, again press enter.
Then the password 123456 and press enter.
Finally the unix group, which can be any value for now.

Trainee credentials

The client is now setup with the training credentials.

Every action done with the Python client will be authenticated as this training user.

Step 4. Retrieving data

We can now start querying the training instance.
Try the following commands and see what result you get.

  • labid get item --id <uuid> (Replace <uuid> with any of the IDs from the search result or take one from the UI)
  • labid get instruments --type MICROSCOPE | jq
Format of the retrieved information

The information is obtained in the JSON format. This is the base format for API responses. Using jq the data is transformed in a readable and parsable way. The information retrieved is similar to that retrieved by the UI client. In fact, our UI is solely retrieving and sending data from and to the API!

As such, the python client or any other client one would write, can retrieve the same and possibly more data from the API.

To see what endpoints the UI uses, open up the network tab of your browser and inspect the requests. You can repeat these requests, by using a 'manual' REST client like Insomnia.

Write operations are currently not available

Currently, the client only does GET operations, meaning readonly. Write operation are technically possible and we will start supporting them in future releases.

Please contact us when using the API for the first time so that a test/development instance is setup for you. Our API will protect for most invalid data, but as our UI has been our sole consumer/producer of API calls, we may be missing some validations.

Do not test against production! We will find you

In the next hands on we will look at different functionality that is exclusive to the CLI like a ArrayExpress like export and linking files.