Levandor

mando-cli flow run — reproducible, test-matchable flow execution

4 min read

New mando flow command group: reproducible, TEST-MATCHABLE flow execution. One command + one params file runs identically anywhere, produces golden-file-diffable output, and drops conformance-suite pointers into Datadog at terminal. Landed 2026-07-28 in the mando-cli working tree (UNCOMMITTED, pending push + a live smoke run).

For Agents

Purpose is conformance: a flow run must be byte-reproducible so a test suite can diff its output and follow it into Datadog. Follow mode has two layers — verbatim local log streaming and a universal step digest. Exit 1 on any Error/Fatal step. The linchpin is a single Uuid tying trigger response, DB row, and every log line together.

Commands

  • mando flow list [-e env] — list available flows for an environment.
  • mando flow run <flow> [--params f.json] [--date ts] [--overrides f.csv|json] [-e env] [--no-follow] [--log-file p] [--poll s] — trigger + follow.
  • mando flow status <flow> <exec-id> — poll a known execution.

Flows: auction, intraday, data-update, as-auction-update, manual-schedule. Kebab-case URL segments on the wire; the body wraps a snake_case flow_key. The server pins flow versions (the CLI never selects a version).

The linchpin — one Uuid everywhere

Verified against the mando repo (cited, not assumed):

  • The id returned by the trigger the DB execution id the root-flattened flow.exec_id on every log line. One Uuid, three surfaces.
  • Local builds ALWAYS emit dd_formatter JSON — init_log hardcodes dd_enabled=true.
  • The server creates all step rows upfront as Queued, so terminal detection cannot fire early on a partially-populated run.
  • The trigger returns immediately (tokio::spawn); the CLI then follows out-of-band.

This is what makes follow-by-exec-id sound: filter every container log line by the root flow.exec_id JSON key and you get exactly this run’s lines.

Follow mode — two layers

Layer 1 — verbatim local streaming (local targets only). Byte-preserved streaming of every execution log line via a prefix-free docker logs --since, filtered by the root flow.exec_id JSON key. Single-writer architecture: a streaming task feeds an mpsc channel and the poll loop is the SOLE writer to stdout/file — no torn or interleaved lines.

Layer 2 — step digest (all targets). Maps step outcomes: Success → pass, Warning → warn, Skip → skip, Error/Fatal → fail; Canceled is terminal. Process exits 1 on any Error/Fatal.

Byte-fidelity contract

tokio Lines strips the trailing \n/\r; the CLI re-adds a single \n. Lossless for mando’s single-line UTF-8 JSON logs — the exact property golden-file diffing depends on.

--log-file: truncate + append, writing verbatim lines AND the NDJSON digest in arrival order, independent of follow mode.

Conformance pointers (emitted at terminal)

Machine-consumable kv events for a downstream conformance test suite:

  • dd_query — @flow.exec_id:<id>, env-scoped when the local Datadog overlay is active (DD_ENV read from the rendered .infra/datadog.builtin.yaml).
  • dd_url — DD_SITE-aware deep link with epoch-ms time bounds.
  • started_at / stopped_at.

Trace-backend hint: local + datadog → Datadog; local without datadog → generic OTel; remote → Datadog. No Jaeger UI ships in the repo (verified — the “generic OTel” hint does not promise a local UI).

Plumbing

  • New src/flow/{mod,client,input,follow,dd}.rs + commands/flow.rs.
  • Shared date recognizer in system/datetime.rs (used by --date).
  • Environments un-gated from the (broken) query feature in config/environments.rs; query behavior itself unchanged — the same 2 pre-existing flight.rs errors remain.
  • Docs: docs/flow-guide.md. Agent skill grown to 104 lines with flow intents.

Review & gate

  • Bugs lens: APPROVED outright — verbatim guarantee, exec-id filtering, and terminal detection all verified at mando source.
  • Quality/DRY lens: Importants fixed (dd.rs cohesion split; the shared date recognizer) + 7 minors.
  • Gate: 464 lib + 8 integration tests, clippy 0 warnings, release build 0.

Graph View

Backlinks