zespan-gate is a small, dependency-free CLI that calls the same quality gate the dashboard’s Versions tab uses, and turns the pass/fail verdict into a process exit code — so a CI job (GitHub Actions, or anything else that checks an exit code) can block a merge or deploy on prompt quality without you hand-rolling the polling logic yourself.
zespan-gate doesn’t replace the dashboard workflow — it’s the same POST /v1/prompts/{name}/versions/{version}/gate route, called from CI instead of a click in the UI. A version gated from CI and one gated from the dashboard are held to the identical bar. See The quality gate for what the three checks (avg score delta, regression count, tool-call accuracy) mean and how to configure their thresholds.Install
zespan-gate binary into your project’s node_modules/.bin. You can also run it without installing via npx @zespan/cli.
Before you gate: link a dataset run
The gate scores a dataset run of the candidate prompt version against a baseline run — it doesn’t run your prompt for you. Produce that run first, either from the dashboard’s Run over dataset button or from your own pipeline usingDatasetsClient. See Dataset runs for the full SDK workflow (fetch items, run your pipeline, link() each result).
Once the candidate run’s items are linked, zespan-gate will trigger scoring for you automatically if it isn’t scored yet — you don’t need to score it manually first.
Usage
string
required
The prompt’s name.
number
required
The candidate prompt version number to gate.
string
required
The dataset run — with the candidate version’s traces already linked — to score and compare.
string
required
The evaluator to use as the judge for both the candidate and baseline runs.
string
A specific dataset run to compare against. Omit this and
--baseline-label both to default to the run tied to whatever currently holds the production label.string
Compare against the run tied to this label instead of
production (e.g. staging).string
Pin scoring to a specific project LLM connection (BYOK) instead of the project default.
string
Advanced: opt into a separate, optional fourth signal — the regression resolution rate. Pass the ID of a dataset run that has replay results from the regression-check flow (previously-failing test cases re-run against the candidate); the gate then also requires the share of those cases that now pass to clear the
regressionResolutionMin threshold (default 80%) before it can pass. This doesn’t change what feeds the regression-count check above, which always compares the candidate run against the baseline regardless of this flag — omit --regression-run-id and the gate evaluates only the original three signals.string
Your Zespan API key. Falls back to the
ZESPAN_API_KEY environment variable. One of the two is required.string
default:"https://api.zespan.com/v1"
Override the API base URL. Falls back to the
ZESPAN_API_URL environment variable. Only needed for a self-hosted deployment.number
default:"3000"
How often to re-check while the gate is scoring the candidate run.
number
default:"120000"
Give up and exit with an error if scoring hasn’t finished within this window.
Exit code contract
Treat exit code
2 differently from 1 in your pipeline if you want: 1 is a real quality regression worth a clear failure message on the PR, while 2 usually means the job is misconfigured or the run wasn’t prepared yet.
Example GitHub Actions step
needs: (or branch protection requiring this check) blocks the merge or deploy until the prompt version passes the gate.
Next steps
- The quality gate — what the three checks measure, default thresholds, and running the gate from the dashboard
- Dataset runs — link a dataset run from your own pipeline before gating it
- LLM Connections — required if the candidate run isn’t scored yet, since gating triggers real judge model calls