CLI Runner

Swarm QA includes a CLI interface for running scans from the terminal — designed for CI/CD pipeline integration. The CLI uses HTTP-based checks (not a full browser) for speed and portability.

Commands

Command	Preset	Description
npm run swarm:run	Standard Scan	6 agents, 180s timeout, 20 pages
npm run swarm:quick	Quick Smoke	Link Patrol + Smoke Flow, 60s, 5 pages
npm run swarm:deep	Deep Audit	All 8 agents, 420s timeout, 50 pages

Flags

Flag	Description	Default
--target <url>	Target URL to scan	Required
--json	Output results as JSON to stdout	Off (human-readable)
--out <path>	Write results to a file instead of stdout	stdout
--threshold <n>	Minimum acceptable score (affects exit code)	0
--agents <list>	Comma-separated agent names to enable	Preset default

Exit Codes

Code	Meaning
0	Scan completed, score meets or exceeds threshold
1	Scan completed, score below threshold or critical findings detected
2	Scan failed (network error, auth failure, invalid target)

INFO

Exit code 1 on any fix-now finding makes the CLI a natural quality gate. A pipeline step using npm run swarm:quick -- --target $STAGING_URL fails the build if critical issues are found.

JSON Output Format

When --json is passed, the output follows this structure:

{
  "target": "https://staging.example.com",
  "score": 81,
  "duration": "2m 12s",
  "agents": {
    "link-patrol": { "findings": 3, "duration": "18s" },
    "smoke-flow": { "findings": 1, "duration": "12s" }
  },
  "findings": [
    {
      "agent": "link-patrol",
      "severity": "high",
      "action": "fix-now",
      "url": "https://staging.example.com/about",
      "message": "Broken link: /team returns 404",
      "evidence": "HTTP 404 on GET /team"
    }
  ]
}

Score Algorithm

The CLI uses the same scoring formula as the GUI:

score = 100 - (critical x 15) - (high x 8) - (medium x 3) - (low x 1)

Only first-party findings count. The score is clamped to a minimum of 0.

CI Pipeline Example

# GitLab CI
swarm-qa:
  stage: test
  script:
    - npm run swarm:quick -- --target $STAGING_URL --threshold 70 --json --out swarm-results.json
  artifacts:
    paths: [swarm-results.json]
    when: always

TIP

Use --json --out to save results as a build artifact. This works with GitLab CI, GitHub Actions, Jenkins, and any CI system that supports npm scripts.

WARNING

The CLI runner uses HTTP-based checks, not a full browser. Agents that require JavaScript rendering (Form Fuzzer, Visual Regression) are skipped in CLI mode. Use the GUI or scheduled scans for full coverage.

Related

• Swarm QA Overview
• Schedule & Webhooks
• Authentication