Libretto

How Libretto Works

• Libretto is a CLI for exploring live websites and building or debugging reusable browser automation scripts.
• Use Libretto commands to inspect the site and open pages, observe state, inspect requests, and prototype interactions.
• Libretto work must end in script changes. Create or edit the workflow file instead of stopping at interactive exploration.

Shipped Source & Documentation

Read references/shipped-source-and-documentation.md for shipped source details, published documentation links, and implementation context beyond what this skill file covers.

Default Integration Approach

1. Call the site's fetch/XHR endpoints via browser-context fetch().
2. If references/site-security-review.md (assess only once per site) rules fetch() unsafe, passively capture responses with page.on('response', ...)
3. Fall back to Playwright UI automation.

Mix strategies freely across steps on a site.

Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first navigation — deep URLs on a cold session are commonly blocked by edge bot protection.

Always declare that entry URL as workflow startUrl. Do not open the same URL again with page.goto at the top of the handler when Libretto launches the browser; Libretto loads startUrl before the handler runs (and before CDP attach on Kernel / cloud providers). run --cdp attaches without navigating, so leave the existing page as-is or navigate inside the handler.

CAPTCHA Handling

• If a CAPTCHA, Cloudflare challenge, or similar bot check appears in a local Chromium session, try to solve it in the visible browser and continue from the solved state.
• If the same challenge appears while the session is using a hosted browser provider, wait up to 2 minutes for automatic CAPTCHA handling before deciding the workflow is blocked.
• When a CAPTCHA was observed during exploration, generated workflow code should include an explicit timeout wait at that point with a short comment linking to the hosted platform stealth docs. Follow references/code-generation-rules.md for the code shape.

Setup

• Use the package manager convention for the target project. The examples use npx libretto; pnpm, yarn, and bun projects should use their equivalent package-manager execution form.
• Use npx libretto setup for first-time workspace onboarding. It installs Chromium and syncs skills.
• Use npx libretto status to inspect open sessions without triggering setup.
• Use npx libretto update to upgrade the project-local Libretto package. Use npx libretto update --dry-run to preview the package-manager command first.

Experiments

• Use npx libretto experiments to list internal feature flags and npx libretto experiments describe <name> for usage notes when an experiment is enabled.

Run Modes

There are three ways to run workflows:

• Local browser run: npx libretto run ./workflow.ts runs workflow code and local Chromium on the current machine. This is easy to watch and private, but most likely to hit CAPTCHAs or anti-bot checks.
• Hosted browser run: npx libretto run ./workflow.ts --provider libretto-cloud runs workflow code locally while the browser runs on provider infrastructure with stealth mechanisms. Use this for anti-bot/CAPTCHA issues, provider-specific behavior, and pre-deploy validation. If the user has not specified a provider, prefer libretto-cloud because it includes one free allocated browser-hour and does not require a third-party provider API key.
• Deployed workflow: Libretto Cloud packages the workflow as an API-backed workflow with the same remote-browser anti-bot mechanisms as hosted provider runs. Deploy only after the workflow passes with the target provider.

When editing a deployed workflow, validate changes with run --provider <deployment-provider> before redeploying; do not debug by repeatedly deploying and running the deployed job.

If the user prefers a provider for all local CLI runs in a workspace or only deploys workflows to that provider, update .libretto/config.json with provider instead of repeating --provider. Read references/configuration-file-reference.md first.

Working Rules

• Announce which session you are using and what page you are on.
• Ask instead of guessing when it is unclear what to click, type, or submit.
• Do not treat visibility as interactivity. If an element will not act, inspect blockers before retrying.
• Defer repo/code review until you begin generating code, unless the user explicitly asks for it earlier.
• Read and follow guidelines in references/code-generation-rules.md before generating or editing production workflow code. Every generated workflow must set startUrl to the first page the automation needs.
• For authenticated workflows, manual login is discovery only. After the user logs in, read only the sign-in action logs and identify the required credentials; if credentials are unclear, ask before writing code.
• Add missing blank LIBRETTO_CLOUD_<secret_name>= entries without overwriting populated values. If any required credential is blank, stop and ask the user to fill it; until then, do not inspect logged-in pages, read authenticated network bodies, write workflow code, open validation sessions, or continue discovery.
• Authenticated workflows must implement librettoAuthenticate with declared credentials before validation. Use a reusable *_totp_secret credential for authenticator-app MFA when the portal supports it (not a one-time otp_code). For SMS one-time codes, follow references/website-authentication.md.
• Read references/website-authentication.md when you need librettoAuthenticate examples, auth-profile details, or SMS OTP (claimSmsOtp).
• Validation requires a successful clean run on a fresh, unauthenticated session with confirmation of the actual returned output, not just process success. Use the same headed or headless mode that the workflow run is already using.
• After validation, always show the user: (1) the output/results from the validation run, and (2) the same command so they can re-run it themselves. Include any --params, --provider, --headed, or --headless flags the workflow needs. Do not add --auth-profile to run; workflow authProfile metadata controls profile use.
• Treat exploration sessions as disposable unless the user explicitly wants one kept open.
• Close disposable sessions before your final response once exploration, debugging, or validation is complete. Open browsers keep consuming local or hosted resources.
• Get explicit user confirmation before mutating actions or replaying network requests that may have side effects.
• Never run multiple exec commands at the same time.
• If the browser must remain read-only, switch to the libretto-readonly skill and use readonly-exec instead of exec.

Commands

open

• Open a page before using exec or snapshot.
• Use open at the start of script authoring when you need live page state to decide how the workflow should work.
• Use headed mode when the user needs to log in or watch the workflow.
• Pass --read-only when you want the session locked for inspection from the moment it is created.

npx libretto open https://example.com
npx libretto open https://example.com --provider libretto-cloud --session provider-debug
npx libretto open https://example.com --read-only --session readonly-example
npx libretto open https://example.com --session debug-example

connect

• Use connect to attach to any existing Chrome DevTools Protocol (CDP) endpoint — a browser started with --remote-debugging-port, an Electron app, or any other CDP-compatible target.
• After connecting, exec, snapshot, pages, and the rest of the session commands follow that session's stored mode.
• Libretto does not manage the connected process's lifecycle. close clears the session but does not terminate the remote process.
• Pass --read-only if the connected session must stay inspection-only from the start.

npx libretto connect http://127.0.0.1:9222 --session my-session
npx libretto connect http://127.0.0.1:9222 --read-only --session readonly-session
npx libretto connect http://127.0.0.1:9223 --session another-session

session-mode

• Use session-mode to inspect whether an existing session is write-access or read-only.
• Only a user can change the session mode for an existing session. Never change a session's mode on your own — the user must change it themselves manually.
• open, run, and connect default new sessions to write-access unless the config sets sessionMode to read-only.
• Pass --read-only or --write-access to override the config default for a single command.

npx libretto session-mode --session my-session

snapshot

• Use snapshot as the primary page observation tool.
• Run snapshot without --objective or --context; the command prints a screenshot path and compact accessibility tree for the current page.
• Run snapshot <ref> to inspect a subtree. Each call captures a fresh screenshot and accessibility tree, then scopes output to that ref. Use ref forms printed in the tree, such as l16; numeric-suffix aliases such as e16 also match l16.
• Use it before guessing at selectors, after workflow failures, and whenever the visible page state is unclear.

npx libretto snapshot --session debug-example
npx libretto snapshot <ref> --session debug-example
npx libretto snapshot --session debug-example --page <page-id>