Using files and apps with Command Line Interface (CLI)

About this article

This article outlines best practices for managing files when using the Command Line Interface (CLI) with the UKB-RAP. It covers:

Finding, accessing, and sorting files
Project structure
File paths
Commands for file manipulation

For a introduction to CLI, see our article here.

Getting started

When working with CLI always use a full file path, ideally starting with your project ID. For example:

[project ID]:/Bulk/Genotype/Results/CEL file

You can find your project ID in the projects tab. Select your associated project and look in the info panel on the right-hand side.

There are various file and directory exploration commands available on UKB-RAP, similar to Unix. These include:

dx pwd: Show the current working directory.
dx cd: Change directory.
dx ls: List files in a directory.
- You can also list file IDs using -la
dx env: Display environment variables.

Example:

In the below screenshot, we have used dx pwd to get information on the present working directory. Here, the working directory is DA Test Project. Then, we can use dx ls to list the files present within the working directory. In this case, there are 3 folders called Notebook_archive, Notebook_snapshots and table-exporter. Typing $dx ls - la will also list all of your file and project IDs.

If we wanted to change the working directory to one of these folders, you could use dx cd, followed by dx ls to check for the files in the new directory.

Below, you can see there is a notebook called Export-participant-data_Python_2025-0 inside the .Notebook_archive folder.

File management: moving data and exploring contents

There are several commands you can use to move data onto and off the platform, as well as to explore file contents.

dx mkdir: create a new directory.
- For example:
- This creates a folder within the present working directory called test_folder
dx upload: upload a file to the platform.
- For example, to upload a file called file.txt from your local machine to the UKB-RAP, you could use the following command:

dx download: download a file from the platform.
- Please note- you are not able to download individual data from the UKB-RAP. However, you are permitted to download summary data, such as statistics and graphs. For example, we can download the file.txt that we just uploaded, using -f to overwrite:

dx head: display the first few lines of a file.

dx cat: display the contents of a file
dx describe: get information for any object on the platform, including files or apps.
- For example, to describe the file.txt, we would receive information like the project it is located in and the file ID.

You can also append --json to return file information as JSON file. E.g.

dx describe file.txt --json

Moving and copying files on UKB-RAP

Please note that dx mv and dx cp have specific uses in the UKB-RAP. You should use the dx mv command within a project, and the dx cp command between projects.

dx mv: moving files within a project
- For example, to move file.txt from test_folder into your main project space, you could do the following:

dx cp: copying files between projects.

dx cp first_project_id/:file.txt second_project_id

Bulk files

Within the bulk folder for your project, you can find all the bulk data files for imaging and genomics. Every file has properties of eid (encoded participant identifier) and field (the data-field the file relates to). You can see a breakdown of this by selecting the file and looking in the right-hand info panel for these boxes:

File Management: dx find data

You can use the dx find data command with additional arguments to specify the data you are searching for.

Examples

You can use the --name argument to look for data with a particular name. E.g:

You can use the --property argument to pass in a key-value pair. For example, you may wish to search for any file with a particular eid:

dx find data --property eid=123456

or you may wish to use the field id instead:

dx find data --property field_id=123456