0
# Percy CLI
1

2
Percy CLI is a comprehensive command-line tool for visual testing that enables developers to capture, upload, and manage visual snapshots for web applications. It provides a unified interface for interacting with the Percy visual testing platform, offering commands for taking snapshots of static directories, executing test suites with visual capture, uploading images, and managing Percy builds and configurations.
3

4
## Package Information
5

6
- **Package Name**: @percy/cli
7
- **Package Type**: npm
8
- **Language**: JavaScript/Node.js
9
- **Installation**: `npm install --save-dev @percy/cli`
10

11
## Core Imports
12

13
The Percy CLI is primarily used as a command-line tool, but it also exports programmatic functions:
14

15
```javascript
16
import { percy, checkForUpdate } from "@percy/cli";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { percy, checkForUpdate } = require("@percy/cli");
23
```
24

25
## Basic Usage
26

27
### Command Line Interface
28

29
The primary interface is the `percy` command-line tool:
30

31
```bash
32
# Install Percy CLI
33
npm install --save-dev @percy/cli
34

35
# Set Percy token
36
export PERCY_TOKEN=your-percy-token
37

38
# Take snapshots of a test suite
39
percy exec -- npm test
40

41
# Snapshot a static directory
42
percy snapshot ./public
43

44
# Upload directory of images
45
percy upload ./screenshots
46
```
47

48
### Programmatic Interface
49

50
```javascript
51
import { percy } from "@percy/cli";
52

53
// Run Percy CLI programmatically
54
await percy(['exec', '--', 'npm', 'test']);
55
```
56

57
## Architecture
58

59
Percy CLI is built around several key components:
60

61
- **Command Framework**: Extensible command system that discovers and loads CLI commands from multiple packages
62
- **Core Engine**: `@percy/core` provides browser automation, asset discovery, and snapshot coordination
63
- **API Client**: `@percy/client` handles all communication with Percy's visual testing service
64
- **Configuration System**: `@percy/config` manages configuration loading, validation, and migration
65
- **Logging System**: `@percy/logger` provides consistent, structured logging across all components
66

67
## Capabilities
68

69
### Core CLI Operations
70

71
Essential Percy workflow commands for starting, stopping, and executing visual tests with any test runner or static content.
72

73
```bash { .api }
74
percy exec -- <command>     # Start Percy, run command, then stop
75
percy start                  # Start Percy process in background
76
percy stop                   # Stop Percy process
77
percy ping                   # Check if Percy process is running
78
```
79

80
[Core Operations](./core-operations.md)
81

82
### Static Site Snapshots
83

84
Capture visual snapshots of static directories, file lists, or sitemaps without requiring a test runner.
85

86
```bash { .api }
87
percy snapshot <dir|file|sitemap>  # Snapshot static content
88
  --base-url <url>                 # Base URL for hosted pages
89
  --include <pattern>              # Include patterns (multiple)
90
  --exclude <pattern>              # Exclude patterns (multiple)
91
  --clean-urls                     # Remove file extensions from URLs
92
```
93

94
[Static Snapshots](./static-snapshots.md)
95

96
### Build Management
97

98
Commands for managing Percy builds, including waiting for completion, finalizing parallel builds, and reviewing build results.
99

100
```bash { .api }
101
percy build wait                    # Wait for build completion
102
  --build <build-id>                # Specific build ID
103
  --project <project>               # Project slug
104
  --commit <sha>                    # Commit SHA
105
  --timeout <ms>                    # Timeout duration
106
  --fail-on-changes                 # Exit with error on diffs
107

108
percy build finalize               # Finalize parallel builds
109
percy build id                     # Print current build ID
110
percy build approve <build-id>     # Approve build
111
percy build reject <build-id>      # Reject build
112
percy build delete <build-id>      # Delete build
113
```
114

115
[Build Management](./build-management.md)
116

117
### Configuration Management
118

119
Tools for creating, validating, and migrating Percy configuration files across different formats.
120

121
```bash { .api }
122
percy config create [filepath]     # Create new config file
123
  --rc                             # Create .percyrc
124
  --yaml                           # Create .percy.yaml
125
  --json                           # Create .percy.json
126
  --js                             # Create .percy.js
127

128
percy config validate [filepath]   # Validate config file
129
percy config migrate [filepath]    # Migrate to latest format
130
  --dry-run                        # Show migration without writing
131
```
132

