> Source: https://vitna.ai/docs/cli/aperture/pipeline > Raw Markdown: https://vitna.ai/docs/cli/aperture/pipeline.md > Corpus index: https://vitna.ai/llms.txt # 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. ```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](../../routing/pipelines.md) 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. | 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) |