# CLI Reference

| Key | Value |
|-----|-------|
| Status | Active |
| Owner | QA Automation |
| Updated | 2026-03-26 |
| Scope | Human-friendly command catalog grouped by job to be done |

This page is intentionally organized by use case instead of dumping a flat list of npm scripts. The repo has a large script surface. Most people do not need to memorize it. They need to know which family of commands solves the problem in front of them.

## Fast Start Commands

| If You Want To... | Command |
|-------------------|---------|
| run a quick health check | `npm run test:smoke` |
| run deploy-critical checks | `npm run test:pdt` |
| run full journeys | `npm run test:e2e` |
| run premium and auth flows | `npm run test:user-flows` |
| run mobile PR-safe checks | `npm run test:mobile:smoke` |
| run content validation | `npm run test:content` |
| run the visual suite | `npm run test:visual` |
| see recent failures from OpenSearch | `npm run os:failed` |
| generate the weekly report | `npm run report:weekly` |

## Test Suites

| Command | What It Is For |
|---------|----------------|
| `npm run test:smoke` | fast all-site health check |
| `npm run test:shadow` | continuous degradation monitoring |
| `npm run test:shadow:quick` | narrower shadow pass |
| `npm run test:pdt` | post-deploy verification |
| `npm run test:e2e` | full reader journeys |
| `npm run test:user-flows` | auth and premium flows |
| `npm run test:visual` | structural screenshot comparisons |
| `npm run test:visual:update` | refresh visual baselines intentionally |
| `npm run test:performance` | standard performance run |
| `npm run test:performance:baseline` | create or refresh performance baselines |
| `npm run test:performance:breaking` | breaking-news style performance checks |
| `npm run test:ads` | ad validation suite |
| `npm run test:ads:desktop` | desktop-only ads validation |
| `npm run test:ads:mobile` | mobile-only ads validation |
| `npm run test:events` | analytics event coverage |
| `npm run test:events:all-sites` | broader event run across sites |

## Mobile Commands

| Command | What It Is For |
|---------|----------------|
| `npm run test:mobile:smoke` | Chrome `@smoke` tier |
| `npm run test:mobile:regression` | Chrome `@regression` tier |
| `npm run test:mobile:deep` | Chrome `@deep` tier |
| `npm run test:mobile:safari:smoke` | Safari `@smoke` tier |
| `npm run test:mobile:safari:regression` | Safari `@regression` tier |
| `npm run test:mobile:safari:deep` | Safari `@deep` tier |
| `npm run test:mobile:all-devices:smoke` | Chrome and Safari smoke tier |
| `npm run test:mobile:all-devices:regression` | Chrome and Safari regression tier |
| `npm run test:mobile:all-devices:deep` | Chrome and Safari deep tier |
| `npm run test:mobile:matrix:smoke` | all-site Chrome smoke matrix |
| `npm run test:mobile:matrix:regression` | all-site Chrome regression matrix |
| `npm run test:mobile:matrix:deep` | all-site Chrome deep matrix |
| `npm run test:mobile:matrix:all-devices:smoke` | all-site all-device smoke matrix |
| `npm run test:mobile:matrix:all-devices:regression` | all-site all-device regression matrix |
| `npm run test:mobile:matrix:all-devices:deep` | all-site all-device deep matrix |

## Content And Coverage Commands

| Command | What It Is For |
|---------|----------------|
| `npm run test:content` | default content run |
| `npm run test:content:all` | full content pass |
| `npm run test:content:existence` | existence tier |
| `npm run test:content:interaction` | interaction tier |
| `npm run test:content:journey` | journey tier |
| `npm run test:content:smoke` | lightweight content validation |
| `npm run test:content:notify` | content notification workflow |
| `npm run coverage:map` | coverage matrix |
| `npm run coverage:map:save` | persist coverage report |
| `npm run coverage:html` | generate HTML coverage output |
| `npm run coverage:gaps` | show uncovered registry areas |
| `npm run coverage:check` | coverage validation |

## Healing And Failure Intelligence

| Command | What It Is For |
|---------|----------------|
| `npm run heal` | general healing analysis |
| `npm run heal:claude` | Claude-assisted healer flow |
| `npm run heal:interactive` | interactive healer |
| `npm run heal:ai` | AI-assisted healing path |
| `npm run heal:apply` | apply local fixes |
| `npm run heal:dry` | preview without changing files |
| `npm run heal:mr` | create MR workflow |
| `npm run heal:site` | site-targeted healing |
| `npm run incidents:query` | query failure clusters needing classification |
| `npm run incidents:template` | generate incident JSON template |
| `npm run incidents:record-recovery` | append confirmed recovery history |
| `npm run fix:stats` | fix database summary |
| `npm run fix:recent` | recent fix history |
| `npm run fix:export` | export fix data |
| `npm run os:failed` | recent failures from OpenSearch |
| `npm run os:logs` | query recent logs |
| `npm run os:stats` | OpenSearch stats |

## Slack And Reporting Commands