133
[Configuration](./configuration.md)
134

135
### Image Uploads
136

137
Direct upload of image files as visual snapshots, useful for integrating with external screenshot tools.
138

139
```bash { .api }
140
percy upload <dirname>             # Upload image directory
141
  --files <pattern>                # File patterns (default: **/*.{png,jpg,jpeg})
142
  --ignore <pattern>               # Ignore patterns
143
  --strip-extensions               # Remove extensions from snapshot names
144
```
145

146
[Image Uploads](./image-uploads.md)
147

148
### Native App Snapshots
149

150
Specialized commands for visual testing of native mobile applications with Percy's app testing platform.
151

152
```bash { .api }
153
percy app exec -- <command>       # Execute with Percy for native apps
154
percy app start                    # Start Percy for native apps
155
percy app stop                     # Stop Percy app process
156
percy app ping                     # Ping Percy app process
157
```
158

159
[App Snapshots](./app-snapshots.md)
160

161
### Programmatic API
162

163
Advanced APIs for SDK development, custom integrations, and deep Percy automation. Includes the Percy core engine, configuration system, API client, environment detection, and utility libraries.
164

165
```javascript { .api }
166
import Percy from "@percy/core";              // Core visual testing engine
167
import { load, validate } from "@percy/config";  // Configuration system
168
import PercyClient from "@percy/client";      // Percy API client
169
import PercyEnv from "@percy/env";            // CI environment detection
170
```
171

172
[Programmatic API](./programmatic-api.md)
173

174
## Global Options
175

176
All Percy commands support these global flags:
177

178
```bash { .api }
179
# Logging Control
180
--verbose, -v                      # Log everything (debug level)
181
--quiet, -q                        # Log errors only
182
--silent, -s                       # Log nothing
183

184
# Percy Configuration
185
--config, -c <path>                # Configuration file path
186
--dry-run, -d                      # Print snapshot names without uploading
187
--labels, -l <labels>              # Build labels (comma-separated)
188

189
# Server Configuration
190
--port, -P <port>                  # Local server port (default: 5338)
191

192
# Asset Discovery
193
--allowed-hostname <pattern>       # Allowed hostname patterns
194
--disallowed-hostname <pattern>    # Disallowed hostname patterns
195
--network-idle-timeout <ms>        # Network idle timeout
196
--disable-cache                    # Disable asset caching
197
--debug                            # Debug asset discovery
198
```
199

200
## Environment Variables
201

202
### Required Configuration
203

204
```bash { .api }
205
PERCY_TOKEN                        # Percy project token (required)
206
```
207

208
### Optional Configuration
209

