Managing submissions

Before submitting a sample you need the workflow registered, and the target environment enabled with an engine and a processing queue. The parameters file can be JSON or YAML.

List submissions

geni submission list

Use --help to see the filtering and sorting options — by provider, status, workflow, date range, environment, engine, queue or tag.

geni submission list --today --status failed
geni submission list --workflow wgs-germline --sort-by duration --sort-order desc

Submit a sample

First find the engine and queue available in the target environment:

geni engine list
geni queue list

Then submit:

geni submission create \
  --workflow-name <workflow-name> \
  --workflow-version <workflow-version> \
  --params-file <path to a JSON or YAML file> \
  --engine-id <engine-id> \
  --queue-id <queue-id> \
  --fallback-queue-id <fallback-queue-id> \
  --output-folder <path to a folder in a bucket>

Recommendations

--workflow-version is optional; without it the latest version is used. Always set it explicitly for production runs.

The input parameters file must be on your computer — the CLI uploads it to GENI.

The engine and queue must both be active and belong to the same environment. The engine needs read permission on every bucket holding input files, and write permission on the bucket named in --output-folder.

Output folder

Every submission must say where output files go, even if the workflow writes nothing. The path follows the cloud’s own convention — s3://bucket/prefix/. GENI passes it to Nextflow as both outdir and outputDir, so the workflow can derive per-task paths from it.

Use --cancel-time DD:HH:MM to cap the runtime of this submission. It overrides whatever the workflow version configures. When the time is reached, GENI cancels the submission and stops its running tasks, the same as geni submission cancel.

Use --tag key=value to label the submission. See Tagging.

Fallback queue

Pass --fallback-queue-id with an on-demand queue. If a job fails for spot-capacity reasons, Nextflow runs it again on the fallback queue.

Note

Cromwell does this on its own and does not need a second queue.

Need a specific process to always run on-demand instead of only after a spot failure? See Routing tasks to a different queue.

Config profiles

Pass --nextflow-profile <names> (comma-separated for more than one) to select a profiles { } block from the workflow’s own nextflow.config — different parameters or per-process resources for a test run versus a production run, without maintaining two workflows.

geni submission create \
  --workflow-name wgs-germline \
  --workflow-version v2.1.0 \
  --params-file sample.json \
  --engine-id <engine-id> \
  --queue-id <queue-id> \
  --nextflow-profile production \
  --output-folder s3://lab-results/run-4471/

Note

Nextflow-only, and the engine needs version 26.04.6-1 or later. See Nextflow config profiles for the full requirements, what a profile can and can’t override, and how retries reuse the same profile.

Cancel

geni submission cancel <submission-id>

GENI stops the Nextflow process and terminates every Batch job belonging to the submission.

Download the inputs file

Recover the exact JSON or YAML parameters file uploaded when the submission was created:

# Print the file content to stdout
geni submission inputs <submission-id>

# Save it to a local file
geni submission inputs <submission-id> --output-file inputs.json

The file keeps its original content. Use an output filename ending in .json or .yaml to match the format used by the submission.

Retry

geni submission retry <submission-id>

By default the retry resumes from the previous run’s work directory — Nextflow -resume reuses any cached results, so unchanged steps don’t re-run. Optionally target a different engine or queue, or disable cache reuse entirely:

geni submission retry <submission-id> --queue-id <ondemand-queue-id>
geni submission retry <submission-id> --dont-resume

Only tasks that finished are reused; a task that was still running when the previous run stopped starts over. On Nextflow engine 26.04.6-2 or later this holds however the previous run ended — including a cancel, manual or by its cancel time. On older versions, a retry after a cancelled run starts from the first task; see Update an engine.

Concurrent retries

Only one retry can be pending per submission. A second retry call while the first hasn’t finished creating its new attempt yet returns 409.

Why was my submission rejected?

An administrator can disable an engine or queue, and GENI support can disable an environment, to retire it without deleting it. New submissions and retries that target a disabled resource fail with one of these messages:

Message	What to do
Environment is disabled	Pick an engine and queue in another environment, or contact GENI support.
Engine is disabled	Pick another engine (geni engine list --enabled), or ask an administrator to enable it.
Queue is disabled	Pick another queue (geni queue list --enabled), or ask an administrator to enable it.
Fallback queue is disabled	Pick another fallback queue, or submit without one.

A retry checks the engine and queue it will actually use, so a retry with --engine-id or --queue-id pointing at an enabled resource still works when the original is disabled. Submissions that were already running when the resource was disabled are not affected.

Submission attempts

Each retry adds a new attempt rather than overwriting the submission’s history. List them, most recent first:

geni submission attempts <submission-id>

geni submission list shows an Attempts column with the total count — it stays 1 unless the submission has been retried. Every submission — including one that has never been retried — has at least one attempt; geni submission attempts shows its job ID, status, timing, and log availability per attempt.

Logs and tasks

Nextflow logs for a submission:

geni submission logs <submission-id>
geni submission logs <submission-id> --follow

The tasks of a submission — add --status failed to see only the failures:

geni task list --submission-id <submission-id>
geni task list --submission-id <submission-id> --status failed

If a task was resubmitted — a fallback-queue retry after a Spot interruption, or the submission itself was retried and the task ran again — geni task list shows Attempt (that task’s latest attempt number), Attempts (its total attempt count), and Submission Attempt (which submission retry produced the latest one). A task’s own retries and the submission’s retries are tracked independently: a task can keep the same single attempt across a submission retry if Nextflow’s cache reused its result.

Logs of one task:

geni task logs <task-id>

Filter by tag, and show another tag as a column:

geni task list --tag <key1>=<value1> --show-tag <key2>

Output formats

Every list command accepts --format, which takes table (the default), csv or json.

geni submission list --today --format csv > runs.csv