@vizdiff/cli

The official command-line interface for VizDiff.io, the visual regression testing platform designed for modern component libraries.

This CLI tool allows you to easily upload your Storybook builds to VizDiff for visual testing, comparison, and approval workflows integrated directly with your Git workflow and GitHub Pull Requests.

Features

• Simple Upload: Upload your static Storybook build directory with a single command.
• Git Integration: Automatically detects the current Git commit SHA, branch name, and base commit/branch for comparison.
• CI Auto-Detection: Reads predefined CI variables (e.g. GitLab CI/CD) so commit, branch, base branch/commit, and merge request number are resolved automatically inside your pipeline.
• Flexible Configuration: Override detected Git information and API endpoint via command-line flags or environment variables.
• CI/CD Ready: Designed for easy integration into your continuous integration pipelines.

Installation

Install the CLI globally using npm:

npm install -g @vizdiff/cli

Or install it as a dev dependency in your project:

npm install --save-dev @vizdiff/cli
# or
yarn add --dev @vizdiff/cli

Usage

The primary command is vizdiff upload:

vizdiff upload <path-to-storybook-build-dir> [options]

Example:

vizdiff upload storybook-static

Authentication

You need a VizDiff Project Token to upload builds.

1. Find your Project Token in your VizDiff project: https://vizdiff.io/projects (You'll need to sign up for VizDiff if you haven't already).
2. Provide the token using either:
   • The VIZDIFF_PROJECT_TOKEN environment variable (recommended, especially for CI):

     export VIZDIFF_PROJECT_TOKEN="your_project_token_here"
     vizdiff upload storybook-static

   • The --token or -t command-line flag:

     vizdiff upload storybook-static --token="your_project_token_here"

Options

| Option | Alias | Environment Variable | Description | Default | | ----------------------- | ----- | ----------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------- | | --token | -t | VIZDIFF_PROJECT_TOKEN | (Required) Your VizDiff project token. | - | | --commit | -c | - | Git commit SHA being built. | Latest commit hash | | --branch | -b | - | Git branch name being built. | Current branch name | | --base-branch | | - | Base branch name for comparison (e.g., main, master). | Default repo branch | | --base-commit | | - | Base commit SHA for comparison. | Merge base with base branch | | --pr | | - | Pull/merge request number associated with the commit (if applicable). | - | | <storybook-build-dir> | | - | (Required) Path to the directory containing your static Storybook build (usually storybook-static). | - | | - | | VIZDIFF_API_URL | VizDiff API endpoint. For self-hosted deployments, point this at your ingress (e.g. https://vizdiff.corp.example.com/api). | https://vizdiff.io/api |

Example with overrides:

export VIZDIFF_PROJECT_TOKEN="your_project_token_here"
vizdiff upload storybook-static \
  --commit="abcdef1234567890" \
  --branch="feature/new-button" \
  --base-branch="main" \
  --pr=123

Git Integration Details

The CLI attempts to automatically determine the correct commit SHA, branch, and base comparison details using git commands within your repository:

• Commit SHA (--commit): Uses the hash of the latest commit (git log -1).
• Branch (--branch): Uses the current branch name (git status).
• Base Branch (--base-branch): Uses the repository's default branch (e.g., main or master, determined by looking at origin/HEAD).
• Base Commit (--base-commit):
  • If the current branch is the base branch, it uses the previous commit (HEAD~1).
  • If the current branch is not the base branch, it uses the merge base between the current branch and the base branch (git merge-base).

You can override any of these automatic detections using the corresponding command-line flags if needed.

CI Environment Auto-Detection

When running inside a supported CI provider, the CLI reads the provider's predefined environment variables instead of relying solely on the local git checkout (which on CI is often a shallow or detached clone). The resolution precedence for every metadata value is:

1. Explicit flags (e.g. --commit, --branch, --pr) — always win.
2. CI environment variables — used when the corresponding flag is not set.
3. Local git inference — used as a final fallback.

GitLab CI/CD

GitLab CI/CD is detected via the GITLAB_CI environment variable. The following predefined variables are mapped:

| Metadata | GitLab variable(s) | | ----------- | -------------------------------------------------------------------------- | | Commit SHA | CI_COMMIT_SHA | | Branch | CI_COMMIT_REF_NAME (fallback CI_COMMIT_BRANCH) | | MR number | CI_MERGE_REQUEST_IID | | Base branch | CI_MERGE_REQUEST_TARGET_BRANCH_NAME (fallback CI_DEFAULT_BRANCH) | | Base commit | CI_MERGE_REQUEST_TARGET_BRANCH_SHA (fallback CI_MERGE_REQUEST_DIFF_BASE_SHA) |

In a branch (push) pipeline only the commit, branch, and CI_DEFAULT_BRANCH base branch are available. In a merge request pipeline the CI_MERGE_REQUEST_* variables additionally supply the MR number and the target (base) branch and commit.

GitLab CI/CD Usage

Store your VizDiff project token as a masked CI/CD variable named VIZDIFF_PROJECT_TOKEN. If you run a self-hosted VizDiff deployment, also add a VIZDIFF_API_URL variable pointing at your ingress (e.g. https://vizdiff.corp.example.com/api); on vizdiff.io this can be omitted.

Minimal .gitlab-ci.yml that builds Storybook and uploads it on both branch pushes and merge requests:

visual-regression:
  image: node:20
  rules:
    # Run on merge request pipelines and on pushes to the default branch.
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  variables:
    # Required for self-hosted VizDiff. Omit on vizdiff.io.
    # VIZDIFF_API_URL must point at your self-hosted ingress, e.g.:
    VIZDIFF_API_URL: "https://vizdiff.corp.example.com/api"
  script:
    - npm ci
    - npm run build-storybook # outputs to ./storybook-static
    - npx @vizdiff/cli upload storybook-static
    # VIZDIFF_PROJECT_TOKEN is read from a masked CI/CD variable.
    # Commit, branch, base branch/commit, and MR number are auto-detected
    # from the GitLab predefined variables — no extra flags needed.

For merge request pipelines, GitLab automatically exposes CI_MERGE_REQUEST_IID and the target branch/commit, so VizDiff will compare against the MR's base and associate the result with the merge request.

How it Works

1. The CLI verifies the existence of necessary Storybook build files (project.json, index.json) in the specified directory.
2. It gathers Git metadata (commit, branch, etc.) from explicit flags, then CI predefined variables, then the local git checkout (in that precedence order).
3. The Storybook build directory is compressed into a .tar.gz archive.
4. The archive is uploaded to the VizDiff API endpoint (/upload/storybook) along with the project token and Git metadata.
5. VizDiff processes the Storybook, renders components, performs visual diffs against the base build, and reports the results back through the VizDiff web app and any configured GitHub checks.

Contributing

Contributions are welcome! Feel free to open an issue to start a discussion, and send a pull request with a suggested improvement.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For help and support, post an issue to this repository or visit vizdiff.io to find contact information for our support team.