Workflow Start
Usage
dxflow workflow start <IDENTITY> [OPTIONS]
Arguments
| Argument | Description |
|---|---|
IDENTITY | The workflow to act on, as listed by dxflow workflow list |
Options
| Flag | Shorthand | Description | Type | Default |
|---|---|---|---|---|
--override | -o | Override value as key=value, none drops a resource; repeatable | stringSlice | |
--fit | -f | Cap every step's cpu and memory to the host capacity and match its gpu to the host | bool | false |
--link | -l | Assign a link to every step declaring one | bool | false |
Overrides
--override takes <category>.<step>.<key>=<value> and is repeatable. Keys are scoped to a step by its name in the definition:
| Category | Key form | Replaces |
|---|---|---|
volume | volume.<step>.<volume-name> | Host side of a named volume (container side stays) |
port | port.<step>.<port-name> | Host side of a named port (container side stays) |
env | env.<step>.<VAR> | An environment variable |
resource | resource.<step>.<cpu|memory|gpu> | A resource limit |
Values are written to the workflow's workflow.ini before it starts and applied only at launch — they never modify the workflow definition (workflow.json). An unknown step / volume / port name, or an invalid cpu/memory/gpu value, fails the start.
A volume value is a host path, resolved like the one in the definition: relative to the engine's directory, so ./volume/data is the data/ of Artifacts and an absolute path is taken as written.
Resource units
resource values follow the runtime's own units:
| Key | Accepts | Examples |
|---|---|---|
cpu | A core count, fractions allowed | 8 is eight cores, 1.5 is one and a half |
memory | A byte count with an optional single-letter unit, case-insensitive and binary: b bytes, k KiB, m MiB, g GiB | 8g is 8 GiB, 512m is 512 MiB |
gpu | One of nvidia, cuda, amd, rocm, all, or none | all |
memory number is bytes, not gigabytes — 8 means 8 bytes, which the runtime rejects as below its minimum. Use one letter only: 8gb is not a valid unit.All three keys also accept none, which means ignore this parameter — the step runs with no limit for it. Use it to lift a limit the definition sets, as in --override resource.step-name.cpu=none. It is an engine-side value and never reaches the runtime.
Fitting to the host
--fit caps each step's cpu and memory to the engine host's core count and total memory, and matches its gpu to the cards the host holds, so a resource the host cannot satisfy no longer fails the start.
- Applied after the overrides — a
resource.<step>.cpuset too high is capped too. - Holds for that start only; never written back to
workflow.ini. - Steps already within the host's capacity are left untouched.
A gpu is matched by vendor: nvidia/cuda needs an NVIDIA card, amd/rocm an AMD one, and all either. Ask for a vendor the host does not have while it holds the other and the request switches over — nvidia on an AMD-only host becomes amd. Only a host with no GPU at all drops it to none, leaving the step on CPU. Detection asks the vendor tooling (nvidia-smi, rocm-smi) rather than the PCI inventory, so a card whose driver is not installed counts as absent.
Without it, an oversized limit or a missing GPU reaches the runtime, which refuses to start the step.
Links
--link assigns a link to every step declaring one under link in the definition, while the license carries any. Left out, the start runs the steps with their declared links idle. The success line carries what the start assigned, one [link → step] detail per link. See Links.
Example
dxflow workflow start my-workflow \
--override volume.step-name.data=/mnt/host/data \
--override env.step-name.KEY=value \
--override resource.step-name.cpu=8 \
--override resource.step-name.memory=8g \
--link
dxflow workflow start my-workflow --fit
dxflow workflow start my-workflow --override resource.step-name.cpu=none