Skip to content

oxo-flow lint#

Run best-practice linting checks on a .oxoflow file.


Usage#

oxo-flow lint [OPTIONS] <WORKFLOW>

Arguments#

Argument Description
<WORKFLOW> Path to the .oxoflow workflow file

Options#

Option Short Default Description
--strict — — Treat warnings as errors (non-zero exit)
--ai — — Enable AI-powered semantic linting
--verbose -v — Enable verbose (debug-level) logging
--quiet — — Suppress informational output — the version banner is omitted; lint diagnostics and the summary are printed regardless (verified: output is byte-identical with --quiet)
--no-color — — Disable colored output
--json — — Output machine-readable JSON to stdout

Examples#

Run standard linting#

oxo-flow lint pipeline.oxoflow

Run strict linting#

oxo-flow lint pipeline.oxoflow --strict

Output#

oxo-flow v0.31.0 — Rust-native bioinformatics pipeline engine
  warning [W003]: rule has no description (rule: bwa_align)
    hint: add description = "Brief one-line description of what bwa_align does" to this rule
  info [W004]: rule has a shell command but no log file specified (rule: bwa_align)
    hint: add log = "logs/bwa_align.log"
  info [W007]: leaf rule (no dependents) could be marked as target = true (rule: fastqc)
    hint: add target = true to this rule
  info [W025]: rule uses deprecated rule-level threads/memory (rule: bwa_align)
    hint: replace `threads = N` / `memory = "8G"` with `resources.threads = N` / `resources.memory = "8G"` under this rule

Summary: 0 errors, 1 warning, 3 info

Each diagnostic prints a hint: line (when a suggestion exists) showing the fix, matching the style of validate and run output. W007 suggests target = true: a rule marked as a target is built by default when oxo-flow run is invoked without an explicit -t, so marking the final leaf rules (like fastqc above) makes them part of the default run — see Workflow Format: Priority and Targeting. W025 flags the deprecated rule-level threads = N / memory = "8G" fields (superseded by [rules.resources] in v0.4) so old workflows surface the migration instead of silently keeping their old settings — see Workflow Format: Rule resources. W031 flags a consumer rule that reads the output of a when-gated producer without a when gate of its own: when the producer's gate is off, its files never appear and the consumer's inputs cannot be resolved at plan time (dry-run input ✗) or the run fails outright. Wildcard templates match after canonicalizing every {...} placeholder, and fully literal paths match literally — a literal input of a gated producer is the same hazard. The repair is either a matching when gate on the consumer or splitting it into when-gated variants (the multiqc/multiqc_pseudo idiom). Consumers that declare their tolerance for a missing producer are not flagged: optional = true / "any" rules, input_groups disk-discovery fallbacks, and consumers that already carry any when gate. W033 flags two rules that write the same output path — including differently-named wildcards over the same template (variants/{smp}.vcf vs variants/{sample}.vcf) and identical literal paths. The engine does not refuse to run: both rules execute and the second to finish silently overwrites the first (verified live in v0.31.0 with a run reporting success while both colliding rules executed), so downstream rules consume the wrong file. The repair is distinct output directories per writer — or a when gate when the two rules are mutually exclusive alternatives (the wgs_coverage/wes_coverage idiom). Multi-producer outputs remain a supported feature, so this is a warning, not an error. {config.*} placeholders are resolved against the parsed config before the templates are compared, so {config.out_dir}/{sample}.vcf collides with its literal counterpart results/{sample}.vcf when out_dir = "results" — and does not collide with {config.alt_dir}/{sample}.vcf when the values differ.