210
```bash { .api }
211
# Build Configuration
212
PERCY_PARALLEL_TOTAL               # Number of parallel processes
213
PERCY_PARALLEL_NONCE               # Parallel build identifier
214
PERCY_PARTIAL_BUILD                # Mark build as partial (1 to enable)
215
PERCY_BUILD_ID                     # Build identifier (set by percy exec)
216
PERCY_BUILD_URL                    # Build URL (set by percy exec)
217
PERCY_COMMIT                       # Override commit SHA
218
PERCY_BRANCH                       # Override branch name
219

220
# Logging Configuration
221
PERCY_DEBUG                        # Debug namespace patterns
222
PERCY_LOGLEVEL                     # Global log level
223
PERCY_SKIP_UPDATE_CHECK           # Skip version checks (1 to enable)
224
PERCY_CLIENT_ERROR_LOGS           # Enable client error logging (1 to enable)
225

226
# Advanced Configuration
227
PERCY_CLIENT_API_URL              # Override Percy API URL
228
PERCY_CONFIG                      # Configuration file path
229
PERCY_GZIP                        # Enable gzip compression (1 to enable)
230
PERCY_RESOURCE_UPLOAD_CONCURRENCY # Upload concurrency limit
231
PERCY_SERVER_ADDRESS              # Percy server address for SDK communication
232
PERCY_ENABLE                      # Enable/disable Percy (0 to disable)
233
PERCY_GITHUB_ACTION               # GitHub Action identifier
234
PERCY_DISABLE_SYSTEM_MONITORING   # Disable system monitoring (1 to disable)
235

236
# CI Environment Variables (detected automatically)
237
# Travis CI
238
TRAVIS_BUILD_ID                   # Travis build identifier
239
TRAVIS_COMMIT                     # Travis commit SHA
240
TRAVIS_PULL_REQUEST               # Travis PR number
241
TRAVIS_BRANCH                     # Travis branch name
242

243
# Jenkins
244
JENKINS_URL                       # Jenkins server URL
245
GIT_COMMIT                        # Git commit SHA
246
ghprbPullId                       # GitHub PR builder pull ID
247
GIT_BRANCH                        # Git branch name
248

249
# CircleCI
250
CIRCLECI                          # CircleCI indicator
251
CIRCLE_SHA1                       # Circle commit SHA
252
CIRCLE_BRANCH                     # Circle branch name
253
CIRCLE_BUILD_NUM                  # Circle build number
254

255
# GitHub Actions
256
GITHUB_ACTIONS                    # GitHub Actions indicator
257
GITHUB_SHA                        # GitHub commit SHA
258
GITHUB_REF                        # GitHub reference
259

260
# GitLab CI
261
GITLAB_CI                         # GitLab CI indicator
262
CI_COMMIT_SHA                     # GitLab commit SHA
263
CI_COMMIT_REF_NAME               # GitLab branch name
264
CI_MERGE_REQUEST_IID             # GitLab merge request ID
265

266
# Azure DevOps
267
TF_BUILD                          # Team Foundation indicator
268
BUILD_SOURCEVERSION               # Azure commit SHA
269
BUILD_SOURCEBRANCH                # Azure branch name
270
SYSTEM_PULLREQUEST_PULLREQUESTID  # Azure PR ID
271
```
272

273
## Types
274

275
### Programmatic API Types
276

277
```javascript { .api }
278
/**
279
 * Main Percy CLI function
280
 * @param args - Command line arguments array
281
 * @returns Promise that resolves when command completes
282
 */
283
function percy(args: string[]): Promise<void>;
284

285
/**
286
 * Check for CLI updates and display warnings if newer version available
287
 * @returns Promise that resolves when check completes
288
 */
289
function checkForUpdate(): Promise<void>;
290
```
291

292
### CLI Command Types
293

294
```typescript { .api }
295
// Command result types
296
interface CommandResult {
297
  success: boolean;
298
  exitCode: number;
299
  output?: string;
300
  error?: Error;
301
}
302

303
// Command options interfaces
304
interface ExecOptions {
305
  parallel?: boolean;
306
  partial?: boolean;
307
  testing?: boolean;
308
}
309

310
interface SnapshotOptions {
311
  baseUrl?: string;
312
  include?: string[];
313
  exclude?: string[];
314
  cleanUrls?: boolean;
315
  files?: string;
316
}
317

318
interface UploadOptions {
319
  files?: string[];
320
  ignore?: string[];
321
  stripExtensions?: boolean;
322
}
323

324
interface BuildWaitOptions {
325
  build?: string;
326
  project?: string;
327
  commit?: string;
328
  timeout?: number;
329
  interval?: number;
330
  failOnChanges?: boolean;
331
  passIfApproved?: boolean;
332
}
333

334
interface BuildReviewOptions {
335
  username?: string;
336
  accessKey?: string;
337
}
338
```
339

340
### Configuration Types
341

