Using the Command Line Interface

Jump to:

Step 1 - Prerequisites and setup

Step 2 - Submit a job

Step 3 - Wait (and monitor)

Step 4 - Retrieve Output

Step 5 (optional) - Log out

Step 1 - Prerequisites and setup

To use the imputation service, you’ll need to make sure both your system and any inputs you hope to pass through the service meet certain prerequisites.

Install the terralab-cli tool

• Ensure Python 3.12 or higher is installed on your computer (see www.python.org).
• To install, we suggest running pip install terralab-cli in your command line (or use your preferred Python package manager)

If your chosen environment is using a version of Python less than 3.12, you can create a virtual Python environment via conda (see the conda documentation). For example:

# make new virtual environment
conda create -n my_python312_env python=3.12

# initiate environment
conda init

# update your shell environment using the path from the previous command's output
source [MODIFIED_PATH]  # e.g. source /home/jupyter/.bashrc

# activate the conda environment 
conda activate my_python312_env

# install terralab-cli
pip install terralab-cli

Authenticate with the CLI

If you are running on a local machine that has access to a web browser in the same environment, you will be prompted to log in when running a terralab command. Proceed to the next step.

If you are running inside a remote environment (such as your institutional cluster or a cloud environment), run terralab login and follow the instructions to authenticate before proceeding to the next step.

Prepare to submit a job

Before actually submitting your first job, use the following commands to learn about the pipeline, including additional instructions for use.

• terralab pipelines list - get all available pipelines to use.  the value under the name column is what you can use for further commands

terralab pipelines list

• terralab pipelines details [PIPELINE_NAME] - retrieve a number of details about the a pipeline, including an example command for submitting a new job.

terralab pipelines details array_imputation

• terralab submit --help - review information about the submit command

terralab submit --help

Step 2 - Submit a job

To submit a job to the imputation service, use the command terralab submit [PIPELINE_NAME] [PIPELINE_INPUTS] where PIPELINE_NAME and PIPELINE_INPUTS can be copied from the terralab pipelines details command.

Example command

terralab submit array_imputation --agreeToTerms --multiSampleVcf YOUR_VALUE_HERE --outputBasename YOUR_VALUE_HERE --description 'YOUR JOB DESCRIPTION HERE'

The --agreeToTerms flag is used to agree to the service's Terms of Service.

HINT: Time to run the job
Note that upon submission, this command will begin by uploading your input file. This means that the time it takes to run this job will be affected by the size of the input file, as well as your internet connection. For guidance on minimizing file size, check out the troubleshooting article.

Step 3 - Wait (and monitor)

Once you’ve submitted a job to the imputation service, it will take at least a few hours to complete the job, depending on the number of samples you are analyzing. In the meantime, you can submit additional jobs, and you can use the commands below to track how many imputation jobs you have going and the status of any particular job.

To retrieve all jobs you’ve submitted

terralab jobs list

To return the status and details of a particular job

terralab jobs details JOB_ID

Step 4 - Retrieve Output

The imputation job should complete within 24 hours, depending on the number of samples in your input. Once it completes, you’ll receive an email notification to the address linked to your Terra account indicating whether the job is completed successfully or has experienced some failure. If successful, the outputs will be stored for you in our cloud for 14 days.

How to download the output using the CLI

To download the output for a particular job, use the terralab download command. You’ll just need the job ID for the job of interest. You can find the job ID either in the automated email you received upon the job’s completion, or you can use the terralab jobs list command described in the previous step. See the Pipeline Overview documentation for what outputs to expect.

To download all the outputs for a job

terralab download JOB_ID

Step 5 (optional) - Log out

The service will keep you logged in for two weeks. This command stops the CLI from authenticating as you when communicating with the service, and should be used when you're done if you're running terralab in a shared environment.

To log out of the CLI

terralab logout