Introduction to Command Line Interface (CLI)

About this article

Most of our researchers use the User Interface (UI) to access UK Biobank’s Research Analysis Platform (UKB-RAP). However, if you need more flexibility or want to automate your work, you can use the Command Line Interface (CLI) to interact with the platform directly from your computer.
This article explains what CLI is, how to access it, and how it can support more advanced or automated workflows.

Why use CLI?

CLI is a text-based interface that allows you to interact with UKB-RAP using typed commands.
While most standard tasks can be completed through UI, CLI offers greater flexibility and control. It’s particularly useful for more complex tasks including automation and building custom workflows.
For example, you could use CLI to run Swiss Army Knife on multiple files at once, or to search your project directory using a single command. CLI interacts with the same Application Programming Interface (API) server as UI, but allows you to work directly from your local machine.

Setting up CLI

To access UKB-RAP via CLI:

1. Make sure you have Python 3 or later installed on your machine.
2. Install the DNAnexus Platform SDK (also called dx toolkit).
3. Log in to the platform from your computer via your preferred CLI. You can do this either via dx login, or via personal token.

Log in via dx

1. Type dx login into the command prompt.
2. You will be prompted for your UKB-RAP credentials, including your username and password. If you have two-factor authentication set up, you may also be asked for a verification code.
3. Select the project you want to work with from your list. If the project isn’t on the first page, type m for more options.

For example:

Log in via token

Generate a token for your project/s if you don't have one already:

Go into your Account Security area via the User Interface, and select API tokens.

Click New Token and fill in the details in the pop up, including which projects you want to be accessible. This will generate a token to input into CLI.

Once you have your token, type the following into your command prompt:

dx login --token [your token here]

Closing CLI

Once you are finished working with the CLI, type dx logout to end your session.

Some dx commands to get you started

Note: all commands begin with "dx".

dx help

Retrieves a listing of all the different commands available in the dx toolkit.

Get help on specific commands by following the command with - -help. E.g.:

dx find --help

dx whoami

Tells you which account you are using.

dx select

Allows you to choose the project you wish to use.

You can use dx select --level to show projects for which you have a certain level of access. E.g.:

dx select --level CONTRIBUTE

dx run

Allows you to run an applet, app, or workflow

dx download

Allows you to download the contents of a file object or multiple objects from the UKB-RAP.

dx find

Search functionality allowing you to generate a list of things such as your current jobs, projects or data objects within your project.

dx mv

Allows you to move or rename files or folders, as well as copy data between your projects.

Command index

Click here for a full index of commands.

Note: if a command is not available in the API, it will not be available via CLI.