(cli:tutorial-getting-started)=
# 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 [](cli:create-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](https://github.com/orgs/atgenomix/packages/container/package/seqslab-cli).  

```
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.   

(cli:interactive)=
### 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](https://www.freedesktop.org/wiki/Software/dbus/)(![external link](../images/external-link.png)) and
[gnome-keyring](https://wiki.gnome.org/Projects/GnomeKeyring) (![external link](../images/external-link.png)) 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](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-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:
```shell
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:

```shell
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 [](cli:create-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:

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