CLI

The VisualQ CLI (@visualq/cli) is a zero-dependency command-line client for the CI REST API. Use it in GitLab CI, Jenkins, CircleCI, Bitbucket Pipelines, Azure Pipelines, or local scripts to trigger quality audits and fail the pipeline when checks do not pass.

For GitHub-hosted repositories, the dedicated GitHub Action adds native check runs and PR comments. For other CI systems, the CLI is the recommended integration surface.

Install

Run directly with npx (no install step):

npx @visualq/cli run --api-key $VISUALQ_API_KEY --project my-website

Or install globally:

npm install -g @visualq/cli
visualq run --api-key $VISUALQ_API_KEY --project my-website

Authentication uses an API key with scope ci or mcp_full. Keys scoped mcp_read cannot trigger runs.

Quick start

export VISUALQ_API_KEY=vq_your_key_here

# Visual regression test (default CI use case)
visualq run --project my-website --environment staging

# Check an existing run
visualq status run_abc123

# List projects accessible with your key
visualq projects

When the API key is project-scoped, --project is optional — the key's associated project is used automatically.

Commands

All run commands (run, baseline, perf, …) trigger POST /api/ci/run, poll GET /api/ci/status/{runId} until completion (unless --no-wait), and exit with a non-zero code when the run fails or checks do not pass.

Options

These options apply to all run commands unless noted otherwise.

status and projects accept --api-key, --api-url, and --locale only.

Environment variables

CI auto-detection

When running inside a supported CI environment, the CLI automatically fills --commit, --branch, --pr, --pr-url (where available), and --ci. Explicit flags always take priority.

On GitLab CI, --pr maps to the merge request IID (the number shown as !123 in the UI), not the internal MR ID.

Examples

Visual regression on staging

visualq run \
  --api-key $VISUALQ_API_KEY \
  --project my-website \
  --environment staging \
  --scenarios "Homepage,Login"

Capture baselines after deploy

visualq baseline \
  --api-key $VISUALQ_API_KEY \
  --project my-website \
  --environment production

Performance audit with budgets

visualq perf \
  --api-key $VISUALQ_API_KEY \
  --project my-website \
  --perf-budgets '{"lcp":2500,"cls":0.1,"score":75}'

The CLI exits with code 1 when any budget threshold is exceeded.

SEO, accessibility, security, analytics

visualq seo       --api-key $VISUALQ_API_KEY --project my-website
visualq a11y      --api-key $VISUALQ_API_KEY --project my-website --browsers chromium,firefox
visualq security  --api-key $VISUALQ_API_KEY --project my-website
visualq analytics --api-key $VISUALQ_API_KEY --project my-website

Fire-and-forget (manual status check)

visualq run --api-key $VISUALQ_API_KEY --project my-website --no-wait
# {"runId":"run_abc123","status":"started"}

visualq status run_abc123 --api-key $VISUALQ_API_KEY

Link results to Jira

visualq run \
  --api-key $VISUALQ_API_KEY \
  --project my-website \
  --jira-key PROJ-456

CI/CD integration examples

GitLab CI

visual-regression:
  stage: test
  image: node:20
  script:
    - npx @visualq/cli run --project "$VISUALQ_PROJECT" --environment staging
  variables:
    VISUALQ_API_KEY: $VISUALQ_API_KEY
    VISUALQ_PROJECT: my-website
  rules:
    - if: $CI_MERGE_REQUEST_IID

Commit SHA, branch, MR number, and provider are auto-detected — no extra flags needed.

Jenkins

stage('Visual Regression') {
    environment {
        VISUALQ_API_KEY = credentials('visualq-api-key')
    }
    steps {
        sh '''
            npx @visualq/cli run \
                --api-key "$VISUALQ_API_KEY" \
                --project my-website \
                --environment staging
        '''
    }
}

SEO gate before merge

seo-audit:
  stage: test
  image: node:20
  script:
    - npx @visualq/cli seo --project my-website --environment staging
  variables:
    VISUALQ_API_KEY: $VISUALQ_API_KEY
    VISUALQ_PROJECT: my-website

See Other CI systems for CircleCI, Jenkins declarative pipeline, and curl-based patterns.

Polling and timeouts

By default, run commands poll every 5 seconds for up to 5 minutes. While waiting, the CLI prints progress lines prefixed with [visualq].

When the run completes:

• VRT / baseline / a11y / security / analytics — fails if summary.failed > 0
• perf — fails if performance budgets are exceeded (perfBudgetResult.pass === false)
• seo — fails if seoFailed > 0

Use --no-wait to skip polling and handle status yourself with visualq status.

Exit codes

Out of scope

The CLI covers CI-triggerable audits via /api/ci/run. It does not replace the VisualQ dashboard for:

For agent-driven workflows beyond CI triggers, see the MCP integration.

Related

• API keys — create and scope keys
• REST API — raw HTTP reference for /api/ci/*
• CI endpoints — request/response schemas
• GitHub Action — native GitHub integration
• Environments — staging / production base URLs