Working with apps using dx run

About this article

This guide introduces how to run apps on UK Biobank’s Research Analysis Platform (UKB‑RAP) using the command line. It explains what dx run does, how to explore app inputs, how to submit jobs, and how to track job progress. This is useful for researchers who want to automate tasks, work with large datasets, or build more flexible workflows.

If you are new to using CLI with UKB‑RAP, you may want to review the introductory article first:
Introduction to Command Line Interface (CLI)

A video tutorial on this topic is also available here.

For more detailed DNAnexus documentation see: Running apps and applets

Why use dx run?

dx run allows you to execute apps, applets, and workflows directly from the command line. This can help you:

Automate repeated tasks
Run tools on large datasets
Use structured and reproducible input files
Monitor and manage multiple jobs easily

Each execution of an app creates a job, which can then be tracked through the CLI.

Understanding apps, inputs, and outputs

Before running anything, it helps to understand a few terms:

Apps: tools available on the UKB‑RAP platform (e.g. FastQC app - login required)
Inputs: files or parameters required to run the app.
Outputs: files produced by the app.
Jobs: individual runs of an app with a defined set of inputs.

Checking app details with dx describe

Before running an app, it’s important to check what inputs it expects.

Command:

dx describe app-<app-name>

Example:

dx describe app-fastqc

This returns a description of the app, including:

Required and optional inputs
Expected output files
A summary of what the app does

This step helps avoid errors caused by incorrect input names or missing parameters.

Running apps with dx run

Once you know the required inputs, you can run an app using the basic syntax:

dx run app-<app-name> -i <input_name>=<file>

Example:

dx run app-fastqc -i reads=my_reads.fastq

Where:

app-fastqc is the tool you are running
reads=my_reads.fastq supplies the required input file

Using a JSON input file

For apps with multiple inputs, you can supply a JSON file instead:

dx run app-fastqc --input-json-file inputs.json

This is useful for:

Reproducibility
Longer, multi‑parameter runs
Sharing or re‑using the same configuration

Tracking and managing jobs

The CLI provides several commands to find and monitor jobs.

View recent jobs

dx find jobs

This typically returns the most recent few jobs in your current project.

Show more job results

You can increase the number of results:

dx find jobs -n 20

Get job details in JSON format

dx find jobs --json

JSON output is especially useful if you need to:

Inspect errors
Parse outputs programmatically
Review job histories

Tracking workflow executions

Workflows may generate multiple jobs. To view jobs and workflow-level details:

dx find executions

What job records contain

Each job will show:

Job ID
App or workflow name
Inputs provided
Current status (running, completed, failed)
Output file paths

A typical workflow using dx run

Below is a common pattern for running an app:

1. Check the app requirements

dx describe app-fastqc

2. Prepare inputs

Ensure filenames are correct
Double‑check input names using dx describe

3. Run the app

dx run app-fastqc -i reads=my_reads.fastq

Or with a JSON file:

dx run app-fastqc --input-json-file inputs.json

4. Monitor the job

dx find jobs

5. Review outputs

Use JSON output for detailed information
Navigate to the job in the UI if you prefer a visual overview