ci
Audit a deployed URL in the cloud and fail the job on findings new since the previous audit
The ci command audits a deployed URL in the cloud as one of your websites, waits for the audit, and exits
non-zero when it has findings that the previous completed audit of that website did not have.
It is a real cloud audit: it appears in the website’s audit history in the dashboard and is
charged like any cloud audit. It is not a local squirrel audit, and it is separate from --fail-on, which gates on
thresholds. The comparison is made by the API (GET /v1/websites/{websiteId}/audits/compare), so the CLI, a plain
curl and any other client read new-versus-previous the same way. See
Fail the build on new findings.
Usage
squirrel ci <url> --website <id> [options]It needs an org API key with the audits:read and audits:write scopes in SQUIRRELSCAN_API_KEY (mint one with
squirrel keys create). --website is the website’s id: the id shown in the dashboard, or the
websiteId of any earlier audit of it.
Options
| Option | Description |
|---|---|
--website <id> | The website the audit belongs to. Its previous completed audit is the baseline. Required |
--fail-on-new <severity> | Fail on new findings at or above error (default), warning or info |
--max-pages <n> | Page limit for the cloud audit. A smaller crawl than the baseline leaves findings on the pages it skipped as not compared, never as resolved |
--timeout <minutes> | How long to wait for the audit (default 30). The run keeps going in the cloud if the wait ends |
--json | Print one JSON object on stdout instead of the text summary |
Progress goes to stderr, so --json keeps stdout clean.
Exit codes
| Code | Meaning |
|---|---|
0 | No new findings at or above the severity, or this is the first audit of the website (no baseline) |
2 | New findings at or above --fail-on-new since the previous completed audit |
3 | The site blocked the crawler (a WAF or bot manager), so nothing was compared |
5 | The site could not be reached, so nothing was compared |
1 | An operational error: bad flags or key, the audit could not start (for example no credits), did not finish in time, failed, or the comparison could not say (gate.status: not_evaluated) |
A blocked or unreachable site never exits 2, and not_evaluated is never a pass: its reason is printed. Findings
that were resolved since the previous audit are listed and never fail the job. Findings on pages the new audit did
not crawl, or from rules it did not run, are neither new nor resolved; the output says how many.
Output
Audit of https://shop.example.com/ (run 01J0RUNEXAMPLE): completed, health score 81
Gate (fail on new error): FAIL: 1 new error since the previous audit
New findings (1):
error links/broken-internal https://shop.example.com/products/a
Resolved findings (1, never fail the job):
warning core/meta-title https://shop.example.com/about
Not compared: 2 on pages not crawled, 3 from rules not run (neither new nor resolved)
Report: https://acme.squirrel.report/01J0REPORTEXAMPLE
Credits used: 52 (balance 400 -> 348; other runs on the org in the same window count too)The credits line is the balance change across the run, read from GET /v1/credits before and after, so another run
on the same organization in that window counts too. On an unmetered plan it says usage is invoiced instead.
The first audit of a website prints No baseline and exits 0.
Example
export SQUIRRELSCAN_API_KEY=... # an org API key, kept in your CI secrets
squirrel ci https://staging.example.com --website "$WEBSITE_ID" --fail-on-new warning