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.
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
Updated almost 3 years ago