CI gates

Use CI gates when you want the build to fail if identified waste crosses a limit or required detector coverage is unavailable.

Threshold flags

--fail-above-waste-rate <n> fails with exit code 3 when structuralWasteRate is above the threshold
--fail-above-waste-usd <n> fails with exit code 3 when confirmed wasteSpendUsd is above the threshold

Both monetary thresholds exit with code 5 when no active monetary detector assessed eligible request evidence from the source. Earlier versions could exit 0 against a non-conclusive zero in that state. Improve the source evidence, intentionally handle exit 5, or remove a threshold the available evidence cannot evaluate. A partial or full result with positive eligible request evidence from at least one monetary detector remains evaluable; use --require-detection-coverage when CI requires stricter completeness. These thresholds use only detector-owned avoidableSpendUsd from the three active monetary findings. Neutral signals never affect an exit code. QM gates fail closed: when any underlying QM request is unpriced, a requested USD or waste-rate threshold cannot make a truthful monetary assertion and exits 5. In particular, unresolved openrouter/auto and negative placeholders are not treated as $0.

Recommended pattern

If you also want the audit recorded remotely, use one command:

npx @xerg/cli@latest audit --push --fail-above-waste-rate 0.30

xerg audit pushes before threshold checks run, so the audit still gets sent even if the command ultimately exits with code 3.

Examples

Identified-waste rate gate:

npx @xerg/cli@latest audit --fail-above-waste-rate 0.30

Require detector coverage before treating the result as a CI assertion:

npx @xerg/cli@latest audit --require-detection-coverage full

Use partial to accept partial or full request-sequence coverage. An unmet coverage requirement exits 5; threshold breaches continue to exit 3. Absolute USD gate:

npx @xerg/cli@latest audit --fail-above-waste-usd 50

Remote gate:

npx @xerg/cli@latest audit --remote deploy@prod.example.com --fail-above-waste-rate 0.20

Exit codes

Exit code	Meaning
`0`	Success
`1`	General failure
`2`	No economic runtime data was found, or activation is required
`3`	A waste threshold was exceeded
`5`	Required observer liveness or detector coverage failed, a monetary threshold cannot be evaluated, or standalone `xerg push` hit a hosted quota/member/capability/history product condition

For compatibility, xerg audit --push still maps the same hosted product-condition rejection to general error 1; use the command-specific code rather than assuming both push paths are identical.

GitHub Actions example

name: xerg
on:
  pull_request:
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx @xerg/cli@latest audit --push --fail-above-waste-rate 0.30
        env:
          XERG_API_KEY: ${{ secrets.XERG_API_KEY }}

Adjust the command if your audit needs explicit paths, SSH access, or a Railway target.

Concepts

Hosted workspace

Automate and share

Releases

Threshold flags

Recommended pattern

Examples

Exit codes

GitHub Actions example

​Threshold flags

​Recommended pattern

​Examples

​Exit codes

​GitHub Actions example

Threshold flags

Recommended pattern

Examples

Exit codes

GitHub Actions example