@visualq/cli

Command-line interface for VisualQ visual regression testing. Trigger VRT runs from any CI/CD pipeline.

Install

npm install -g @visualq/cli
# or use directly with npx
npx @visualq/cli run --api-key vq_xxx --project my-site

Usage

# Run visual regression tests
visualq run --api-key vq_xxx --project my-site

# Create new baselines
visualq baseline --api-key vq_xxx --project my-site

# Run specific scenarios
visualq run --api-key vq_xxx --project my-site --scenarios "Homepage,Login"

# Check run status
visualq status <runId> --api-key vq_xxx

Options

| Option | Description | |--------|-------------| | --api-key <key> | API key (or set VISUALQ_API_KEY env var) | | --project <slug> | Project slug (optional if API key is project-scoped) | | --scenarios <list> | Comma-separated scenario labels | | --api-url <url> | API base URL (default: https://visualq.ai) | | --no-wait | Don't wait for completion | | --commit <sha> | Git commit SHA (auto-detected in CI) | | --branch <name> | Git branch name (auto-detected in CI) | | --pr <number> | PR / merge request number (auto-detected in CI) | | --ci <provider> | CI provider name (auto-detected) |

CI Auto-Detection

When running inside a supported CI environment, --commit, --branch, --pr, and --ci are automatically detected from environment variables. Explicit flags always take priority over auto-detected values.

| CI Provider | Detection variable | Commit | Branch | PR / MR | |-------------|-------------------|--------|--------|---------| | GitLab CI | $GITLAB_CI | $CI_COMMIT_SHA | $CI_COMMIT_REF_NAME | $CI_MERGE_REQUEST_IID | | GitHub Actions | $GITHUB_ACTIONS | $GITHUB_SHA | $GITHUB_HEAD_REF | Parsed from $GITHUB_REF | | CircleCI | $CIRCLECI | $CIRCLE_SHA1 | $CIRCLE_BRANCH | Parsed from $CIRCLE_PULL_REQUEST | | Jenkins | $JENKINS_URL | $GIT_COMMIT | $GIT_BRANCH | $CHANGE_ID | | Travis CI | $TRAVIS | $TRAVIS_COMMIT | $TRAVIS_BRANCH | $TRAVIS_PULL_REQUEST | | Bitbucket Pipelines | $BITBUCKET_COMMIT | $BITBUCKET_COMMIT | $BITBUCKET_BRANCH | $BITBUCKET_PR_ID | | Azure Pipelines | $BUILD_BUILDID | $BUILD_SOURCEVERSION | $BUILD_SOURCEBRANCH | $SYSTEM_PULLREQUEST_PULLREQUESTID |

This means most CI/CD configurations only need --project (and VISUALQ_API_KEY).

CI/CD Examples

GitHub Actions

name: Visual Regression
on: [pull_request]

jobs:
  visual-test:
    runs-on: ubuntu-latest
    steps:
      - uses: abecms/visualq-action@v1
        with:
          api-key: ${{ secrets.VISUALQ_API_KEY }}
          project: "your-project-slug"

For GitHub Actions, prefer the dedicated visualq-action which provides native check runs and PR comments.

GitLab CI

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

The CLI automatically reads $CI_COMMIT_SHA, $CI_COMMIT_REF_NAME, and $CI_MERGE_REQUEST_IID from the GitLab CI environment. This enables commit statuses and MR comments without extra flags.

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

CircleCI

jobs:
  visual-test:
    docker:
      - image: node:20
    steps:
      - run:
          name: Visual Regression
          command: npx @visualq/cli run --project "$VISUALQ_PROJECT"
          environment:
            VISUALQ_API_KEY: ${VISUALQ_API_KEY}
            VISUALQ_PROJECT: your-project-slug

Jenkins

stage('Visual Regression') {
    steps {
        sh '''
            npx @visualq/cli run \
                --api-key "$VISUALQ_API_KEY" \
                --project "your-project-slug"
        '''
    }
}

Exit Codes

• 0 — All scenarios passed
• 1 — Visual differences detected or run failed

License

MIT