Skip to main content

Command Syntax

OmegaFlow uses Hydra's key=value override syntax:

omegaflow recording=<id> [action=<action>] [key=value ...]

Arguments are configuration overrides, not conventional --long-option flags. For example:

omegaflow recording=tutorial/install action=check verbose=true

OmegaFlow discovers the project root automatically. Override it when operating on another project without changing directories:

omegaflow project_root=/path/to/project recording=tutorial/install

Select a recording​

Recording ids map to directories under studio.recording_dir. With the default workspace, recording=tutorial/install selects recordings/tutorial/install/index.md.

omegaflow action=list
omegaflow recording=tutorial/install

An id whose index.md has kind: collection groups an ordered set of videos. For example, omegaflow recording=tutorial builds every video listed by the tutorial collection. action=watch opens one index page with a titled, described link to each built video. Collections also support dry_run=true for build previews; select an individual member for other single-video actions.

Actions that operate across recordings do not require a selection. list and runs are the common examples. inspect and output can also work without recording when a run_id uniquely identifies a run.

Select an action​

action defaults to build:

# These are equivalent.
omegaflow recording=demo
omegaflow recording=demo action=build

The public actions are bootstrap, build, check, clean, gc, watch, list, runs, inspect, and output.

Override values​

Use dotted keys for nested configuration:

omegaflow action=list studio.recording_dir=demos
omegaflow recording=demo studio.run_gc.max_age_days=14

Hydra parses booleans, numbers, lists, mappings, and null. Quote values when your shell or Hydra would otherwise interpret punctuation or whitespace:

omegaflow action=runs runs_since=2h runs_limit=null
omegaflow recording=demo +script_params.message='hello world'

OmegaFlow accepts rec.* shorthand even when the key does not exist in the base tool config:

omegaflow recording=demo rec.capture.headless=false

Other keys added to an initially empty mapping use Hydra's + prefix. This is why declared script parameters are passed as +script_params.<name>=<value>.

See Overrides and Script Parameters before using rec.* in repeatable project workflows.

Config files versus command overrides​

Put shared project defaults in .omegaflow/config.yaml:

studio:
  recording_dir: recordings
  data_dir: recordings/.omegaflow

Use command-line overrides for a single invocation. CLI values have the highest precedence. See Project Configuration for the complete composition order.

Built-in help​

omegaflow --help
omegaflow --hydra-help

The first command prints the composed OmegaFlow schema. Because it is generated from Hydra, it also shows fields used internally by build stages. The Complete Option Reference identifies those fields so they are not mistaken for public actions or routine options.