Skip to content

Global Options

Global options are the flags accepted by every OmicsBox Engine tool, in addition to that tool's own inputs and parameters. They control where results go, how output is formatted, and how the run behaves. They can be placed before or after the tool name:

omicsbox --local-folder ./out fasta-splitter --i-input-files seqs.fasta …
omicsbox fasta-splitter --i-input-files seqs.fasta … --local-folder ./out

Every tool's own inputs and parameters are documented on that tool's manual page and by omicsbox describe <tool>; the options below are the shared ones and are not repeated per tool.

Options

Option Default Description
--local-folder <path> — Download outputs to this folder on your machine.
--cloud-folder <furi> — Write outputs to this cloud location, e.g. s3://bucket/prefix/.
--output-format TEXT|JSON TEXT Output format. JSON emits newline-delimited progress on standard error and a run manifest on standard output.
--config <file> — Read a tool's input and parameter values from a YAML file (see Running Tools). Command-line flags override the file.
--detach off Submit a cloud job and return immediately, printing its run ID. Ignored by synchronous tools.
--keep-inputs-in-cloud off Keep uploaded inputs in the cloud after the run, for chaining pipeline steps.
--strict off Treat parameter-validation warnings as errors and stop the run. By default, warnings are printed and the run continues.
--mute off Suppress the live cloud log messages that are otherwise streamed while a job runs.
--verbose, -v off Show additional diagnostic messages during execution.
--help, -h — Show usage for the command.
--version, -V — Show the Engine version.

Precedence

When the same setting can come from more than one place, the Engine uses this order, highest priority first:

  1. a command-line flag,
  2. an environment variable,
  3. the configuration file (~/.omicsbox/config.yaml),
  4. the built-in default.

Environment variables

Variable Effect
OMICSBOX_SKEY Subscription key; takes priority over the key stored by activate.
OMICSBOX_LOCAL_FOLDER Default for --local-folder.
OMICSBOX_CLOUD_FOLDER Default for --cloud-folder.
OMICSBOX_OUTPUT_FORMAT Default output format (TEXT or JSON).
OMICSBOX_KEEP_INPUTS_IN_CLOUD Default for --keep-inputs-in-cloud (true/false).
OMICSBOX_CONFIG Path to the configuration file (overrides ~/.omicsbox/config.yaml).
OMICSBOX_CATALOG Path to the tool catalog cache (overrides ~/.omicsbox/catalog.json).

Setting OMICSBOX_SKEY is the recommended way to supply credentials in CI systems and containers.

Persistent configuration

~/.omicsbox/config.yaml stores defaults for the output options so you don't repeat them on every command. Manage it with the config command:

omicsbox config set local_folder ~/omicsbox-outputs
omicsbox config set cloud_folder s3://my-bucket/omicsbox/
omicsbox config get local_folder
omicsbox config list

Recognized keys:

Key Effect
local_folder Default local output folder (--local-folder).
cloud_folder Default cloud output location (--cloud-folder).
output_location Force the output location (LOCAL, CLOUD or BOTH) instead of inferring it.

To change the default output format, set the OMICSBOX_OUTPUT_FORMAT environment variable.

Credentials do not belong in the configuration file

config set rejects any key that looks like a credential (containing token, skey, password or secret). Provide your subscription key through the OMICSBOX_SKEY environment variable or omicsbox activate instead.

The configuration file (~/.omicsbox/config.yaml) is separate from a tool's --config file: the former sets CLI-wide defaults, the latter supplies one tool's inputs and parameters for a single run.