canary-automate

Canary automate (one-off)

Run a script against a real browser and return the result — ephemeral, nothing recorded. Use the canary-scripting skill for the API.

When to use

• A quick, one-shot browser task: navigate, extract, fill, screenshot.
• Scraping or checking a page where you don't need a trace / video / report.
• For a recorded, verifiable run with a report, use canary-session instead.

Examples

Example 1: scrape

User says: "get the top 10 Hacker News titles" or "scrape the headlines" Write a script that opens the page and evaluates the data, run it, return the JSON it logs.

Example 2: check

User says: "is the pricing page up and what's the headline?" or "screenshot the homepage" goto, read the element (or screenshot), report.

Workflow

1. If the runtime isn't installed: npx @usecanary/cli install (one-time; downloads Chromium).
2. Write a short, focused script with the canary-scripting API (browser.getPage, page.goto, locator/evaluate, console.log the result), observing first on unknown pages (see Hard rules).
3. Run it: npx @usecanary/browser run ./script.js (or pipe the script via stdin).
4. If the result is empty or a selector missed, observe and retry: run a second short script that logs page.url(), page.title(), and (await page.snapshotForAI()).full (or a targeted locator(...).count()), pick a better selector, re-run. Named pages persist between runs, so state carries over.
5. Report the script's stdout. On optional extractions, degrade gracefully (log a WARN, don't crash) — but don't paper over a miss you can fix by observing.
6. Cleanup (optional): the run leaves a shared background daemon up for reuse. To shut it (and any browser) down, run npx @usecanary/browser stop (alias of canary stop / canary daemon stop).

Hard rules

• Unknown page? Snapshot first, then act: read (await page.snapshotForAI()).full to see what is there, pick a semantic selector from it (getByRole, getByText), then interact. Never guess selectors blind.
• Known page or selectors? Skip the snapshot and use direct selectors — faster and more reliable.