@guanzhu.me/pw-cli 0.0.11 → 0.0.12

package/README.md

@@ -74,6 +74,52 @@ Run a local script:
 pw-cli run-script ./scrape.js --url https://example.com
 ```
 
+`run-script` is intended for multi-step automation. Your script can use:
+
+- Playwright globals: `page`, `context`, `browser`, `playwright`
+- Script args: `args`
+- CommonJS globals: `require`, `module`, `exports`, `__filename`, `__dirname`
+
+More complete example:
+
+```javascript
+// scripts/extract-links.js
+const fs = require('fs');
+
+const url = args[args.indexOf('--url') + 1] || 'https://example.com';
+const output = args[args.indexOf('--output') + 1] || 'links.json';
+
+await page.goto(url, { waitUntil: 'networkidle' });
+
+const links = await page.locator('a').evaluateAll(nodes =>
+  nodes
+    .map(a => ({
+      text: a.textContent.trim(),
+      href: a.href,
+    }))
+    .filter(item => item.href)
+);
+
+fs.writeFileSync(
+  output,
+  JSON.stringify(
+    {
+      url,
+      count: links.length,
+      links,
+    },
+    null,
+    2
+  )
+);
+
+return `saved ${links.length} links to ${output}`;
+```
+
+```bash
+pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
+```
+
 Reuse a page that was opened through `pw-cli open`:
 
 ```bash
@@ -108,7 +154,7 @@ pw-cli list
 - `open` injects headed and persistent defaults
 - Browser-backed commands can auto-open a browser session if needed
 - `run-code` accepts stdin and plain inline statements
-- `run-script` executes a local `.js` file with Playwright globals
+- `run-script` executes a local `.js` file with Playwright globals, CommonJS globals, and `args`
 - Common element commands accept XPath refs
 - `queue` lets you batch multiple commands and run them in order
 
@@ -235,7 +281,7 @@ console [min-level]         list console messages
 run-code <code>             run playwright code snippet
                             pw-cli: reads code from stdin when <code> is omitted
                             pw-cli: wraps plain statements in an async function
-run-script <file> [...]     run a local JavaScript file with page/context/browser globals
+run-script <file> [...]     run a local JavaScript file with Playwright globals and script args
 network                     list all network requests since loading the page
 tracing-start               start trace recording
 tracing-stop                stop trace recording
@@ -289,6 +335,7 @@ pw-cli open https://example.com
 pw-cli run-code "await page.goto('https://example.com'); return await page.title()"
 echo "return await page.url()" | pw-cli run-code
 pw-cli run-script ./scripts/smoke.js --env prod
+pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
 pw-cli click "//button[contains(., 'Submit')]"
 pw-cli queue add goto https://example.com
 pw-cli queue add snapshot

package/bin/pw-cli.js

@@ -229,7 +229,7 @@ DevTools:
   run-code <code>             run playwright code snippet
                               pw-cli: reads code from stdin when <code> is omitted
                               pw-cli: wraps plain statements in an async function
-  run-script <file> [...]     run a local JavaScript file with page/context/browser globals
+  run-script <file> [...]     run a local JavaScript file with Playwright globals and script args
   network                     list all network requests since loading the page
   tracing-start               start trace recording
   tracing-stop                stop trace recording
@@ -271,10 +271,23 @@ Examples:
   pw-cli run-code "await page.goto('https://example.com'); return await page.title()"
   echo "return await page.url()" | pw-cli run-code
   pw-cli run-script .\\scripts\\smoke.js --env prod
+  pw-cli run-script .\\scripts\\extract-links.js --url https://example.com --output links.json
   pw-cli click "//button[contains(., 'Submit')]"
   pw-cli queue add goto https://example.com
   pw-cli queue add snapshot
   pw-cli queue run