When both writers carry meaningful when gates that are complementary empty-string checks on the same expression — X != '' on one and X == '' on the other (the paired/tumor-only mutect2_paired/mutect2_tumoronly shape) — each rule runs exactly when the other does not, so the pair can never race and the collision is not reachable at runtime. W033 then downgrades to an info note naming the shared expression ("... their when gates are complementary on 'X' — collision is not reachable at runtime") instead of the warning. The detection is deliberately narrow: a single top-level ==/!= whose right side is the empty-string literal '' or "" and whose left side is the same bare config.<name> or wildcard.<name> reference on both sides. These are the only left-hand forms the executor compares with exact complement semantics — compound conditions (&&/||), comparison operators other than ==/!=, function-call or unqualified-identifier left sides, different expressions, non-empty or unquoted right-hand sides, and pairs where either writer is ungated all keep the plain warning — a syntactic complement there would not prove a runtime one (a shared disjunct short-circuits both gates to true; anything the executor cannot parse as a reference falls through to its default-true verdict). See Troubleshooting → Output collisions. W034 flags an {input[N]} / {output[N]} placeholder whose index is out of range, or a named {input.key} / {output.key} whose key the rule does not declare. The substitution loop only renders indices 0..len (list-form: declaration order; map-form: keys in sorted order; dir-form: the single entry), and only renders named references for declared keys — anything else survives rendering as literal brace text, so the tool is invoked with a path like {input[5]} and fails with an unrelated "No such file" error that hides the real mistake. The repair depends on the input shape: use an in-range index (map-form indices follow the rule's sorted keys, not the text order), switch to the bare {input} / {output} form to interpolate all entries, or — preferred for role-bearing IO — declare a map and use named access (tumor = "..." + {input.tumor}), which also survives reordering. Lines that are comments in the rendered script are exempt, and script paths are checked the same way as inline shell. W032 flags a [config] key whose name looks like a secret (token, secret, passwd, password, credential, api_key, access_key, private_key, ssh_key, key — matched at word/segment boundaries, so names that merely contain these as a substring, like tokenize or password_length_hint, are not flagged) but is not declared sensitive: its value then lands in plaintext in command records, stderr tails, and the checkpoint — credential leakage on shared clusters and in CI artifacts. The repair is the declaration itself:

[config]
api_token = { default = "sk-...", sensitive = true }

Declared-sensitive keys are env-routed and masked on disk, so W032 never flags them — see [config] — Configuration Variables. to declare the glob in input = [...] — glob inputs are compiled by the DAG builder and linked to every matching producer output, so they create real edges — or, for gather/fan-in steps, to list the files via expand_inputs. Pattern arguments (find data -name '*.tmp') and cleanup commands (rm -rf build/*) are not data reads and are not flagged.

W036 flags a rule that declares input_function. The field is parsed and round-tripped, but the engine performs no dynamic input resolution — the function is never called, so the rule's input list stays exactly as declared. Because input_function also suppresses W035's glob-only heuristic, an undeclared-glob rule would otherwise look silently safe; W036 fires alongside so the missing dynamic behavior is never invisible. The repair is to declare the inputs statically (input = [...], glob inputs, or expand_inputs).

W037 flags a rule whose resource_hint sets runtime or io_bound. Both fields are parsed and round-tripped, but nothing consumes them — the memory estimator reads only input_size and memory_scale. The repair is to declare enforced limits instead (resources.time_limit, resources.memory, resources.threads); the reserved hints stay legal TOML so external tooling can keep writing them.

W039 flags a dotted {namespace.key} placeholder whose namespace the engine does not recognize — for example {metadata.batch} where {meta.batch} was meant. Bare {token} wildcards already get an unknown-wildcard warning and {input.…}/{output.…} mistakes have their own W034 checks, but an unrecognized dotted namespace used to fall through every guard: the token renders as literal brace text and the tool fails on input that looks valid. The diagnostic suggests the closest recognized namespace when the typo is a prefix-extended or truncated form (metadata → meta, conf → config); shell brace text like awk '{print $1}' and comment lines are not flagged.

W040 flags a rule with no runnable command: shell is missing or empty/whitespace-only and no non-empty script is declared. This is the lint mirror of E022 — the engine skips such a rule at run time (“no shell or script defined”), so the workflow validates yet silently does nothing. The classic source is an oxo-flow import of a Nextflow process whose script: block was not captured; re-import after upgrading, or add the command by hand. transform rules are exempt because their command lives in transform.map/transform.combine.

W041 flags a rule that references the sample domain — {sample}, {group}, {wildcard.sample}, {wildcard.group}, or {meta.<column>} — with no binding source. The rule then runs exactly once and the token stays unbound (the execution-time placeholder gate rejects the rendered command). The repair is to bind the domain in input/output and declare its source ([[sample_groups]], [[pairs]], sample_pattern, pairs_pattern, [[values]], or a scatter) — or, for a deliberate one-instance {meta.*} read, add singleton = true. singleton silences the LINT diagnosis only; the execution-time gate still rejects a {meta.*} token that survives rendering (a one-row metadata table is the supported constant read; {config.<key>} is the workflow constant). The binding model is shared with the expansion engine, so:

  • a sample_pattern/pairs_pattern declaration counts even when lint runs without the data mounted (CI/editor);
  • a {meta.*} reference in output binds when the metadata column(s) uniquely key every instance — a constant column (batch_{meta.batch}.tsv) does not fan out and stays flagged (the engine avoids the silent duplicate-output race);
  • a one-row metadata table is an unambiguous constant read;
  • singleton = true suppresses {meta.*} only — a {sample}/{group} survivor is always a defect and stays flagged;
  • a scatter binds its own variable (a scatter over pair_id does not hide an unbound {sample});
  • every free-text field is scanned, including log, script, benchmark, hooks, env-var values, and string params. Shell ${...} parameter expansion and comments are never treated as placeholders.

Notes#

  • lint is a strict superset of validate: it runs every validate check (parsing, DAG, input existence) plus style linting and secret scanning — running validate separately after lint adds nothing
  • Linting checks for common mistakes, missing metadata, and potential performance issues
  • Rules are checked for valid input/output patterns and environment declarations
  • Use --strict to ensure high-quality workflow definitions in production environments

Every finding carries a stable code (E0xx = validation error, W0xx = lint warning). The full code index with one-line meanings lives in the Glossary → Diagnostic Codes.