| Command | What It Is For |
|---------|----------------|
| `npm run notify:slack:success` | post success summary |
| `npm run notify:slack:failure` | post humanized failure summary |
| `npm run notify:slack:visual` | post visual-suite result summary |
| `npm run report:weekly` | weekly report |
| `npm run report:monthly` | monthly report |
| `npm run report:legacy` | legacy report path |
| `npm run report:legacy:weekly` | legacy weekly report |
| `npm run report:legacy:monthly` | legacy monthly report |
| `npm run report:merge` | merge report data |
| `npm run slack:reply-resolved` | preview recovery replies |
| `npm run slack:reply-resolved:send` | send recovery replies |
| `npm run slack:reply-thread` | post to a specific Slack thread |
| `npm run slackbot` | Slackbot helper API |

## Monitoring Commands

| Command | What It Is For |
|---------|----------------|
| `npm run monitor:consent` | consent dialog monitor |
| `npm run monitor:selectors` | selector health monitor |
| `npm run monitor:robots-txt` | robots.txt and sitemap health |
| `npm run monitor:urls` | URL monitor entry point |
| `npm run monitor:urls:crawl` | basic crawl |
| `npm run monitor:urls:crawl:nav` | crawl following nav links |
| `npm run monitor:urls:crawl:deep` | deeper crawl variant |
| `npm run monitor:urls:crawl:full` | fullest crawl mode |
| `npm run monitor:urls:broken` | broken link report |
| `npm run monitor:urls:slack` | send broken-link Slack summary |
| `npm run monitor:urls:slack:weekly` | weekly URL monitor summary |
| `npm run monitor:grafana` | browser-based Grafana visual checks |
| `npm run monitor:grafana:slack` | Grafana visual checks with Slack output |

## Observability And Dashboard Commands

| Command | What It Is For |
|---------|----------------|
| `npm run grafana:generate` | generate dashboard JSON from code |
| `npm run grafana:deploy` | deploy dashboards |
| `npm run grafana:deploy:dry` | dry-run dashboard deploy |
| `npm run grafana:validate` | validate dashboard definitions |
| `npm run grafana:validate-data` | validate dashboard queries against live data |
| `npm run grafana:pipeline` | CI-oriented Grafana workflow |
| `npm run observability:verify` | combined health and quality check |
| `npm run observability:verify:health` | blocking health checks |
| `npm run observability:verify:quality` | data quality checks |
| `npm run opensearch:setup` | OpenSearch setup path |
| `npm run opensearch:setup:dry` | dry-run OpenSearch setup |
| `npm run os:setup-retention` | retention setup |

## Discovery, Crawling, And Data Commands

| Command | What It Is For |
|---------|----------------|
| `npm run crawl` | crawl all sites |
| `npm run crawl:site` | crawl one site |
| `npm run crawl:consent` | crawl with consent focus |
| `npm run discover` | selector discovery entry point |
| `npm run discover:all` | full selector discovery |
| `npm run discover:mobile` | mobile selector discovery |
| `npm run discover:site` | site-targeted discovery |
| `npm run data:compare` | compare data outputs |
| `npm run data:sync` | sync data assets |
| `npm run data:weekly` | weekly data summary |

## Visual Fact-Checker Commands

| Command | What It Is For |
|---------|----------------|
| `npm run factcheck` | standard fact-check run |
| `npm run factcheck:dry` | screenshot-only dry run |
| `npm run factcheck:smoke` | fact-check smoke results |
| `npm run factcheck:pdt` | fact-check PDT results |
| `npm run factcheck:failures` | focus on failures |
| `npm run factcheck:mobile` | mobile fact-check |
| `npm run factcheck:slack` | post fact-check output to Slack |
| `npm run factcheck:ci` | CI-oriented fact-check path |
| `npm run factcheck:dashboard` | local dashboard for fact-check output |
| `npm run deploy:verify` | PDT plus fact-check verification |
| `npm run deploy:verify:full` | broader deployment verification |

## Confluence And Documentation Commands

| Command | What It Is For |
|---------|----------------|
| `npm run confluence:sync` | doc publishing workflow entry point |

For manual publishing, the `.confluence/` scripts remain the source of truth.

## Useful Debug Commands

| Command | What It Is For |
|---------|----------------|
| `npm run test:debug` | Playwright debug mode |
| `npm run test:headed` | headed browser run |
| `npm run test:trace` | trace-friendly run |
| `npm run test:ui` | Playwright UI mode |
| `npm run test` | default npm test entry |
| `npm run test:site` | site-targeted default suite entry |
| `npm run test:all` | broad test entry point |

## How To Read This Page

If you are here because of a specific task, use this map:

| Task | Best Section |
|------|--------------|
| run a suite | Test Suites |
| diagnose or heal failures | Healing And Failure Intelligence |
| send or debug alerts | Slack And Reporting |
| inspect background monitors | Monitoring Commands |
| work on dashboards or OpenSearch | Observability And Dashboard Commands |
| work on content coverage | Content And Coverage Commands |
| work on AI screenshot review | Visual Fact-Checker Commands |