CLI

👍
Covered in this doc
Each CLI command and its options

🚧
Requires Node.js
The Percy CLI is written in Node.js and requires v10.0.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 start
percy stop
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: 125] Asset discovery network idle timeout (in milliseconds)

  --cache-responses                                [default: true] Caches successful network responses in asset
                                                   discovery

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: 125] 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 start

Starts the percy process.

USAGE
  $ percy start

OPTIONS
  -c, --config=config                              Path to percy config file
  -d, --detached                                   start as a detached process
  -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: 125] Asset discovery network idle timeout (in milliseconds)

EXAMPLE
  $ percy start
  info: percy has started on port 5338.

percy stop

Stops the percy process.

USAGE
  $ percy stop

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

EXAMPLE
  $ percy stop
  info: percy has stopped.

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