Sign in or start for free
Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2-web!

### [percy-cli on GitHub](🔗)

[![](https://travis-ci.org/percy/percy-cli.svg?branch=master)](🔗) [![](https://badge.fury.io/rb/percy-cli.svg)](🔗)

Percy makes it very simple to integrate visual regression testing for static websites, no matter what tools were used to generate it.

This can be especially useful for static sites generated by [Jekyll](🔗) (ie. for GitHub Pages), [Grow](🔗), [Middleman](🔗), or other static site generators.

# Installation





Make sure you have completed [Setup](🔗) of your CI service first. You can also test Percy in your [local development](🔗) environment.

First, install the Percy command-line client:


If you already have the client installed, you can update your old version by running:

# Local testing

Percy CLI relies on the `PERCY_TOKEN` environment variable for authenticating and authorizing access to each repository.
You can temporarily set it in your local shell session by exporting the variable:

Or you can set it just for the current command:


IMPORTANT: Keep your Percy token secret. Anyone with access to your token can consume your account quota, though they cannot read data.
See the Setup guides for how to securely set environment variables in your CI service.
# Usage

If your static site exists in a directory called `_site`, it's as simple as this:

That's it!
For example:

Percy now starts rendering pages and generating visual diffs for your site. Under the hood, Percy only uploads files that have changed---so after the first time this command is run, future runs will be very fast.
## In a CI service
You can do the above steps locally for testing, but to get continuous visual integration for your static site you'll need to run the `gem install percy-cli` and `percy snapshot _site/` commands as CI build steps for your project.
For example, in Travis CI, we can add these steps to `.travis.yml`:

The steps will be similar when configuring other CI services or other static site generators.
## Responsive testing
You can use Percy [responsive visual diffs](🔗) to test pages at different CSS breakpoints. Just pass the `--widths` flag with a comma-separated list of widths.

## Enable JavaScript
By default, JavaScript is not enabled in the Percy rendering environment (in Percy's other SDKs JavaScript is run in tests locally, but in the CLI no JavaScript is run). To enable it for your static site add this argument:

## Base URL path
If your static files are hosted in a sub-directory instead of the webserver root, you will need to provide the `--baseurl` flag:

For Jekyll users, this should be set to the same as your `baseurl` config setting.
# Changelog

  • [percy-cli releases on GitHub](🔗)
# Contributing

  1. Fork it (<https://github.com/percy/percy-cli/fork>)
  2. Create your feature branch (`git checkout -b my-new-feature`)
  3. Commit your changes (`git commit -am 'Add some feature'`)
  4. Push to the branch (`git push origin my-new-feature`)
  5. Create a new Pull Request
[Throw a ★ on it!](🔗)