# Running Apps and Applets

You can run apps and applets from the command-line using the command [`dx run`](/user/helpstrings-of-sdk-command-line-utilities.md#run). The inputs to these app(let)s can be from any project for which you have *VIEW* access. Or [run from the UI.](/getting-started/key-concepts/apps-and-workflows.md)

## Running in Interactive Mode

If `dx run` is run without specifying any inputs, interactive mode launches. When you run this command, the platform prompts you for each required input, followed by a prompt to set any optional parameters. As shown below using the [BWA-MEM FASTQ Read Mapper app](https://platform.dnanexus.com/app/bwa_mem_fastq_read_mapper) (platform login required to access this link), after you are done entering inputs, you must confirm that you want the applet/app to run with the inputs you have selected.

```shell
$ dx run app-bwa_mem_fastq_read_mapper
Entering interactive mode for input selection.

Input:   Reads (reads_fastqgz)
Class:   file

Enter file ID or path ((<TAB> twice for compatible files in current directory, '?' for more options)
reads_fastqgz: reads.fastq.gz

Input:   BWA reference genome index (genomeindex_targz)
Class:   file
Suggestions:
    project-BQpp3Y804Y0xbyG4GJPQ01xv://file-* (DNAnexus Reference Genomes)

Enter file ID or path (<TAB> twice for compatible files in current directory, '?' for more options)
genomeindex_targz: "Reference Genome Files:/H. Sapiens - hg19 (UCSC)/ucsc_hg19.bwa-index.tar.gz"

Select an optional parameter to set by its # (^D or <ENTER> to finish):

 [0] Reads (right mates) (reads2_fastqgz)
 [1] Add read group information to the mappings (required by downstream GATK)? (add_read_group) [default=true]
 [2] Read group id (read_group_id) [default={"$dnanexus_link": {"input": "reads_fastqgz", "metadata": "name"}}]
 [3] Read group platform (read_group_platform) [default="ILLUMINA"]
 [4] Read group platform unit (read_group_platform_unit) [default="None"]
 [5] Read group library (read_group_library) [default="1"]
 [6] Read group sample (read_group_sample) [default="1"]
 [7] Output all alignments for single/unpaired reads? (all_alignments)
 [8] Mark shorter split hits as secondary? (mark_as_secondary) [default=true]
 [9] Advanced command line options (advanced_options)

Optional param #: <ENTER>

Using input JSON:
{
    "reads_fastqgz": {
        "$dnanexus_link": {
            "project": "project-xxxx",
            "id": "file-xxxx"
        }
    },
    "genomeindex_targz": {
        "$dnanexus_link": {
            "project": "project-xxxx",
            "id": "file-xxxx"
        }
    }
}

Confirm running the applet/app with this input [Y/n]: <ENTER>
Calling app-xxxx with output destination project-xxxx:/

Job ID: job-xxxx
Watch launched job now? [Y/n] n
```

## Running in Non-interactive Mode

### Naming Each Input

You can also specify each input parameter by name using the `‑i` or `‑‑input` flags with syntax `‑i<input name>=<input value>`. Names of data objects in your project are resolved to the appropriate IDs and packaged correctly for the API method as shown below.

When specifying input parameters using the `‑i/‑‑input` flag, you must use the input field *names* (not to be confused with their human-readable *labels*). To look up the input field names for an app, applet, or workflow, you can run the command `dx run app(let)-xxxx -h`, as shown below using the [Swiss Army Knife app](https://platform.dnanexus.com/app/swiss-army-knife) (platform login required to access this link).

```
usage: dx run app-swiss-army-knife [-iINPUT_NAME=VALUE ...]

App: Swiss Army Knife

Version: 5.1.0 (published)

A multi-purpose tool for all your basic analysis needs

See the app page for more information:
  https://platform.dnanexus.com/app/swiss-army-knife

Inputs:
  Input files: [-iin=(file) [-iin=... [...]]]
        (Optional) Files to download to instance temporary folder before
        command is executed.

  Command line: -icmd=(string)
        Command to execute on instance. View the app readme for details.

  Whether to use "dx-mount-all-inputs"?: [-imount_inputs=(boolean, default=false)]
        (Optional) Whether to mount all files that were supplied as inputs to
        the app instead of downloading them to the local storage of the
        execution worker.

  Public Docker image identifier: [-iimage=(string)]
        (Optional) Instead of using the default Ubuntu 24.04 environment, the
        input command <CMD> will be run using the specified publicly
        accessible Docker image <IMAGE> as it would be when running 'docker
        run <IMAGE> <CMD>'. Example image identifiers are 'ubuntu:25.04',
        'quay.io/ucsc_cgl/samtools'. Cannot be specified together with
        'image_file'. This input relies on access to internet and is unusable
        in an internet-restricted project.

  Platform file containing Docker image accepted by `docker load`: [-iimage_file=(file)]
        (Optional) Instead of using the default Ubuntu 24.04 environment, the
        input command <CMD> will be run using the Docker image <IMAGE> loaded
        from the specified image file <IMAGE_FILE> as it would be when running
        'docker load -i <IMAGE_FILE> && docker run <IMAGE> <CMD>'. Cannot be
        specified together with 'image'.

Outputs:
  Output files: [out (array:file)]
        (Optional) New files that were created in temporary folder.
```

The help message describes the inputs and outputs of the app, their types, and how to identify them when running the app from the command line. For example, from the above help message, the Swiss Army Knife app has two primary inputs: one or more files and a string to be executed on the command line, to be specified as `-iin=file-xxxx` and `icmd=<string>`, respectively.

The example below shows you how to run the same Swiss Army Knife app to sort a small BAM file using these inputs.

```shell
$ dx run app-swiss-army-knife \
-iin=project-BQbJpBj0bvygyQxgQ1800Jkk:file-BQbXVY0093Jk1K VY1J082y7v \
-icmd="samtools sort -T /tmp/aln.sorted -o SRR100022_chrom20_mapped_to_b37.sorted.bam \
SRR100022_chrom20_mapped_to_b37.bam" -y

Using input JSON:
{
    "cmd": "samtools sort -T /tmp/aln.sorted -o SRR100022_chrom20_mapped_to_b37.sorted.bam SRR100022_chrom20_mapped_to_b37.bam",
    "in": [
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BQbXVY0093Jk1KVY1J082y7v"
            }
        }
    ]
}

Calling app-xxxx with output destination project-xxxx:/

Job ID: job-xxxx
```

### Specifying Array Input

To specify array inputs, reuse the `‑i/‑‑input` flag for each input in the array and each file specified is appended into an array in the same order as it was entered on the command line. Below is an example of how to use the [Swiss Army Knife app](https://platform.dnanexus.com/app/swiss-army-knife) to index multiple BAM files (platform login required to access this link).

```shell
$ dx run app-swiss-army-knife \
-iin=project-BQbJpBj0bvygyQxgQ1800Jkk:file-BQbXVY0093Jk1KVY1J082y7v \
-iin=project-BQbJpBj0bvygyQxgQ1800Jkk:file-BZ9YGpj0x05xKxZ42QPqZkJY \
-iin=project-BQbJpBj0bvygyQxgQ1800Jkk:file-BZ9YGzj0x05b66kqQv51011q \
-icmd="ls *.bam | xargs -n1 -P5 samtools index" -y

Using input JSON:
{
    "cmd": "ls *.bam | xargs -n1 -P5 samtools index",
    "in": [
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BQbXVY0093Jk1KVY1J082y7v"
            }
        },
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BZ9YGpj0x05xKxZ42QPqZkJY"
            }
        },
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BZ9YGzj0x05b66kqQv51011q"
            }
        }
    ]
}

Calling app-xxxx with output destination project-xxxx:/

Job ID: job-xxxx
```

### Job-Based Object References (JBORs)

[Job-based object references](/developer/api/running-analyses/job-input-and-output.md#job-based-object-references) (JBORs) can also be provided using the `-i` flag with syntax `‑i<input name>=<job id>:<output name>`. Combined with the `--brief` flag (which allows `dx run` to output only the job ID) and the `-y` flag (to skip confirmation), you can string together two jobs using one command.

Below is an example of how to run the [BWA-MEM FASTQ Read Mapper app](https://platform.dnanexus.com/app/bwa_mem_fastq_read_mapper) (platform login required to access this link), producing the output named `sorted_bam` as described in the `dx help` output by executing the command `dx run app-bwa_mem_fastq_read_mapper -h`. The `sorted_bam` output is then used as input for the [Swiss Army Knife app](https://platform.dnanexus.com/app/swiss-army-knife) (platform login required to access this link).

```shell
$ dx run app-swiss-army-knife \
    -iin=$(dx run app-bwa_mem_fastq_read_mapper \
    -ireads_fastqgz=project-BQbJpBj0bvygyQxgQ1800Jkk:file-BQbXKk80fPFj4Jbfpxb6Ffv2 \
    -igenomeindex_targz=project-BQpp3Y804Y0xbyG4GJPQ01xv:file-B6qq53v2J35Qyg04XxG0000V -y \
    --brief):sorted_bam \
    -icmd="samtools index *.bam" -y

Using input JSON:
{
    "in": [
        {
            "$dnanexus_link": {
                "field": "sorted_bam",
                "job": "job-xxxx"
            }
        }
    ],
    "cmd": "samtools index *.bam"
}

Calling app-xxxx with output destination project-xxxx:/

Job ID: job-xxxx
```

## Advanced Options

Some examples of additional functionalities provided by `dx run` are listed below.

### Quiet Output

Regardless of whether you run a job interactively or non-interactively, the command `dx run` always prints the exact input JSON with which it is calling the applet or app. If you don't want to print this verbose output, you can use the `--brief` flag which tells `dx` to print out only the job ID instead. This job ID can then be saved.

```shell
$ dx run app-bwa_mem_fastq_read_mapper \
    -ireads_fastqgz="project-BQbJpBj0bvygyQxgQ1800Jkk:/SRR100022/SRR100022_1.filt.fastq.gz" \
    -ireads_fastqgz="project-BQbJpBj0bvygyQxgQ1800Jkk:/SRR100022/SRR100022_2.filt.fastq.gz" \
    -igenomeindex_targz="project-BQpp3Y804Y0xbyG4GJPQ01xv:file-B6ZY4942J35xX095VZyQBk0v" \
    --destination "mappings" -y --brief
```

{% hint style="success" %}
To run jobs without being prompted for confirmation, use the `-y` or `--yes` option. This is especially helpful when scripting or automating job submissions.

If you want to both skip confirmation and immediately monitor the job's progress, use `-y --watch`. This starts the job and displays its logs in your terminal as it runs.
{% endhint %}

### Rerunning a Job With the Same Settings

If you are debugging *applet-xxxx* and want to rerun a job you previously ran, using the same settings (destination project and folder, inputs, instance type requests), but use a new executable *applet-yyyy*, you can use the `--clone` flag.

```shell
$ dx run app-swiss-army-knife --clone job-xxxx -y

Using input JSON:
{
    "cmd": "ls *.bam | xargs -n1 -P5 samtools index",
    "in": [
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BQbXVY0093Jk1KVY1J082y7v"
            }
        },
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BZ9YGpj0x05xKxZ42QPqZkJY"
            }
        },
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BZ9YGzj0x05b66kqQv51011q"
            }
        }
    ]
}

Calling app-xxxx with output destination project-xxxx:/

Job ID: job-xxxx
```

In the above command, the command overrides the `--clone job-xxxx` command to use the executable [Swiss Army Knife app](https://platform.dnanexus.com/app/swiss-army-knife) (platform login required to access this link) rather than that used by the job.

If you want to modify some but not all settings from the previous job, you can run `dx run <executable> --clone job-xxxx [options]`. The command-line arguments you provide in `[options]` override the settings reused from `--clone`. For example, this is useful if you want to rerun a job with the same executable and inputs but a different instance type, or if you want to run an executable with the same settings but slightly different inputs.

The example shown below redirects the outputs of the job to the folder "outputs/".

```shell
$ dx run app-swiss-army-knife \
--clone job-xxx --destination project-xxxx:/output -y
```

{% hint style="info" %}
While the `--clone job-xxxx` flag copies the applet, instance type, and inputs, it does not copy usage of the `--allow-ssh` or `--debug-on` flags. These must be re-specified for each job run. For more information, see the [Connecting to Jobs](/developer/apps/execution-environment/connecting-to-jobs.md) page.
{% endhint %}

### Specifying the Job Output Folder

The `--destination` flag allows you to specify the full `project-ID:/folder/` path in which to output the results of the app(let). If this flag is unspecified, the output of the job defaults to the present working directory, which can be determined by running [`dx pwd`](/user/helpstrings-of-sdk-command-line-utilities.md#pwd).

```shell
$ dx run app-bwa_mem_fastq_read_mapper \
-ireads_fastqgz="project-BQbJpBj0bvygyQxgQ1800Jkk:/SRR100022/SRR100022_1.filt.fastq.gz" \
-ireads_fastqgz="project-BQbJpBj0bvygyQxgQ1800Jkk:/SRR100022/SRR100022_2.filt.fastq.gz" \
-igenomeindex_targz="project-BQpp3Y804Y0xbyG4GJPQ01xv:file-B6ZY4942J35xX095VZyQBk0v" \
--destination "mappings" -y --brief
```

In the above command, the flag `--destination project-xxxx:/mappings` instructs the job to output all results into the "mappings" folder of *project-xxxx*.

### Specifying a Different Instance Type

The `dx run --instance-type` command allows you to specify the instance types to use for the job. More information is available by running the command `dx run --instance-type-help`.

Some apps and applets have multiple [entry points](/developer/api/running-analyses/applets-and-entry-points.md#running-entry-points), meaning that different instance types can be specified for different functions executed by the app(let). In the example below, the [Parliament app](https://platform.dnanexus.com/app/parliament) (platform login required to access this link) is run while specifying the instance types for the entry points `honey`, `ssake`, `ssake_insert`, and `main`. Specifying the instance types for each entry point requires a JSON-like string, meaning that the string should be wrapped in single quotes, as explained earlier, and shown below.

```shell
dx run parliament \
  -iillumina_bam=illumina.bam \
  -iref_fasta=ref.fa.gz \
  --instance-type '{
    "honey": "mem1_ssd1_x32",
    "ssake": "mem1_ssd1_x8",
    "ssake_insert": "mem1_ssd1_x32",
    "main": "mem1_ssd1_x16"
  }' \
  -y \
  --brief
```

### Adding Metadata to a Job

If you are running many jobs that have varying purposes, you can organize the jobs using metadata. Two types of metadata are available on the DNAnexus Platform: properties and tags.

Properties are key-value pairs that can be attached to any object on the platform, whereas tags are strings associated with objects on the platform. The `--property` flag allows you to attach a property to a job, and the `--tag` flag allows you to tag a job.

Adding metadata to executions does not affect the metadata of the executions' output files. Metadata on jobs makes it easier for you to search for a particular job in your job history. This is useful when you want to tag all jobs run with a particular sample, for instance.

```shell
$ dx run app-swiss-army-knife \
    -iin=project-BQbJpBj0bvygyQxgQ1800Jkk:file-BQbXVY0093Jk1KVY1J082y7v \
    -icmd="samtools sort -T /tmp/aln.sorted -o \
    SRR100022_chrom20_mapped_to_b37.sorted.bam SRR100022_chrom20_mapped_to_b37.bam" \
    --property foo=bar --tag dna -y
```

### Specifying an App Version

If your current workflow is not using the most up-to-date version of an app, you can specify an older version when running your job. Append the app name with the version required, for example, app-xxxx/0.0.1 if the current version is app-xxxx/1.0.0.

```shell
$ dx run app-swiss-army-knife/2.0.1 \
    -iin=project-BQbJpBj0bvygyQxgQ1800Jkk:file-BQbXVY0093Jk1KVY1J082y7v \
    -icmd="samtools sort -T /tmp/aln.sorted -o SRR100022_chrom20_mapped_to_b37.sorted.bam SRR100022_chrom20_mapped_to_b37.bam" \
    -y --brief
```

### Watching a Job

To monitor your job as it runs, use the `--watch` flag to display the job's logs in your terminal window as it progresses.

```shell
$ dx run app-swiss-army-knife \
  -iin=project-BQbJpBj0bvygyQxgQ1800Jkk:file-BQbXVY0093Jk1KVY1J082y7v \
  -icmd="samtools sort -T /tmp/aln.sorted \
    -o SRR100022_chrom20_mapped_to_b37.sorted.bam \
    SRR100022_chrom20_mapped_to_b37.bam" \
  --watch \
  -y \
  --brief

job-xxxx

Job Log
-------
Watching job job-xxxx. Press Ctrl+C to stop.
```

### Providing Input JSON

You can also specify the input JSON in its entirety. To specify a data object, you must wrap it in [DNAnexus link form](/developer/api/running-analyses/job-input-and-output.md#special-values) (a key-value pair with a key of `$dnanexus_link` and value of the data object's ID). Because you are already providing the JSON in its entirety, if the applet/app ID can be resolved and the JSON can be parsed, confirmation before the job starts is not required. Three methods exist for entering the full input JSON, discussed in separate sections below.

#### From the CLI

If using the CLI to enter the full input JSON, you must use the flag `‑j/‑‑input‑json` followed by the JSON in **single** quotes. Only single quotes should be used to wrap the JSON to avoid interfering with the double quotes used by the JSON itself.

```shell
$ dx run app-swiss-army-knife -j '{
  "cmd": "ls *.bam | xargs -n1 -P5 samtools index",
  "in": [
    { "$dnanexus_link": {
        "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
        "id": "file-BQbXVY0093Jk1KVY1J082y7v"
      }
    },
    { "$dnanexus_link": {
        "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
        "id": "file-BZ9YGpj0x05xKxZ42QPqZkJY"
      }
    },
    { "$dnanexus_link": {
        "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
        "id": "file-BZ9YGzj0x05b66kqQv51011q"
      }
    }
  ]
}' -y

Calling app-xxxx with output destination project-xxxx:/

Job ID: job-xxxx
```

#### From a File

If using a file to enter the input JSON, you must use the flag `‑f/‑‑input‑json‑file` followed by the name of the JSON file.

```shell
$ dx run app-swiss-army-knife -f input.json

Using input JSON:
{
    "cmd": "ls *.bam | xargs -n1 -P5 samtools index",
    "in": [
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BQbXVY0093Jk1KVY1J082y7v"
            }
        },
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BZ9YGpj0x05xKxZ42QPqZkJY"
            }
        },
        {
            "$dnanexus_link": {
                "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
                "id": "file-BZ9YGzj0x05b66kqQv51011q"
            }
        }
    ]
}

Calling app-xxxx with output destination project-xxxx:/

Job ID: job-xxxx
```

#### From `stdin`

Entering the input JSON file using `stdin` is done the same way as entering the file using the `-f` flag with the substitution of using "-" as the filename. Below is an example that shows how to `echo` the input JSON to `stdin` and pipe the output to the input of `dx run`. As before, use single quotes to wrap the JSON input to avoid interfering with the double quotes used by the JSON itself.

```shell
$ echo '{
  "cmd": "ls *.bam | xargs -n1 -P5 samtools index",
  "in": [
    {
      "$dnanexus_link": {
        "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
        "id": "file-BQbXVY0093Jk1KVY1J082y7v"
      }
    },
    {
      "$dnanexus_link": {
        "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
        "id": "file-BZ9YGpj0x05xKxZ42QPqZkJY"
      }
    },
    {
      "$dnanexus_link": {
        "project": "project-BQbJpBj0bvygyQxgQ1800Jkk",
        "id": "file-BZ9YGzj0x05b66kqQv51011q"
      }
    }
  ]
}' | dx run app-swiss-army-knife -f - -y

Calling app-xxxx with output destination project-xxxx:/

Job ID: job-xxxx
```

### Getting Additional Information on `dx` run

Executing the `dx run --help` command shows the flags available to use with `dx run`. The message printed by this command is identical to the one displayed in the brief description of [`dx run`](/user/helpstrings-of-sdk-command-line-utilities.md#run).

### Cost Run Limits

The `--cost-limit cost_limit` sets the maximum cost of the job before termination. In case of workflows, it is the cost of the entire analysis job. For a batch run, this limit applies per job. See the `dx run --help` command for more information.

### Job Runtime Limits

On the DNAnexus Platform, jobs are limited to a runtime of 30 days. Jobs running longer than 30 days are automatically terminated.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.dnanexus.com/user/running-apps-and-workflows/running-apps-and-applets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.