<a id="cli-aws-omics-start-run"></a>

# start-run

## Description

Starts a new run and returns details about the run, or duplicates an existing run. A run is a single invocation of a workflow. If you provide request IDs, Amazon Web Services HealthOmics identifies duplicate requests and starts the run only once. Monitor the progress of the run by calling the `GetRun` API operation.

To start a new run, the following inputs are required:

* A service role ARN (`roleArn` ).
* The run’s workflow ID (`workflowId` , not the `uuid` or `runId` ).
* An Amazon S3 location (`outputUri` ) where the run outputs will be saved.
* All required workflow parameters (`parameter` ), which can include optional parameters from the parameter template. The run cannot include any parameters that are not defined in the parameter template. To see all possible parameters, use the `GetRun` API operation.
* For runs with a `STATIC` (default) storage type, specify the required storage capacity (in gibibytes). A storage capacity value is not required for runs that use `DYNAMIC` storage.

> `StartRun` can also duplicate an existing run using the run’s default values. You can modify these default values and/or add other optional inputs. To duplicate a run, the following inputs are required:
* A service role ARN (`roleArn` ).
* The ID of the run to duplicate (`runId` ).
* An Amazon S3 location where the run outputs will be saved (`outputUri` ).

To learn more about the optional parameters for `StartRun` , see [Starting a run](https://docs.aws.amazon.com/omics/latest/dev/starting-a-run.html) in the *Amazon Web Services HealthOmics User Guide* .

Use the `retentionMode` input to control how long the metadata for each run is stored in CloudWatch. There are two retention modes:

* Specify `REMOVE` to automatically remove the oldest runs when you reach the maximum service retention limit for runs. It is recommended that you use the `REMOVE` mode to initiate major run requests so that your runs do not fail when you reach the limit.
* The `retentionMode` is set to the `RETAIN` mode by default, which allows you to manually remove runs after reaching the maximum service retention limit. Under this setting, you cannot create additional runs until you remove the excess runs.

To learn more about the retention modes, see [Run retention mode](https://docs.aws.amazon.com/omics/latest/dev/run-retention.html) in the *Amazon Web Services HealthOmics User Guide* .

You can use Amazon Q CLI to analyze run logs and make performance optimization recommendations. To get started, see the [Amazon Web Services HealthOmics MCP server](https://github.com/awslabs/mcp/tree/main/src/aws-healthomics-mcp-server) on GitHub.

See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/omics-2022-11-28/StartRun)

`start-run` uses document type values. Document types follow the JSON data model where valid values are: strings, numbers, booleans, null, arrays, and objects. For command input, options and nested parameters that are labeled with the type `document` must be provided as JSON. Shorthand syntax does not support document types.

## Synopsis

```
  start-run
[--workflow-id <value>]
[--workflow-type <value>]
[--run-id <value>]
--role-arn <value>
[--name <value>]
[--cache-id <value>]
[--cache-behavior <value>]
[--run-group-id <value>]
[--priority <value>]
[--parameters <value>]
[--storage-capacity <value>]
--output-uri <value>
[--log-level <value>]
[--tags <value>]
[--request-id <value>]
[--retention-mode <value>]
[--storage-type <value>]
[--workflow-owner-id <value>]
[--workflow-version-name <value>]
[--networking-mode <value>]
[--scratch-storage-mode <value>]
[--configuration-name <value>]
[--session-policy <value>]
[--engine-settings <value>]
[--output-uri-prefix-mode <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
[--cli-error-format <value>]
[--help]
```

## Options

`--workflow-id` (string)

> The run’s workflow ID. The `workflowId` is not the UUID.

> Constraints:

> * min: `1`
> * max: `18`
> * pattern: `[0-9]+`

`--workflow-type` (string)

> The run’s workflow type. The `workflowType` must be specified if you are running a `READY2RUN` workflow. If you are running a `PRIVATE` workflow (default), you do not need to include the workflow type.

> Possible values:

> * `PRIVATE`
> * `READY2RUN`

> Constraints:

> * min: `1`
> * max: `64`

`--run-id` (string)

> The ID of a run to duplicate.

> Constraints:

> * min: `1`
> * max: `18`
> * pattern: `[0-9]+`

`--role-arn` (string) [required]

> A service role for the run. The `roleArn` requires access to Amazon Web Services HealthOmics, S3, Cloudwatch logs, and EC2. An example `roleArn` is `arn:aws:iam::123456789012:role/omics-service-role-serviceRole-W8O1XMPL7QZ` . In this example, the Amazon Web Services account ID is `123456789012` and the role name is `omics-service-role-serviceRole-W8O1XMPL7QZ` .

> Constraints:

> * min: `1`
> * max: `128`
> * pattern: `arn:.+`

`--name` (string)

> A name for the run. This is recommended to view and organize runs in the Amazon Web Services HealthOmics console and CloudWatch logs.

> Constraints:

> * min: `1`
> * max: `128`
> * pattern: `[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+`

`--cache-id` (string)

> Identifier of the cache associated with this run. If you don’t specify a cache ID, no task outputs are cached for this run.

> Constraints:

> * min: `1`
> * max: `18`
> * pattern: `[0-9]+`

`--cache-behavior` (string)

> The cache behavior for the run. You specify this value if you want to override the default behavior for the cache. You had set the default value when you created the cache. For more information, see [Run cache behavior](https://docs.aws.amazon.com/omics/latest/dev/how-run-cache.html#run-cache-behavior) in the *Amazon Web Services HealthOmics User Guide* .

> Possible values:

> * `CACHE_ON_FAILURE`
> * `CACHE_ALWAYS`

> Constraints:

> * min: `1`
> * max: `64`

`--run-group-id` (string)

> The run’s group ID. Use a run group to cap the compute resources (and number of concurrent runs) for the runs that you add to the run group.

> Constraints:

> * min: `1`
> * max: `18`
> * pattern: `[0-9]+`

`--priority` (integer)

> Use the run priority (highest: 1) to establish the order of runs in a run group when you start a run. If multiple runs share the same priority, the run that was initiated first will have the higher priority. Runs that do not belong to a run group can be assigned a priority. The priorities of these runs are ranked among other runs that are not in a run group. For more information, see [Run priority](https://docs.aws.amazon.com/omics/latest/dev/creating-run-groups.html#run-priority) in the *Amazon Web Services HealthOmics User Guide* .

> Constraints:

> * min: `0`
> * max: `100000`

`--parameters` (document)

> Parameters for the run. The run needs all required parameters and can include optional parameters. The run cannot include any parameters that are not defined in the parameter template. To retrieve parameters from the run, use the GetRun API operation.

JSON Syntax:

```json
{...}
```

`--storage-capacity` (integer)

> The `STATIC` storage capacity (in gibibytes, GiB) for this run. The default run storage capacity is 1200 GiB. If your requested storage capacity is unavailable, the system rounds up the value to the nearest 1200 GiB multiple. If the requested storage capacity is still unavailable, the system rounds up the value to the nearest 2400 GiB multiple. This field is not required if the storage type is `DYNAMIC` (the system ignores any value that you enter).

> Constraints:

> * min: `0`
> * max: `100000`

`--output-uri` (string) [required]

> An output S3 URI for the run. The S3 bucket must be in the same region as the workflow. The role ARN must have permission to write to this S3 bucket.

> Constraints:

> * min: `1`
> * max: `750`
> * pattern: `[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+`

`--log-level` (string)

> A log level for the run.

> Possible values:

> * `OFF`
> * `FATAL`
> * `ERROR`
> * `ALL`

> Constraints:

> * min: `1`
> * max: `64`

`--tags` (map)

> Tags for the run. You can add up to 50 tags per run. For more information, see [Adding a tag](https://docs.aws.amazon.com/omics/latest/dev/add-a-tag.html) in the *Amazon Web Services HealthOmics User Guide* .

> key -> (string)

> > Constraints:

> > * min: `1`
> > * max: `128`

> value -> (string)

> > Constraints:

> > * min: `0`
> > * max: `256`

Shorthand Syntax:

```
KeyName1=string,KeyName2=string
```

JSON Syntax:

```json
{"string": "string"
  ...}
```

`--request-id` (string)

> An idempotency token used to dedupe retry requests so that duplicate runs are not created.

> Constraints:

> * min: `1`
> * max: `128`
> * pattern: `[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+`

`--retention-mode` (string)

> The retention mode for the run. The default value is `RETAIN` .

> Amazon Web Services HealthOmics stores a fixed number of runs that are available to the console and API. In the default mode (`RETAIN` ), you need to remove runs manually when the number of run exceeds the maximum. If you set the retention mode to `REMOVE` , Amazon Web Services HealthOmics automatically removes runs (that have mode set to `REMOVE` ) when the number of run exceeds the maximum. All run logs are available in CloudWatch logs, if you need information about a run that is no longer available to the API.

> For more information about retention mode, see [Specifying run retention mode](https://docs.aws.amazon.com/omics/latest/dev/starting-a-run.html) in the *Amazon Web Services HealthOmics User Guide* .

> Possible values:

> * `RETAIN`
> * `REMOVE`

> Constraints:

> * min: `1`
> * max: `64`

`--storage-type` (string)

> The storage type for the run. If you set the storage type to `DYNAMIC` , Amazon Web Services HealthOmics dynamically scales the storage up or down, based on file system utilization. By default, the run uses `STATIC` storage type, which allocates a fixed amount of storage. For more information about `DYNAMIC` and `STATIC` storage, see [Run storage types](https://docs.aws.amazon.com/omics/latest/dev/workflows-run-types.html) in the *Amazon Web Services HealthOmics User Guide* .

> Possible values:

> * `STATIC`
> * `DYNAMIC`

> Constraints:

> * min: `1`
> * max: `64`

`--workflow-owner-id` (string)

> The 12-digit account ID of the workflow owner that is used for running a shared workflow. The workflow owner ID can be retrieved using the `GetShare` API operation. If you are the workflow owner, you do not need to include this ID.

> Constraints:

> * pattern: `[0-9]{12}`

`--workflow-version-name` (string)

> The name of the workflow version. Use workflow versions to track and organize changes to the workflow. If your workflow has multiple versions, the run uses the default version unless you specify a version name. To learn more, see [Workflow versioning](https://docs.aws.amazon.com/omics/latest/dev/workflow-versions.html) in the *Amazon Web Services HealthOmics User Guide* .

> Constraints:

> * min: `1`
> * max: `64`
> * pattern: `[A-Za-z0-9][A-Za-z0-9\-\._]*`

`--networking-mode` (string)

> Optional configuration for run networking behavior. If not specified, this will default to RESTRICTED.

> Possible values:

> * `RESTRICTED`
> * `VPC`

`--scratch-storage-mode` (string)

> Optional configuration for enabling scratch ephemeral storage mounted at /tmp. If not specified, this will default to SHARED. This configuration is applicable only for CPU tasks. For tasks using GPUs, scratch storage is always LOCAL.

> Possible values:

> * `LOCAL`
> * `SHARED`

> Constraints:

> * min: `1`
> * max: `64`

`--configuration-name` (string)

> Optional configuration name to use for the workflow run.

> Constraints:

> * min: `1`
> * max: `128`
> * pattern: `[A-Za-z0-9][A-Za-z0-9\-\._]*`

`--session-policy` (string)

> Optional inline policy json for scoping down permissions via a session policy on the IAM role provided in the roleArn parameter.

> Constraints:

> * min: `1`
> * max: `2048`
> * pattern: `[\p{L}\p{M}\p{Z}\p{S}\p{N}\p{P}\t\n\r]+`

`--engine-settings` (document)

> Engine-specific settings for the workflow run. Use this field to specify configuration options that are specific to the workflow engine (for example, Nextflow profiles).

JSON Syntax:

```json
{...}
```

`--output-uri-prefix-mode` (string)

> You can control the path prefixes that the service adds beneath `outputUri` . If you don’t specify a value, the service uses `SERVICE_DEFINED` , which adds a run-specific prefix.

> Possible values:

> * `SERVICE_DEFINED`
> * `NONE_WITH_OVERWRITE`

`--cli-input-json` | `--cli-input-yaml` (string)
Reads arguments from the JSON string provided. The JSON string follows the format provided by `--generate-cli-skeleton`. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with `--cli-input-yaml`.

`--generate-cli-skeleton` (string)
Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value `input`, prints a sample input JSON that can be used as an argument for `--cli-input-json`. Similarly, if provided `yaml-input` it will print a sample input YAML that can be used with `--cli-input-yaml`. If provided with the value `output`, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

## Global Options

`--debug` (boolean)

Turn on debug logging.

`--endpoint-url` (string)

Override command’s default URL with the given URL.

`--no-verify-ssl` (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

`--no-paginate` (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

`--output` (string)

The formatting style for command output.

* json
* text
* table
* yaml
* yaml-stream
* off

`--query` (string)

A JMESPath query to use in filtering the response data.

`--profile` (string)

Use a specific profile from your credential file.

`--region` (string)

The region to use. Overrides config/env settings.

`--version` (string)

Display the version of this tool.

`--color` (string)

Turn on/off color output.

* on
* off
* auto

`--no-sign-request` (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

`--ca-bundle` (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

`--cli-read-timeout` (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

`--cli-connect-timeout` (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

`--cli-binary-format` (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob `fileb://` will always be treated as binary and use the file contents directly regardless of the `cli-binary-format` setting. When using `file://` the file contents will need to properly formatted for the configured `cli-binary-format`.

* base64
* raw-in-base64-out

`--no-cli-pager` (boolean)

Disable cli pager for output.

`--cli-auto-prompt` (boolean)

Automatically prompt for CLI input parameters.

`--no-cli-auto-prompt` (boolean)

Disable automatically prompt for CLI input parameters.

`--cli-error-format` (string)

The formatting style for error output. By default, errors are displayed in enhanced format.

* legacy
* json
* yaml
* text
* table
* enhanced

`--help` (boolean)

Display help for the command/subcommand.

## Examples

#### NOTE
To use the following examples, you must have the AWS CLI installed and configured. See the [Getting started guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the *AWS CLI User Guide* for more information.

Unless otherwise stated, all examples have unix-like quotation rules. These examples will need to be adapted to your terminal’s quoting rules. See [Using quotation marks with strings](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) in the *AWS CLI User Guide* .

**Example 1: To run a workflow**

The following `start-run` example runs a workflow with ID `1234567`.

```bash
aws omics start-run \
    --workflow-id 1234567 \
    --role-arn arn:aws:iam::123456789012:role/omics-service-role-serviceRole-W8O1XMPL7QZ \
    --name 'cram-to-bam' \
    --output-uri s3://amzn-s3-demo-bucket/workflow-output/ \
    --run-group-id 1234567 \
    --priority 1 \
    --storage-capacity 10 \
    --log-level ALL \
    --parameters file://workflow-inputs.json
```

Contents of `workflow-inputs.json`:

```json
{
    "sample_name": "NA12878",
    "input_cram": "s3://amzn-s3-demo-bucket/NA12878.cram",
    "ref_dict": "s3://amzn-s3-demo-bucket/Homo_sapiens_assembly38.dict",
    "ref_fasta": "s3://amzn-s3-demo-bucket/Homo_sapiens_assembly38.fasta",
    "ref_fasta_index": "amzn-s3-demo-bucket/Homo_sapiens_assembly38.fasta.fai"
}
```

Output:

```json
{
    "arn": "arn:aws:omics:us-west-2:123456789012:run/1234567",
    "id": "1234567",
    "status": "PENDING",
    "tags": {}
}
```

For more information, see [Starting a run](https://docs.aws.amazon.com/omics/latest/dev/starting-a-run.html) in the *AWS HealthOmics User Guide*.

**Example 2: To load source files from Amazon Omics**

The following `start-run` example loads source files from Amazon Omics storage by using service-specific URIs. The `workflow-inputs.json` file for this example uses Amazon Omics URIs for read set and reference genome sources.

```json
{
    "sample_name": "NA12878",
    "input_cram": "omics://123456789012.storage.us-west-2.amazonaws.com/1234567890/readSet/1234567890/source1",
    "ref_dict": "s3://amzn-s3-demo-bucket/Homo_sapiens_assembly38.dict",
    "ref_fasta": "omics://123456789012.storage.us-west-2.amazonaws.com/1234567890/reference/1234567890",
    "ref_fasta_index": "omics://123456789012.storage.us-west-2.amazonaws.com/1234567890/reference/1234567890/index"
}
```

## Output

arn -> (string)

> Unique resource identifier for the run.

> Constraints:

> * min: `1`
> * max: `128`
> * pattern: `arn:.+`

id -> (string)

> The run’s ID.

> Constraints:

> * min: `1`
> * max: `18`
> * pattern: `[0-9]+`

status -> (string)

> The run’s status.

> Possible values:

> * `PENDING`
> * `STARTING`
> * `RUNNING`
> * `STOPPING`
> * `COMPLETED`
> * `DELETED`
> * `CANCELLED`
> * `FAILED`

> Constraints:

> * min: `1`
> * max: `64`

tags -> (map)

> The run’s tags.

> key -> (string)

> > Constraints:

> > * min: `1`
> > * max: `128`

> value -> (string)

> > Constraints:

> > * min: `0`
> > * max: `256`

uuid -> (string)

> The universally unique identifier for a run.

> Constraints:

> * min: `1`
> * max: `128`
> * pattern: `[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+`

runOutputUri -> (string)

> The destination for workflow outputs.

> Constraints:

> * min: `1`
> * max: `750`
> * pattern: `[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+`

configuration -> (structure)

> Configuration details for the workflow run.

> name -> (string)

> > User-friendly name for the configuration.

> > Constraints:

> > * min: `1`
> > * max: `128`
> > * pattern: `[A-Za-z0-9][A-Za-z0-9\-\._]*`

> arn -> (string)

> > Unique resource identifier for the configuration.

> > Constraints:

> > * min: `1`
> > * max: `190`
> > * pattern: `arn:.+`

> uuid -> (string)

> > Unique identifier for the configuration.

> > Constraints:

> > * min: `1`
> > * max: `128`
> > * pattern: `[\p{L}||\p{M}||\p{Z}||\p{S}||\p{N}||\p{P}]+`

networkingMode -> (string)

> Networking mode for the workflow run.