+
+run-script example:
+  // scripts/extract-links.js
+  const fs = require('fs');
+  const url = args[args.indexOf('--url') + 1] || 'https://example.com';
+  const output = args[args.indexOf('--output') + 1] || 'links.json';
+  await page.goto(url, { waitUntil: 'networkidle' });
+  const links = await page.locator('a').evaluateAll(nodes =>
+    nodes.map(a => ({ text: a.textContent.trim(), href: a.href })).filter(x => x.href)
+  );
+  fs.writeFileSync(output, JSON.stringify({ url, count: links.length, links }, null, 2));
+  return \`saved \${links.length} links to \${output}\`;
 `.trim() + '\n');
 }
 
@@ -631,7 +644,19 @@ async function handleRunScript(rawArgv) {
   const [scriptPath, ...scriptArgs] = positionals;
 
   if (!scriptPath) {
-    process.stderr.write('pw-cli: run-script requires a script path\n\nUsage: pw-cli run-script <file.js> [args...]\n');
+    process.stderr.write(`pw-cli: run-script requires a script path
+
+Usage:
+  pw-cli run-script <file.js> [args...]
+
+What the script receives:
+  - Playwright globals: page, context, browser, playwright
+  - Script args array: args
+  - CommonJS globals: require, module, exports, __filename, __dirname
+
+Example:
+  pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
+`);
     process.exit(1);
   }
   if (!fs.existsSync(path.resolve(scriptPath))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanzhu.me/pw-cli",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Persistent Playwright browser CLI with headed defaults, profile support, queueing, and script execution",
   "bin": {
     "pw-cli": "./bin/pw-cli.js"

package/src/cli.js

@@ -54,7 +54,18 @@ async function cmdRunCode(rest, opts) {
 async function cmdRunScript(rest, opts) {
   const [scriptPath, ...scriptArgs] = rest;
   if (!scriptPath) {
-    die('No script path provided.\n\nUsage: pw-cli run-script <file.js> [args...]');
+    die(`No script path provided.
+
+Usage:
+  pw-cli run-script <file.js> [args...]
+
+What the script receives:
+  - Playwright globals: page, context, browser, playwright
+  - Script args array: args
+  - CommonJS globals: require, module, exports, __filename, __dirname
+
+Example:
+  pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json`);
   }
 
   const conn = await getConnection(opts);
@@ -105,20 +116,34 @@ GLOBAL OPTIONS
 
 COMMANDS
   run-code [code]          Execute inline JS (reads stdin if omitted)
-  run-script <file> [...]  Execute a .js script with optional args
+  run-script <file> [...]  Execute a local .js file with Playwright globals and script args
   kill                     Stop the running browser
   status                   Show browser status
 
 SCRIPT GLOBALS
-  page, context, browser, playwright, args, require, __filename, __dirname
+  page, context, browser, playwright, args
+  require, module, exports, __filename, __dirname
 
 EXAMPLES
   pw-cli run-code "await page.goto('https://example.com'); console.log(await page.title())"
   echo "await page.screenshot({ path: 'out.png' })" | pw-cli run-code
   pw-cli run-script ./scrape.js --url https://example.com
+  pw-cli run-script ./scripts/extract-links.js --url https://example.com --output links.json
   pw-cli --headless run-code "await page.goto('https://example.com')"
   pw-cli --profile work status
   pw-cli kill
+
+RUN-SCRIPT EXAMPLE
+  // scripts/extract-links.js
+  const fs = require('fs');
+  const url = args[args.indexOf('--url') + 1] || 'https://example.com';
+  const output = args[args.indexOf('--output') + 1] || 'links.json';
+  await page.goto(url, { waitUntil: 'networkidle' });
+  const links = await page.locator('a').evaluateAll(nodes =>
+    nodes.map(a => ({ text: a.textContent.trim(), href: a.href })).filter(x => x.href)
+  );
+  fs.writeFileSync(output, JSON.stringify({ url, count: links.length, links }, null, 2));
+  return \`saved \${links.length} links to \${output}\`;
 `.trim());
 }