Pull and run the SeqsLab CLI

The SeqsLab CLI is deployed as a Docker container.

Objective

This tutorial will help you download and run an instance of the SeqsLab command line interface (CLI) tool.

Prerequisites

• A command line interface (CLI) tool such as the Windows Command Prompt or the Mac Terminal

• A SeqsLab workspace. For details, see Create a SeqsLab workspace.

1. Pull the container

To get the container, complete the following steps:

a. Pull the image from the official Atgenomix Docker repository in Github.

docker pull ghcr.io/atgenomix/seqslab-cli:latest

b. Find and define the subdomain name of the SeqsLab API as PRIVATE_NAME. For example, the domain “atgenomix.seqslab.net” uses “atgenomix” as its PRIVATE_NAME.

export PRIVATE_NAME="yourCompanyName"

2. Run the SeqsLab CLI Container

After the setup, you can launch the SeqsLab CLI container via Docker run commands. The SeqsLab CLI container supports both interactive and CLI modes.

Interactive Mode

The interactive mode provides a fish-style auto-completion function in a python interpreter context that is more user friendly, especially for beginners.

docker run --rm --name cli \
    -e PRIVATE_NAME="${PRIVATE_NAME}" \
    --privileged \
    -v /mnt/:/seqslab/ \
    -it ghcr.io/atgenomix/seqslab-cli:latest \
    dbus-run-session /etc/init_container.sh 

Running this command results to a python interpreter-like interface where you can use the SeqsLab CLI in interactive mode. The above docker run command involves -v options to bind-mount volume /mnt from the host directory, so that datasets stored under host directory /mnt can be accessed from the container in the dataset management step. If no data upload or data download operation is planned, the -v option can be omitted.

CLI Mode

The CLI mode provides a shell-based interface where you can issue commands at the shell prompt. With the shell-based interface, the CLI mode provides the possibility for automation integration with your existing scripts, from the sequencers to the subsequent dry lab operations.

Launch SeqsLab CLI container in CLI mode using the following command:

docker run --rm --name cli \
    -e PRIVATE_NAME="${PRIVATE_NAME}" \
    --privileged \
    -v /mnt/:/seqslab/ \
    -it ghcr.io/atgenomix/seqslab-cli:latest 

The SeqsLab CLI uses dbus() and gnomeKerying () to do session-based credentials and secrets management. You will need to manually create a dbus session and unlock gnome-keyring, then run SeqsLab CLI under the same session.

dbus-run-session -- bash
echo YOUR_SESSION_PASSWORD | gnome-keyring-daemon --unlock
seqslab auth signin -i

3. Authenticate the session

Whether you launch the SeqsLab CLI container in interactive or CLI mode, you will need to sign in to authenticate the session before running any SeqsLab CLI command. SeqsLab CLI follows the Oauth 2.0 device code () authentication process in a headless Linux system. After authentication, the SeqsLab CLI will get an API token from the SeqsLab API. The token generally expires within 2 hours. The longest refresh lifespan is one day. After the API token expires, you will need to manually sign in again to use SeqsLab CLI.

To authenticate your session, run the following command:

seqslab auth signin -i

Note: If you are not logging into your Azure primary domain, please export AZUREAD_OAUTH2_TENANT=‘Microsoft Entra Domain’. For example: atgenomix.com.

export AZUREAD_OAUTH2_TENANT='atgenomix.com'
seqslab auth signin -i

The SeqsLab CLI supports daemon mode sign-in for long-running, non-interactive processes. This allows you to get a client-credential encoded API token and that you can keep in the secret keyring.

Important

The daemon mode sign-in must be used in a secure environment, such as on the console of a server that is securely protected in a facility. All users must sign out at the end of a long-running process to delete the client credentials.

To authenticate your session in daemon mode, run the following command:

seqslab auth signin -i -d

To use auth daemon to silently refresh the session and get a new API token for an unlimited period, run the following command:

seqslab auth daemon

Remember to sign out at the end of a long-running process to clear the client-credential stored in the secret keyring.

seqslab auth signout

SeqsLab backend resources are managed using a concept called workspace, which defines the computation, storage, and container registry resources. The workspace can be created using SeqLab CLI command workspace create. For details, see Create a SeqsLab workspace.

Most SeqsLab CLI commands require you to provide the workspace information. To list existing workspaces and get the workspace name, use following command:

seqslab workspace list
[
    {
        "id": "/subscriptions/xxxxxxxxx-aaaa-bbbb-cccc-zzzzzzzzzzzz/resourceGroups/seqslabwus2",
        "name": "seqslabwus2",
        "location": "westus2"
    }
]