Get started

Compound pipeline CLI

Source

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.

bash
DATABASE_MIGRATE_URL=... npm run aperture:pipeline -- --org convexity --stages web-search:6,doc-parse:10,deep-research:1 --runs 10000 --discover-peers
bash
npm run aperture:pipeline -- --stackfile vitna.stack.json --pipeline research-report --ledger ./ledger.jsonl --max-run-cost-usd 0.15

Nothing 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, evidence rows, 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 --stages to 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 from stackfile.pipelines (or --stages) against the committed Witness market snapshot and any privateSkus declared in the Stackfile.
FlagMeaning
--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-DDRestrict --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-peersScan 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
--jsonEmit structured JSON report

Exit codes

CodeMeaning
0Evaluation succeeded and cleared any configured spend budget gates
1Register mode requested with neither DATABASE_MIGRATE_URL nor DATABASE_URL set
2Invalid 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)