feat(help): add Examples section to every customer-facing command's --help

[anil-bd]

feat(help): add Examples section to every customer-facing command's --help

The gap

AWS CLI, gh, and Stripe CLI all ship an Examples: section in every command's --help output. Bright Data CLI does not. The user's first reflex on hitting an unfamiliar command is --help; seeing Usage: + Arguments: + Options: without an example forces them to alt-tab to the README. The README is 1,200 lines and does not surface examples discoverably either.

Specifically for Scraper Studio: when a YouTube creator records a demo (per the recent creator brief), the bdata scraper create --help moment is the first on-screen reference. Today they see the https://example.com/webhook default and no real invocation, then leave the terminal to find one. That's an off-camera cut at scene 1:30 of every shoot.

What this adds

An Examples: section to the six Scraper-Studio-adjacent commands:

Command	Examples added
scraper create	minimal Hacker News build, named + saved YC W26 build, custom delivery webhook
scraper run	single-URL async, sync mode for fast pages, save as CSV
discover	basic query, intent + cap, country localization with content
search	Google web search, news in a country, Bing images on mobile
pipelines	list types, single Amazon product, LinkedIn person profile saved as CSV
scrape	markdown default, JSON with metadata, geo-targeted mobile

All examples use real, public, scrape-friendly domains (Hacker News, Y Combinator, real SERP queries). No example.com. Bright Data house style C5.

Implementation

• New src/utils/help.ts with format_examples() + add_examples() so every command renders the section identically. The format is:

  Examples:
    # one-line description of what this does
    $ brightdata scraper create https://news.ycombinator.com "..."
  
    # another description
    $ brightdata scraper create ... --pretty -o create.json
  

• Six command files each gain three examples covering: minimal happy path, one useful variant, one production pattern.
• Attached via Commander's addHelpText('after', ...). This renders during outputHelp() (the --help path) without affecting helpInformation() or parse-time behavior. Zero impact on any non-help code path.

Tests

src/__tests__/utils/help.test.ts, 10 cases:

• format_examples() unit (3): empty input, single example, multiple with blank-line separator
• add_examples() integration (1): on a fresh Commander instance, renders correctly via outputHelp()
• Regression contract (6, one per command): every command in the list has an Examples: block, contains at least one $ brightdata line inside the block, and uses no example.com URL in the Examples block. If a future refactor drops Examples from any command, this fires.

The regression test renders help via configureOutput({writeOut}) + outputHelp() to capture the addHelpText output. helpInformation() alone does NOT include addHelpText content, so a naive test would silently pass.

Run:

npx vitest run src/__tests__/utils/help.test.ts
# Test Files  1 passed (1)
#      Tests  10 passed (10)

Full suite: 183 passed / 9 failed. The 9 failures (in scrape, browser, discover, add-mcp tests) all pre-exist on main and are unrelated to this change. Confirmed by running the suite on the stashed baseline.

Live verification

$ bdata scraper create --help | tail -12
  -k, --api-key <key>      Override API key
  -h, --help               display help for command

Examples:
  # Build a scraper for a public page (AI generation takes 5 to 10 minutes)
  $ brightdata scraper create https://news.ycombinator.com "Extract the top 30 stories: title, url, points, author, comment count."

  # Name the scraper and save the full AI output for inspection
  $ brightdata scraper create https://www.ycombinator.com/companies?batch=W26 "For each company card, extract name, vertical, tagline, link" --name yc-w26 --pretty -o create.json

  # Custom delivery webhook (default is a stub, set this when wiring to your own backend)
  $ brightdata scraper create https://news.ycombinator.com "Extract top stories" --deliver-webhook https://your-app.test/scraper-callback

Same shape on scraper run, discover, search, pipelines, scrape.

What this does NOT do

• Does not touch the misleading https://example.com/webhook default value on --deliver-webhook (that is issue N10, its own PR).
• Does not change Usage, Options, Arguments, or any command behavior.
• Does not change exit codes, output streams, or stdout/stderr routing.
• Does not add a dependency.

Refs

• Audit issue: N13 in scraper-studio-cli-demo/ISSUES.md
• bright-dx-writer critique: scraper-studio-cli-demo/CRITIQUE.md (DX content pattern C5, Examples-absent reference failure mode)
• Established baseline: AWS CLI aws s3 cp help, gh pr create --help, stripe customers create --help all ship Examples