-
Notifications
You must be signed in to change notification settings - Fork 48
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
3 changed files
with
48 additions
and
202 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| packages/cli/README.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,225 +1,71 @@ | ||
| # @percy/cli | ||
| # Percy CLI | ||
|
|
||
| A collection of CLI commmands for taking Percy snapshots. | ||
|  | ||
|
|
||
| ## Commands | ||
| <!-- commands --> | ||
| * [`percy config:create [FILEPATH]`](#percy-configcreate-filepath) | ||
| * [`percy config:validate [FILEPATH]`](#percy-configvalidate-filepath) | ||
| * [`percy exec`](#percy-exec) | ||
| * [`percy exec:ping`](#percy-execping) | ||
| * [`percy exec:start`](#percy-execstart) | ||
| * [`percy exec:stop`](#percy-execstop) | ||
| * [`percy finalize`](#percy-finalize) | ||
| * [`percy help [COMMAND]`](#percy-help-command) | ||
| * [`percy snapshot PATHNAME`](#percy-snapshot-pathname) | ||
| * [`percy upload DIRNAME`](#percy-upload-dirname) | ||
| The Percy CLI is used to capture and upload snapshots to [percy.io](https://percy.io) from the | ||
| command line. | ||
|
|
||
| ## `percy config:create [FILEPATH]` | ||
| ## Installation | ||
|
|
||
| create a Percy config file | ||
| Using yarn: | ||
|
|
||
| ```sh-session | ||
| $ yarn add @percy/cli --dev | ||
| ``` | ||
| USAGE | ||
| $ percy config:create [FILEPATH] | ||
| ARGUMENTS | ||
| FILEPATH config filepath | ||
| OPTIONS | ||
| --js create a .percy.js file | ||
| --json create a .percy.json file | ||
| --rc create a .percyrc file | ||
| --yaml create a .percy.yaml file | ||
| --yml create a .percy.yml file | ||
| EXAMPLES | ||
| $ percy config:create | ||
| $ percy config:create --yaml | ||
| $ percy config:create --json | ||
| $ percy config:create --js | ||
| $ percy config:create --rc | ||
| $ percy config:create ./config/percy.yml | ||
| ``` | ||
|
|
||
| ## `percy config:validate [FILEPATH]` | ||
|
|
||
| validate a Percy config file | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ percy config:validate [FILEPATH] | ||
| ARGUMENTS | ||
| FILEPATH config filepath, detected by default | ||
| EXAMPLES | ||
| $ percy config:validate | ||
| $ percy config:validate ./config/percy.yml | ||
| ``` | ||
|
|
||
| ## `percy exec` | ||
|
|
||
| start and stop Percy around a supplied command | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ percy exec | ||
| OPTIONS | ||
| -c, --config=config configuration file path | ||
| -h, --allowed-hostname=allowed-hostname allowed hostnames | ||
| -q, --quiet log errors only | ||
| -t, --network-idle-timeout=network-idle-timeout [default: 100] asset discovery idle timeout | ||
| -v, --verbose log everything | ||
| --disable-asset-cache disable asset discovery caches | ||
| --silent log nothing | ||
| EXAMPLES | ||
| $ percy exec -- echo "percy is running around this echo command" | ||
| $ percy exec -- yarn test | ||
| ``` | ||
|
|
||
| ## `percy exec:ping` | ||
|
|
||
| pings a running Percy process | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ percy exec:ping | ||
| OPTIONS | ||
| -q, --quiet log errors only | ||
| -v, --verbose log everything | ||
| --silent log nothing | ||
| EXAMPLE | ||
| $ percy server:ping | ||
| ``` | ||
|
|
||
| ## `percy exec:start` | ||
|
|
||
| starts a Percy process | ||
| Using npm: | ||
|
|
||
| ```sh-session | ||
| $ npm install @percy/cli --save-dev | ||
| ``` | ||
| USAGE | ||
| $ percy exec:start | ||
| OPTIONS | ||
| -c, --config=config configuration file path | ||
| -h, --allowed-hostname=allowed-hostname allowed hostnames | ||
| -q, --quiet log errors only | ||
| -t, --network-idle-timeout=network-idle-timeout [default: 100] asset discovery idle timeout | ||
| -v, --verbose log everything | ||
| --disable-asset-cache disable asset discovery caches | ||
| --silent log nothing | ||
| EXAMPLES | ||
| $ percy server:start | ||
| $ percy server:start &>/dev/null | ||
| ``` | ||
|
|
||
| ## `percy exec:stop` | ||
|
|
||
| stops a running Percy process | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ percy exec:stop | ||
| ## Command Topics | ||
|
|
||
| OPTIONS | ||
| -q, --quiet log errors only | ||
| -v, --verbose log everything | ||
| --silent log nothing | ||
| - [`percy exec`](./packages/cli-exec#readme) - capture and upload snapshots | ||
| - [`percy snapshot`](./packages/cli-snapshot#readme) - snapshot a static directory or a list of pages | ||
| - [`percy upload`](./packages/cli-upload#readme) - upload a static directory of images | ||
| - [`percy config`](./packages/cli-config#readme) - manage configuration files | ||
| - [`percy finalize`](./packages/cli-finalize#readme) - finalize parallel builds | ||
|
|
||
| EXAMPLE | ||
| $ percy server:stop | ||
| ``` | ||
| ### Advanced | ||
|
|
||
| ## `percy finalize` | ||
| In addition to the CLI packages, this repo contains core libraries responsible for Percy's CI/CD | ||
| integrations, Percy API communication, DOM snapshotting, and asset discovery. | ||
|
|
||
| finalize parallel Percy builds | ||
| - [`@percy/env`](./packages/env#readme) - captures CI build environment variables | ||
| - [`@percy/client`](./packages/client#readme) - handles communicating with the Percy API | ||
| - [`@percy/dom`](./packages/dom#readme) - serializes DOM snapshots | ||
| - [`@percy/core`](./packages/core#readme) - performs snapshot asset discovery and uploading | ||
| - [`@percy/logger`](./packages/logger#readme) - common logger used throughout the CLI | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ percy finalize | ||
| ## Issues | ||
|
|
||
| OPTIONS | ||
| -q, --quiet log errors only | ||
| -v, --verbose log everything | ||
| --silent log nothing | ||
| For problems directly related to the CLI, [add an issue on | ||
| GitHub](https://github.com/percy/percy-cli/issues/new). | ||
|
|
||
| EXAMPLE | ||
| $ percy finalize | ||
| ``` | ||
| For other issues, [open a support request](https://percy.io). | ||
|
|
||
| ## `percy help [COMMAND]` | ||
| ## Developing | ||
|
|
||
| display help for percy | ||
| This project is built with [lerna](https://lerna.js.org/). The core libaries and CLI plugins are | ||
| located in [./packages](./packages). Run `yarn` to install dependencies after cloning the repo and use | ||
| the following scripts for various development tasks: | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ percy help [COMMAND] | ||
| - `yarn build` - build all packages | ||
| - `yarn build:watch` - build and watch all packages in parallel | ||
| - `yarn clean` - clean up build and coverage output | ||
| - `yarn lint` - lint all packages | ||
| - `yarn readme` - generate oclif readme usage | ||
| - `yarn test` - run all tests, one package after another | ||
| - `yarn test:coverage` - run all tests with coverage, one package after another | ||
|
|
||
| ARGUMENTS | ||
| COMMAND command to show help for | ||
| Individual package scripts can be invoked using yarn's | ||
| [workspace](https://classic.yarnpkg.com/en/docs/cli/workspace/) command. For example: | ||
|
|
||
| OPTIONS | ||
| --all see all commands in CLI | ||
| ```sh-session | ||
| $ yarn workspace @percy/core test | ||
| ``` | ||
|
|
||
| _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v2.2.3/src/commands/help.ts)_ | ||
| ## Releasing | ||
|
|
||
| ## `percy snapshot PATHNAME` | ||
|
|
||
| snapshot a list of pages from a file or directory | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ percy snapshot PATHNAME | ||
| ARGUMENTS | ||
| PATHNAME path to a directory or file containing a list of pages | ||
| OPTIONS | ||
| -b, --base-url=base-url [default: /] the url path to serve the static directory from | ||
| -c, --config=config configuration file path | ||
| -d, --dry-run prints a list of pages to snapshot without snapshotting | ||
| -f, --files=files [default: **/*.{html,htm}] one or more globs matching static file paths to snapshot | ||
| -h, --allowed-hostname=allowed-hostname allowed hostnames | ||
| -i, --ignore=ignore one or more globs matching static file paths to ignore | ||
| -q, --quiet log errors only | ||
| -t, --network-idle-timeout=network-idle-timeout [default: 100] asset discovery idle timeout | ||
| -v, --verbose log everything | ||
| --disable-asset-cache disable asset discovery caches | ||
| --silent log nothing | ||
| EXAMPLES | ||
| $ percy snapshot ./public | ||
| $ percy snapshot pages.yml | ||
| ``` | ||
|
|
||
| ## `percy upload DIRNAME` | ||
|
|
||
| upload a directory of images | ||
|
|
||
| ``` | ||
| USAGE | ||
| $ percy upload DIRNAME | ||
| ARGUMENTS | ||
| DIRNAME directory of images to upload | ||
| OPTIONS | ||
| -c, --config=config configuration file path | ||
| -d, --dry-run prints a list of matching images to upload without uploading | ||
| -f, --files=files [default: **/*.{png,jpg,jpeg}] one or more globs matching image file paths to upload | ||
| -i, --ignore=ignore one or more globs matching image file paths to ignore | ||
| -q, --quiet log errors only | ||
| -v, --verbose log everything | ||
| --silent log nothing | ||
| EXAMPLE | ||
| $ percy upload ./images | ||
| ``` | ||
| <!-- commandsstop --> | ||
| **@todo** |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters