Semantiva CLI

Note

Single Source of Truth (SSoT) — This page mirrors the CLI implementation at semantiva/cli/__init__.py. Update code and docs together to avoid drift.

Overview

  • semantiva run — Execute a pipeline from YAML.

  • semantiva inspect — Inspect a pipeline configuration.

  • semantiva dev lint — Lint components against contracts.

Exit Codes

0: success, 1: CLI error, 2: file error, 3: config error, 4: runtime error, 5: interrupt.

Run

Execute a pipeline.

Syntax

semantiva run PIPELINE.yaml
                  [--dry-run]
                  [--validate]
                  [--set key=value]...
                  [--context key=value]...
                  [-v | --verbose]
                  [-q | --quiet]
                  [--execution.orchestrator CLASS]
                  [--execution.executor CLASS]
                  [--execution.transport CLASS]
                  [--execution.option key=value]...
                  [--trace.driver NAME]
                  [--trace.output PATH-or-DriverSpec]
                  [--trace.option key=value]...
                  [--fanout.param NAME]
                  [--fanout.values SEQ]
                  [--fanout.values-file PATH]
                  [--fanout.multi NAME=SEQ]...
                  [--fanout.multi-file PATH]
                  [--version]

Arguments - PIPELINE.yaml Path to the pipeline YAML file. - --dry-run Build graph without executing nodes. - --validate Validate configuration only. - --set key=value Override by dotted path (lists use numeric indices).

  • Value parsing: YAML first; falls back to string on parse error.

  • --context key=value Inject initial context key/values.

    • Value parsing: YAML first; falls back to string on parse error.

  • -v / --verbose Increase log verbosity.

  • -q / --quiet Only show errors.

  • --execution.orchestrator Resolve orchestrator via the Execution Component Registry (ECR).

  • --execution.executor Resolve executor via the Execution Component Registry (ECR).

  • --execution.transport Resolve transport via the Execution Component Registry (ECR).

  • --execution.option Key/value pairs forwarded to the orchestrator options.

  • --trace.driver Trace driver name (none, jsonl, pythonpath, or registry class).

  • --trace.output Trace output path or module:Class when driver=pythonpath.

  • --trace.option Additional driver keyword arguments (repeatable).

  • --fanout.param Single-parameter fan-out target name.

  • --fanout.values Values for single-parameter fan-out (JSON list or comma-separated).

  • --fanout.values-file External JSON/YAML file supplying fan-out values.

  • --fanout.multi Multi-parameter ZIP values (repeatable name=[...] arguments).

  • --fanout.multi-file External JSON/YAML mapping supplying multi fan-out values.

  • --version Show CLI version.

CLI flags mirror the YAML schema. Any value provided on the command line overrides the matching YAML block before validation and execution. Trace detail flags are supplied via --trace.option detail=... (hash is implied when no detail is provided). Environment pins and why-ok invariants are always captured by SemantivaOrchestrator, ensuring consistent SER output across orchestrator implementations.

Note

In YAML, use the plural key options under trace and execution. The CLI uses repeatable singular flags --trace.option and --execution.option to populate those mappings.

Component Resolution The CLI loads extensions before constructing execution components so that the Execution Component Registry (ECR) contains all orchestrators, executors, and transports. Built-in identifiers include local (orchestrator), sequential (executor), and in_memory (transport). Unknown component names result in an error with did-you-mean suggestions based on the registered inventory.

YAML Extension Loading If your YAML contains:

extensions: ["my_package.ext"]

or:

pipeline:
  extensions: ["my_package.ext"]

those extensions are loaded before validation/execution. Extension registration is deterministic and idempotent: each extension is imported once and must expose either an entry point under semantiva.extensions or a module-level register() hook.

Inspect

Syntax

semantiva inspect PIPELINE.yaml
                    [--extended]
                    [-v | --verbose]
                    [-q | --quiet]
                    [--strict]
                    [--version]

Arguments - PIPELINE.yaml Path to the pipeline YAML file. - --extended Show extended inspection details. - -v / --verbose Increase log verbosity. - -q / --quiet Only show errors. - --strict Exit non-zero if configuration is invalid. - --version Show CLI version.

Dev / Lint

Syntax

semantiva dev lint
  [--modules MOD ...]
  [--paths PATH ...]
  [--extensions NAME ...]
  [--yaml FILE ...]
  [--export-contracts PATH]
  [--debug]
  [--version]

Arguments - --modules Python modules to import and validate - --paths Paths to scan for Python components - --extensions Extension names (entry points or module names) to load and validate - --yaml Pipeline YAML files (discovers referenced components) - --export-contracts Write rule catalog to PATH (Markdown) - --debug Detailed rule-by-rule diagnostics - --version Show CLI version