Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

Covered in this doc

Each CLI command and its options

Requires Node.js

The Percy CLI is written in Node.js and requires v8.2.0+ to work correctly.

CLI on GitHub

Quick start

The fastest possible use of our CLI is with NPM's npx client. npx allows you to run any percy command with ease. Once you have set your PERCY_TOKEN environment variable, you can run any percy command with npx:

$ npx percy -v
$ npx percy upload ./example-screenshots
$ npx percy exec -- cypress run
$ npx percy snapshot ./_site

Installing

You can install the CLI locally in your project by running npm install -D @percy/agent (or yarn add -D @percy/agent) Once that's done, you can use npx (or yarn) to run any percy command in that projects directory:

$ npx percy -v
$ yarn percy -v

Commands

To see an evergreen and accurate version of the CLI flags, visit the CLI repos README.

  • percy exec
  • percy finalize
  • percy help [COMMAND]
  • percy snapshot [SNAPSHOTDIRECTORY]
  • percy upload [UPLOADDIRECTORY]

percy exec

Start and stop Percy around a supplied command.

USAGE
  $ percy exec

OPTIONS
  -c, --config=config                              Path to percy config file
  -h, --allowed-hostname=allowed-hostname          Allowable hostname(s) to capture assets from
  -p, --port=port                                  [default: 5338] Port
  -t, --network-idle-timeout=network-idle-timeout  [default: 50] Asset discovery network idle timeout (in milliseconds)

  --cache-responses                                [default: false] Enable caching network responses for asset discovery
                                                   (experimental)

EXAMPLES
  $ percy exec -- echo "percy is running around this echo command"
  $ percy exec -- bash -c "echo foo && echo bar"

percy finalize

Finalize a build. Commonly used for parallelized builds, especially when the number of parallelized processes is unknown.

USAGE
  $ percy finalize

OPTIONS
  -a, --all  (required)

EXAMPLE
  $ percy finalize --all
  [percy] Finalized parallel build.

percy help [COMMAND]

display help for percy

USAGE
  $ percy help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

percy snapshot [SNAPSHOTDIRECTORY]

Snapshot a directory containing a pre-built static website.

USAGE
  $ percy snapshot [SNAPSHOTDIRECTORY]

ARGUMENTS
  SNAPSHOTDIRECTORY  [default: .] A path to the directory you would like to snapshot

OPTIONS
  -b, --base-url=base-url                          [default: /] If your static files will be hosted in a subdirectory,
                                                   instead of the webservers root path, set that subdirectory with this
                                                   flag.

  -c, --config=config                              Path to percy config file

  -h, --allowed-hostname=allowed-hostname          Allowable hostname(s) to capture assets from

  -i, --ignore-files=ignore-files                  [default: ] Glob or comma-seperated string of globs for matching the
                                                   files and directories to ignore.

  -p, --port=port                                  [default: 5338] Port

  -s, --snapshot-files=snapshot-files              [default: **/*.html,**/*.htm] Glob or comma-seperated string of globs
                                                   for matching the files and directories to snapshot.

  -t, --network-idle-timeout=network-idle-timeout  [default: 50] Asset discovery network idle timeout (in milliseconds)

EXAMPLES
  $ percy snapshot _site/
  $ percy snapshot _site/ --base-url "/blog/"
  $ percy snapshot _site/ --ignore-files "/blog/drafts/**"

percy upload [UPLOADDIRECTORY]

Upload a directory containing static snapshot images.

USAGE
  $ percy upload [UPLOADDIRECTORY]

ARGUMENTS
  UPLOADDIRECTORY  [default: .] A path to the directory containing static snapshot images

OPTIONS
  -c, --config=config  Path to percy config file

  -f, --files=files    [default: **/*.png,**/*.jpg,**/*.jpeg] Glob or comma-seperated string of globs for matching the
                       files and directories to snapshot.

  -i, --ignore=ignore  [default: ] Glob or comma-seperated string of globs for matching the files and directories to
                       ignore.

EXAMPLES
  $ percy upload _images/
  $ percy upload _images/ --files **/*.png

CLI


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.