CLI & CI gate

One dependency-free command starts a suite, waits for the verdict and exits with a code your pipeline understands. PASS deploys; FAIL blocks; INCONCLUSIVE is your call.

Written from the code · updated 26 Sep 2026 · Something wrong or missing? Tell us

Install

The CLI is a single Node 22 script with no dependencies, so it runs straight from the repository or from npm:

npx @colvo/cli run --project <project id> --wait

Configuration

Option / env	Meaning
COLVO_API_KEY	Backend key (`cak_…`). Required.
COLVO_API_URL	Defaults to `https://colvo.app`.
--project	Project id. Required.
--build	Agent build id; defaults to the project default.
--scenarios	Comma-separated template keys; default: whole library.
--repeats	1–5, default 3.
--label	Free text shown in the console (e.g. the commit).
--wait / --no-wait	Wait for the verdict (default) or just start.
--timeout	Minutes to wait, default 15.
--inconclusive-exit	Exit code for INCONCLUSIVE: 0, 1 or 2 (default).

Exit codes

Code	Meaning
0	PASS
1	FAIL — a proven defect; do not deploy
2	INCONCLUSIVE — not a proven defect, but do not deploy blindly (configurable)
3	Usage, API or timeout error (including `402` plan limit)

GitHub Actions

name: colvo-gate
on: [push]
jobs:
  suite:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - name: Run the COLVO suite
        env:
          COLVO_API_KEY: ${{ secrets.COLVO_API_KEY }}
        run: npx @colvo/cli run --project ${{ vars.COLVO_PROJECT_ID }} --label "${{ github.sha }}" --wait

Point the build at a staging deployment of your agent (a build whose endpoint is the preview URL) and the gate runs on every push. GitLab CI, CircleCI and plain shells work the same way; only the exit code matters.

← Test APIWebhooks →