Pull and run the SeqsLab CLI

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( external link ) and gnome-keyring () 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

Daemon Mode#

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

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

Tip

Specifying the Microsoft Entra tenant (optional)

SeqsLab CLI respects the environment variable AZUREAD_OAUTH2_TENANT to determine which Microsoft Entra tenant to use during sign-in.

Single-tenant accounts: The tenant is usually auto-resolved; you typically do not need to set this variable.
Multi-tenant or guest scenarios (for example, your account’s home tenant A is a guest in tenant B): Set AZUREAD_OAUTH2_TENANT to the target tenant ID to direct the sign-in. This is the recommended practice for multi-tenant sign-ins.

Example:

export AZUREAD_OAUTH2_TENANT="8a36ae05-xxxx-0000-xxxx-2313e33qc9ee"
seqslab auth signin -i

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 the following command:

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