Natural-language web automation using Puppeteer.

Node CI Travis CI Coverage Dependencies License Vulnerabilities Based on Node.ts npm type definitions npm package npm downloads Contributors semantic-release


⭐️ How it works

Write in natural language (following the Commands section). For example, you can create a file with the following set of commands:


Go to
Click on the login link
Type username
Type password 3rjiw9qie2308
Click on login button
Take a screenshot
Save to to report.csv

Then, run the command:

puppet “path/to/download.puppet”

💡 Usage


Install the package globally from npm:

npm install —global puppet
# Local Puppet file
puppet “path/to/commands.puppet”

# Remote Puppet file

# Commands directly in CLI
puppet “open” “get page HTML” “save as page.html”


Import and use the API:

const { puppet } = require(“puppet”); // Node.js
import { puppet } from “puppet”; // TypeScript/ES6

// Local Puppet file
await puppet(“path/to/commands.puppet”);

// Remote Puppet file
await puppet(“”);

// Commands directly as an array of strings
await puppet([“open”, “get page HTML”, “save as page.html”]);

🔫 Commands


  • Go to
  • Navigate to URL
  • Go to the page on
  • Open


  • Wait for 10 seconds
  • Wait for 2 minutes
  • Wait for 100ms
  • Wait for navigation


  • Take a screenshot of this page
  • Take a JPEG screenshot
  • Full screenshot this page
  • Make a transparent screenshot
  • Screenshot and omit the background

Export page to PDF/HTML

  • Save this page as PDF
  • Save page HTML
  • Get the HTML
  • Save the whole page as PDF

Save to file

  • Save result to path/to/file
  • Save this screenshot to path/to/file
  • Save this to the file path/to/file

Mouse events

  • Click on point [123, 456]
  • Right click on coordinates 123, 456
  • Move mouse cursor to points 123, 456
  • Click on 123, 456 using middle mouse button

👩‍💻 Development

Build TypeScript:

npm run build

Run unit tests and view coverage:

npm run test-without-reporting

Related work

  • Puppeteer is the headless Chrome API for Node.js
  • Archiver is the Internet Archive saver I made using Puppeteer
  • TagUI is a CLI for digital process automation (RPA)

✨ Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

📄 License