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.

• 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.
• 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.

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

The primary command is vizdiff upload:

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

Example:

vizdiff upload storybook-static

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"

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

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.

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.) unless overridden by flags.
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.

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

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

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