Getting started with SeqsLab CLI

SeqsLab CLI container

The SeqsLab CLI is deployed as a Docker container. To get the container, complete the following steps:

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

docker pull seqslabmain.azurecr.io/seqslab_cli

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"

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, particularly for beginners.

docker run --rm --name cli \
    -e PRIVATE_NAME="${PRIVATE_NAME}" \
    --privileged \
    -v /mnt/:/seqslab/ \
    -it seqslabmain.azurecr.io/seqslab_cli \
    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 options -v 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 seqslabmain.azurecr.io/seqslab_cli 

The SeqsLab CLI uses dbus(external link) and gnomeKerying (external link) 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 $RANDOM | gnome-keyring-daemon --unlock
seqslab auth signin -i

Authentication

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 commands. SeqsLab CLI follows the Oauth 2.0 device code (external link) 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

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 gnome 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 authenticate 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 logout

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 more 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"
    }
]