Compound pipeline CLI
Compute a multi-stage, multi-class AI pipeline Bill of Materials, attribute empirical x-vitna-run trace fan-out from a runtime ledger, discover eligible lower-cost Witness class peers, and enforce per-run or monthly spend budgets in CI.
DATABASE_MIGRATE_URL=... npm run aperture:pipeline -- --org convexity --stages web-search:6,doc-parse:10,deep-research:1 --runs 10000 --discover-peersnpm run aperture:pipeline -- --stackfile vitna.stack.json --pipeline research-report --ledger ./ledger.jsonl --max-run-cost-usd 0.15Nothing is written to the database or disk. Every actionable optimization prints the exact operator command (aperture:decide, aperture:candidate:add, aperture:evidence:add, or aperture:rule:add). See Multi-class unit profiles and compound pipelines for how stage fan-out, provenance splits, and optimization buckets are derived.
Modes and flags
- Register mode (
--org <slug>): reads active workloads, standing decisions, registered candidates,evidencerows, live Witness and customer-entered private rates, provider compliance terms, and three-provenance SKU capabilities. Pass--stages <slug:calls,...>to define stage order and fan-out, or omit--stagesto evaluate all active workloads in the organisation. - Offline Stackfile mode (
--stackfile <vitna.stack.json>): runs with zero database connection for CI checks and architecture planning, reading pipeline definitions fromstackfile.pipelines(or--stages) against the committed Witness market snapshot and anyprivateSkusdeclared in the Stackfile.
| Flag | Meaning |
|---|---|
--org <slug> | Evaluate workloads registered in <slug> |
--stages <spec> | Comma-separated <slug>[:<invocationsPerRun>][:bg] list |
--stackfile <file> | Run offline against a vitna.stackfile.v1 file with no database |
--pipeline <slug> | Select a named entry from stackfile.pipelines |
--runs <n> | Monthly pipeline execution volume (monthlyRuns) |
--run-label <label> | Plural label for one pipeline run (default runs) |
--ledger <file.jsonl> | Group vitna-runtime JSONL rows by runId (x-vitna-run) for empirical stage fan-out |
--agent <agentId> | Filter --ledger rows to one x-vitna-agent identifier |
--window YYYY-MM-DD..YYYY-MM-DD | Restrict --ledger rows to one closed UTC date range |
--evidence <evals.json> | Supply offline evaluation measurements in --stackfile mode |
--terms <terms.json> | Supply offline provider compliance terms in --stackfile mode |
--discover-peers | Scan active Witness SKUs in each stage's class for eligible lower-cost exploratory levers |
--max-run-cost-usd <usd> | CI gate: exit 4 if totals.costPerRunUsd exceeds <usd> or any stage is unpriceable |
--max-monthly-cost-usd <usd> | CI gate: exit 4 if totals.monthlyCostUsd exceeds <usd> or monthlyRuns is unset |
--json | Emit structured JSON report |
Exit codes
| Code | Meaning |
|---|---|
0 | Evaluation succeeded and cleared any configured spend budget gates |
1 | Register mode requested with neither DATABASE_MIGRATE_URL nor DATABASE_URL set |
2 | Invalid flags, malformed stage spec, unreadable input file, or unknown organisation/workload/pipeline |
4 | --max-run-cost-usd or --max-monthly-cost-usd gate was exceeded (or a stage was unpriceable under a gate) |
