From 3a970ba453d912760b1c39edc6850d17ca5a914f Mon Sep 17 00:00:00 2001 From: Wil Wilsman Date: Tue, 14 Apr 2020 18:44:05 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Update=20CLI=20readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + packages/cli/README.md | 246 +++++++------------------------------- packages/cli/package.json | 3 +- 3 files changed, 48 insertions(+), 202 deletions(-) create mode 120000 README.md diff --git a/README.md b/README.md new file mode 120000 index 000000000..284a18f47 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +packages/cli/README.md \ No newline at end of file diff --git a/packages/cli/README.md b/packages/cli/README.md index e672d12d1..02b53baea 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,225 +1,71 @@ -# @percy/cli +# Percy CLI -A collection of CLI commmands for taking Percy snapshots. +![CI](https://github.com/wwilsman/percy/workflows/Continuous%20Integration/badge.svg) -## 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 -``` - +**@todo** diff --git a/packages/cli/package.json b/packages/cli/package.json index 3ff5a353f..3295bd1e2 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -14,8 +14,7 @@ "scripts": { "lint": "eslint --ignore-path ../../.gitignore .", "postpublish": "rm -f oclif.manifest.json", - "prepublish": "oclif-dev manifest", - "readme": "oclif-dev readme" + "prepublish": "oclif-dev manifest" }, "oclif": { "bin": "percy",