feat: add chainweaver run CLI subcommand to execute flows from disk (#129)

[dgenio]

Summary

Adds the chainweaver run verb so users can execute a flow without writing Python — the most-requested DX gap per the issue body. Stacked on top of #157 (scaffolding refactor); the base auto-retargets to main once #157 merges.

chainweaver run flows/etl.flow.yaml \
    --tools my_pkg.tools \
    --input '{"date": "2026-05-15"}'

Closes #129.

Changes

• chainweaver/cli.py — new run_command, two private helpers (_import_tools_from, _parse_initial_input), _run_result_to_table renderer, module-docstring update listing the verb.
• tests/test_cli.py — TestRunCommand with 12 cases (happy path table + JSON, --input-file, --quiet, missing flow file (exit 2), unimportable tools module (exit 2), missing tool (exit 1), malformed JSON input, non-object input, missing --input/--input-file, mutual exclusion, invalid flow file).
• README.md — new "Command-line interface" section listing all five subcommands with run first.
• docs/v1-release-criteria.md §6 — adds chainweaver run to the v1 CLI checklist.

Behavior

Flag	Meaning
--tools <module> (repeatable, -t)	Python import path; module's top-level Tool instances are registered, de-duplicated by Tool.name.
--input <json-string> (-i)	JSON object passed as initial_input. Mutually exclusive with --input-file.
--input-file <path>	Path to a JSON file holding the initial input object.
--format table|json (-f)	Default table shows step rows + final_output; json emits ExecutionResult.model_dump_json().
--quiet (-q)	Suppress stdout/stderr; result via exit code only.

Exit codes match the existing contract:

• 0 — flow succeeded.
• 1 — execution failed (result.success == False), missing tool, malformed input JSON, or CLI-level error.
• 2 — flow file or tools module not found / not importable.

On failure, the first failing StepRecord is also surfaced to stderr as chainweaver: step N (tool '<name>') failed: <error_message> so CI / scripts can grep without parsing table output.

Deferred per the issue body

Per the issue's "once that lands" framing:

• --checkpoint <path> — depends on Checkpointer (PR Add middleware, caching, checkpointing, streaming, and OTel support #136). Will be added in a small follow-up once that lands.
• --cache <path> — depends on StepCache (PR Add middleware, caching, checkpointing, streaming, and OTel support #136). Same.
• Plugin entry-point fallback for tool discovery — depends on Add Python entry-point discovery for community-contributed tools and flows #130.

No half-wired stubs were added now.

Testing

• Linting passes (ruff check chainweaver/ tests/ examples/)
• Formatting check passes (ruff format --check chainweaver/ tests/ examples/)
• Type checking passes (python -m mypy chainweaver/ tests/)
• All existing tests pass (python -m pytest tests/ -v --no-cov) — 479/479 passed in 1.77s (467 pre-existing + 12 new)
• New tests added for new functionality

$ ruff check chainweaver/ tests/ examples/
All checks passed!
$ ruff format --check chainweaver/ tests/ examples/
49 files already formatted
$ python -m mypy chainweaver/ tests/
Success: no issues found in 42 source files
$ python -m pytest tests/ -q --no-cov
479 passed in 1.77s

Diff stat: 4 files changed, 625 insertions(+), 1 deletion(-) (240 LoC of CLI code + 353 LoC of tests + 31 LoC README + 2 LoC v1 criteria).

Related Issues

Closes #129.

Checklist

• Code follows project conventions (see AGENTS.md and docs/agent-context/)
• Public API changes are documented — run_command is reachable via the chainweaver console script; CLI docstring + README + v1-release-criteria all updated
• No secrets or credentials included

Tradeoffs / risks

• Tool import side-effects. Loading a user-supplied module via importlib.import_module runs that module's top-level code. Documented in the issue and in the per-flag help; out-of-scope to sandbox here.
• Deferred flags vs immediate stubs. Per the issue body these flags are "no-op until the underlying issue ships." I chose to defer them entirely rather than land dead-flag stubs that would mislead --help consumers. Easy 1-flag follow-up PRs once Add Checkpointer protocol for crash-resume of in-flight executions #128 / Add step-result caching layer for deterministic tool outputs #127 / Add Python entry-point discovery for community-contributed tools and flows #130 merge.
• Initial-input JSON-object constraint. --input '[1,2,3]' is rejected with exit 1. Justification: every Flow.input_schema is a Pydantic BaseModel, which requires a dict input. Accepting non-objects would force an artificial conversion. Flagged here in case you'd prefer to relax it.

Scope notes

Closes #129 only. Adjacent items (cookbook recipe in #146, GH Action wrapper in #149) are intentionally deferred to their own issues.

https://claude.ai/code/session_01QcSJ3NWhe5B4k1EP25Hx3n

---

Generated by Claude Code