> 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) |
