Command-Line Interface

Run, export, validate and orchestrate experiments from the shell: the registry-driven, transport-aware tvbo command tree.

The tvbo command line runs, exports, imports, validates and orchestrates TVB-O simulations from a shell. It is registry-driven: every backend and every file format is a plug-in entry rather than a hard-coded branch. It is also transport-aware, so a spec may be a local file, an ontology CURIE, or a database name. HTTP URLs are reserved for a future release.

The command tree

Generated from the installed CLI, so it cannot describe a command that does not exist.

tvbo
├── run        Execute a SimulationStudy or SimulationExperiment.
├── export     Render a SPEC into a target format (no execution).
├── save       Like export, with bundled data when supported.
├── import     Load a foreign file (auto-dispatch by extension).
├── info       Inspect a SPEC (tasks, outputs, declared backends).
├── formats    List all registered I/O formats.
├── verify     Check a study-of-studies is buildable (completeness / staleness / manifest coverage).
├── version    Print the tvbo version.
├── brain      Draw a spec dissolving into a cortical surface made of its own characters.
├── validate   [all | bids | omex | schema | sedml | study]
├── config     [path | show]
├── cache      [prune]
├── network    [build]
├── figure     [caption | compare | render]
├── workflow   [backends | finalize | nextflow | plan | run | slurm | snakemake | submit]
├── skills     [install | sync | uninstall]
├── units      [add | list | show]
├── study      [init | layout]
└── install    [auto7p]

What is a SPEC?

Most verbs take a single positional argument called SPEC, which can be:

Form Example Resolves to
File path ./study.yaml, /abs/path.yaml YAML loaded by LinkML
CURIE experiment:JR_Optimization, dynamics:JansenRit Database lookup by class + name
Bare name JR_Optimization Tries Study → Experiment → Dynamics in order
file:// URI file:///tmp/foo.yaml Same as a path
http(s):// URI (reserved) Pulled remotely in a future milestone

See Specs and resolution for the full rules.

Verb reference

Each page below documents one verb or sub-tree, with its flags, exit codes and worked examples.

Six command groups have no guide page yet and are documented only by their generated API reference: tvbo figure, tvbo study, tvbo units, tvbo cache, tvbo verify and tvbo install.

Two execution paths

The CLI exposes two complementary execution paths:

  1. Direct execution. tvbo run invokes the requested backend in-process and saves the results. Best for laptops, CI and short experiments.
  2. Workflow emission. tvbo workflow {slurm,snakemake,nextflow} writes a self-contained reproducibility kit and exits. The kit holds the workflow artefact, the frozen backend script, the frozen YAML spec and a README, so it can be archived, moved to a cluster and run without tvbo installed.

The same study YAML produces a different DAG on different backends. The planner consults the backend capability table, mirrored from ontology/tvb-o-axioms.ttl §4.1, to decide which sweep axes vectorize inside the backend and which fan out across workflow tasks.

Quick start

# Inspect a study
tvbo info study:Schirner2023_MultiscaleBNM_DM

# Render JAX code to stdout
tvbo export jax experiment:JR_MEG_FrequencyGradient_Optimization

# Run locally with the tvboptim backend
tvbo run experiment:JR_MEG_FrequencyGradient_Optimization -b tvboptim -o ./out

# Emit a Snakemake reproducibility kit
tvbo workflow snakemake experiment:JR_MEG_FrequencyGradient_Optimization \
    --backend jax -o ./kit-jax

# Submit the same study via Slurm in one shot
tvbo run experiment:JR_MEG_FrequencyGradient_Optimization \
    --engine slurm --backend jax -o ./run-001