OmicsBox Engine

Introduction

The OmicsBox Engine is the command-line interface (CLI) to OmicsBox. It exposes the same bioinformatics analyses as the desktop application through a single omicsbox command, so pipelines and analyses can be scripted, automated, and integrated into workflow managers such as Nextflow — without opening the graphical interface.

The Engine is designed to complement the desktop application rather than replace it. The desktop application remains the primary environment for exploring data and inspecting results interactively; the Engine is for running analyses reproducibly from a terminal, on a server, or inside a container. Both share the same OmicsBox account, subscription, and cloud storage.

How it works

Every analysis available in the desktop application is published to the Engine as a subcommand. Running a tool follows the same three steps every time:

omicsbox list                 # discover the available tools
omicsbox describe <tool>      # inspect a tool's inputs, parameters and defaults
omicsbox <tool> [options]     # run it

Tools are drawn from the same internal catalog the desktop uses, so the set of tools and their parameters always matches the installed version of OmicsBox.

Cloud jobs and your terminal

Most OmicsBox analyses run on OmicsCloud, exactly as they do when launched with cloud execution from the desktop application, so running them requires a signed-in account with available Cloud Units.

How long a command keeps your terminal busy depends on the tool:

• Long-running cloud analyses can be detached: start them with --detach and the Engine submits the job, prints a run ID, and returns straight away. You can close the terminal — or even switch off your computer — and reconnect later with that run ID to check progress or download the results.
• Other commands run in your current session and report progress as they go, so keep the session open until they finish.

See Long-running cloud jobs for the full detach-and-reconnect workflow.

Quick start

# 1. One-time setup — activate your subscription and sign in
omicsbox activate <your-45-character-subscription-key>

# 2. See which tools are available
omicsbox list

# 3. Inspect a tool before running it
omicsbox describe fasta-splitter

# 4. Run it, sending outputs to a local folder
omicsbox fasta-splitter \
    --i-input-files-single-end ./sequences.fasta \
    --filter parts --split-value-parts 4 \
    --local-folder ./results

Installation, activation and sign-in are covered in Installation & Activation.

Command structure

A tool invocation is made up of four parts:

omicsbox  <tool>  --i-<input> <value>  <parameters>  <global options>
          │        │                    │             │
          │        │                    │             └─ shared plumbing (output folder, format, …)
          │        │                    └─ tool-specific parameters (--kmer-size, --database, …)
          │        └─ one or more inputs, always prefixed --i-
          └─ the tool's short name (from `omicsbox list`)

• Inputs are always prefixed --i- and accept local files, cloud paths, or URIs — see Providing inputs.
• Parameters and inputs are specific to each tool. They are not listed here — every tool has its own manual page with a generated OmicsBox Engine reference section, and omicsbox describe <tool> always reports the exact, current set.
• Global options are shared by every tool (output destination, output format, verbosity, …) and are documented once in Global Options.
• There are no --o-* output flags. All outputs are routed automatically to the folder you choose with --local-folder or --cloud-folder.

Because omicsbox describe <tool> is generated live from the tool itself, it always reflects the current flags, defaults, and — for cloud-backed options such as --database — the values available to your account. It is the reliable way to check a tool's exact command line before you run it, rather than relying on memory or older examples.

Finding and inspecting tools

Both commands work offline and need no sign-in. See Built-in Commands for the full reference.

Where to go next

• Installation & Activation — install the Engine, then activate and sign in to OmicsCloud.
• Running Tools — inputs, outputs, configuration files, and building pipelines.
• Built-in Commands — the utility commands (list, describe, status, logs, config, …).
• Global Options — the flags shared by every tool.

Every individual tool's page (for example ABySS or Taxonomic Classification) also carries an OmicsBox Engine section with that tool's exact command line.