Running Tools

This page explains how to run analyses with the OmicsBox Engine: how to inspect a tool, provide its inputs, control where results go, and reconnect to long-running cloud jobs. For the flags shared by every tool see Global Options; for the utility commands see Built-in Commands.

Inspect, compose, run

Running a tool always follows the same loop:

omicsbox describe <tool>      # 1. see the exact inputs, parameters and defaults
omicsbox <tool> [options]     # 2. run it

describe is generated at real time from the tool, so it is a reliable source of truth for a tool's command line: its flags, parameters and the values offered by cloud-backed options (such as --database) can change between versions and between accounts. The plain describe <tool> output contains the inputs, parameters, outputs and parameter relationships. Add --output-format json for the same information as JSON, or --full for the complete specification (types, defaults, numeric ranges, value candidates, argument groups) in either format.

omicsbox describe kraken2                                # human-readable
omicsbox describe kraken2 --output-format json           # machine-readable
omicsbox describe kraken2 --output-format json --full    # complete machine-readable spec

describe --save-template <path> writes a YAML skeleton you can fill in and pass back with --config (see Configuration files).

Providing inputs

Every input flag is prefixed --i-. An input value can be a local file, a file already in your OmicsCloud storage, or an explicit URI. The Engine detects which one you gave:

Cloud inputs are used in place — no local copy is made. To see what is in your cloud storage and get paths you can paste straight into an --i- flag, use:

omicsbox cloud-files                    # list everything
omicsbox cloud-files async_inputs/fastq # filter by folder

Each line it prints (for example /cloud/async_inputs/fastq/reads.fastq.gz) is a valid input value.

Where results go

There are no --o-* output flags. You choose a destination folder and the Engine names and places each output automatically:

You can keep your results locally, in the cloud, or in both places at once: set --local-folder to download them to your machine, --cloud-folder to write them to the cloud, or pass both flags to save a copy in each. If you set neither, the run stops and asks for a destination.

Outputs land directly in the chosen folder (there is no per-run subfolder). File outputs are named after the output and its file type; a tool that produces a folder of files (such as Fasta Splitter) fills the destination folder directly.

Progress and run IDs

While a tool runs, the Engine prints progress messages as it goes, keeping them separate from the results themselves:

OmicsBox Engine 3.2.0
Resolved command: omicsbox fasta-splitter --i-input-files-single-end seqs.fasta --split-value-parts 4
Submitting fasta-splitter...
Run ID: fasta-splitter_20260602_112135_YIMWQG
Status: QUEUED
Status: RUNNING
Output files: part_1.fasta, part_2.fasta
Outputs saved to: ./results/

• Resolved command: echoes the fully-resolved invocation — every flag with its effective value, including the defaults that were applied — so a run is reproducible and auditable.
• Run ID: identifies a cloud run and is the handle used by status, logs and cancel.

Live cloud log messages are streamed to standard error as the job runs; suppress them with --mute, or raise diagnostic detail with --verbose.

Long-running cloud jobs: detach and reconnect

Cloud analyses can be detached so your terminal returns immediately:

omicsbox kraken2 --i-read-files reads.fastq.gz --database "…" --detach

This submits the job, prints its Run ID, and exits. Reconnect from any shell using that ID:

omicsbox status <runId>                                  # check progress
omicsbox logs <runId> --follow                           # stream logs
omicsbox status <runId> --download --local-folder ./out  # fetch outputs when COMPLETE
omicsbox cancel <runId>                                  # stop the run

--detach applies only to cloud (asynchronous) tools; synchronous tools run to completion in the foreground and ignore it.

Configuration files

Instead of a long command line, a tool's inputs and parameters can be supplied from a YAML file:

omicsbox describe kraken2 --save-template ./kraken2.yaml   # generate a template
# edit ./kraken2.yaml …
omicsbox kraken2 --config ./kraken2.yaml                   # run from the file

Values passed on the command line override the file, so a template can capture your defaults while individual runs override specific flags. This is distinct from the persistent CLI configuration in ~/.omicsbox/config.yaml, which sets defaults for global options — see Global Options.

Automation and pipelines

The Engine is built to be driven by scripts and workflow managers:

• JSON output — add --output-format json (or set it once with omicsbox config set output_format JSON). Progress becomes newline-delimited JSON on standard error, and a single run manifest is printed to standard output on success:

  {
    "runId": "fasta-splitter_20260602_112135_YIMWQG",
    "tool": "fasta-splitter",
    "outputLocation": "local",
    "outputs": [
      { "key": "output-path", "path": "/abs/results/part_1.fasta" }
    ],
    "exitCode": 0
  }
  

  An output entry carries a path when it was downloaded locally and a uri when it was written to the cloud.

• Exit codes make failures scriptable: 0 success, 1 error, 2 bad arguments, 3 authentication, 4 cloud/transport.

• Cloud-to-cloud chaining — keep uploaded inputs available for a following step with --keep-inputs-in-cloud, and read one step's cloud outputs directly as the next step's --i- inputs, avoiding intermediate downloads.

For a machine-readable description of any tool to generate wrappers from, use omicsbox describe <tool> --output-format json --full.