342
```typescript { .api }
343
interface PercyConfig {
344
  // Core configuration
345
  version?: number;
346
  snapshot?: SnapshotConfig;
347
  discovery?: DiscoveryConfig;
348
  agent?: AgentConfig;
349
  
350
  // Build configuration
351
  parallel?: {
352
    total?: number;
353
    nonce?: string;
354
  };
355
  
356
  // Upload configuration
357
  defer?: boolean;
358
  delayUploads?: boolean;
359
  deferUploads?: boolean;
360
  
361
  // Static configuration
362
  static?: StaticConfig;
363
  
364
  // Upload specific configuration
365
  upload?: UploadConfig;
366
}
367

368
interface SnapshotConfig {
369
  widths?: number[];
370
  minHeight?: number;
371
  percyCSS?: string;
372
  enableJavaScript?: boolean;
373
  enableLayout?: boolean;
374
  disableShadowDOM?: boolean;
375
  deviceScaleFactor?: number;
376
  scope?: string;
377
  ignoreRegions?: IgnoreRegion[];
378
  considerRegions?: ConsiderRegion[];
379
}
380

381
interface DiscoveryConfig {
382
  allowedHostnames?: string[];
383
  disallowedHostnames?: string[];
384
  networkIdleTimeout?: number;
385
  concurrency?: number;
386
  launchOptions?: LaunchOptions;
387
  userAgent?: string;
388
  deviceScaleFactor?: number;
389
}
390

391
interface AgentConfig {
392
  assetDiscovery?: {
393
    networkIdleTimeout?: number;
394
    pagePoolSizeMin?: number;
395
    pagePoolSizeMax?: number;
396
    allowedHostnames?: string[];
397
    disallowedHostnames?: string[];
398
    requestHeaders?: Record<string, string>;
399
    authorization?: {
400
      username: string; 
401
      password: string;
402
    };
403
  };
404
}
405

406
interface StaticConfig {
407
  baseUrl?: string;
408
  include?: string[];
409
  exclude?: string[];
410
  cleanUrls?: boolean;
411
  rewrites?: RewriteRule[];
412
}
413

414
interface UploadConfig {
415
  files?: string[];
416
  ignore?: string[];
417
  stripExtensions?: boolean;
418
  concurrency?: number;
419
}
420

421
interface LaunchOptions {
422
  headless?: boolean;
423
  args?: string[];
424
  timeout?: number;
425
  slowMo?: number;
426
  devtools?: boolean;
427
  executablePath?: string;
428
}
429

430
interface RewriteRule {
431
  source: string;
432
  destination: string;
433
}
434

435
interface IgnoreRegion {
436
  selector?: string;
437
  xpath?: string;
438
  coordinates?: {
439
    top: number;
440
    bottom: number;
441
    left: number;
442
    right: number;
443
  };
444
}
445

446
interface ConsiderRegion {
447
  selector?: string;
448
  xpath?: string;
449
  coordinates?: {
450
    top: number;
451
    bottom: number;
452
    left: number;
453
    right: number;
454
  };
455
}
456
```
457

458
### Build and Snapshot Types
459

460
```typescript { .api }
461
interface Build {
462
  id: string;
463
  number: number;
464
  url: string;
465
  webUrl: string;
466
  state: 'pending' | 'processing' | 'finished' | 'failed';
467
  reviewState?: 'unreviewed' | 'approved' | 'rejected';
468
  reviewStateReason?: string;
469
  isApproved?: boolean;
470
  totalComparisons: number;
471
  totalComparisonsFinished: number;
472
  totalComparisonsDiff: number;
473
  branch?: string;
474
  commitSha?: string;
475
  commitMessage?: string;
476
  pullRequestNumber?: string;
477
}
478

479
interface Snapshot {
480
  name: string;
481
  url?: string;
482
  domSnapshot?: string;
483
  clientInfo?: string;  
484
  environmentInfo?: string;
485
  widths?: number[];
486
  minHeight?: number;
487
  enableJavaScript?: boolean;
488
  percyCSS?: string;
489
  scope?: string;
490
  additionalSnapshots?: AdditionalSnapshot[];
491
  requestHeaders?: Record<string, string>;
492
  authorization?: {
493
    username: string;
494
    password: string;
495
  };
496
}
497

498
interface AdditionalSnapshot {
499
  prefix?: string;
500
  suffix?: string;
501
  name?: string;
502
  waitForTimeout?: number;
503
  waitForSelector?: string;
504
  execute?: string | Function;
505
  percyCSS?: string;
506
  ignoreRegions?: IgnoreRegion[];
507
  considerRegions?: ConsiderRegion[];
508
}
509
```
510

511
## Error Handling
512

513
Percy CLI provides structured error handling with specific exit codes and error types:
514

515
- **Exit Code 0**: Success
516
- **Exit Code 1**: General error (configuration, network, etc.)
517
- **Exit Code 2**: Build failed with visual differences (when using `--fail-on-changes`)
518

519
Common error scenarios include missing tokens, configuration validation failures, network connectivity issues, and build processing errors. The CLI provides detailed error messages and suggestions for resolution.