# Libretto
> Toolkit for building, debugging, and maintaining browser automations.
This file contains the full content of all documentation pages. For a compact index, see [llms.txt](https://libretto-docs.vercel.app/docs/llms.txt). To download all pages as a zip, use [docs.zip](https://libretto-docs.vercel.app/docs/docs.zip).
---
title: Quickstart
url: "https://libretto-docs.vercel.app/docs/get-started/quickstart.md"
description: Install Libretto into the Node.js package that contains your browser automations. Run Libretto commands with npx libretto from that package. If you are...
---
> Install Libretto and run your first workflow end to end.
## Agent prompt
> Fetch and follow [https://libretto.sh/start.md](https://libretto.sh/start.md) to set up Libretto and create a new browser automation.
## Manual
Install Libretto into the Node.js package that contains your browser automations. Run Libretto commands with `npx libretto` from that package.
Decide whether you want to create a new Libretto package or add Libretto to an existing Node.js package.
If you create a new package, choose where it should live and what it should be named. If you use an existing package, switch into that package directory before installing Libretto.
From the directory where the new package should be created:
```bash theme={null}
npm create libretto@latest
```
You can pass a package name directly:
```bash theme={null}
npm create libretto@latest my-automations
```
This scaffolds a package, installs dependencies, runs setup, and downloads Chromium.
From the existing package directory, add Libretto as a dependency and run setup:
```bash theme={null}
npm install libretto zod
npx libretto setup
```
Then create a workflow file and run it with `npx libretto run --headless`.
Create `src/workflows/scrape-page.ts` in the package you set up:
```ts src/workflows/scrape-page.ts
import { workflow } from "libretto";
import { z } from "zod";
export default workflow(
"scrape-page",
{
input: z.object({}),
output: z.object({
title: z.string(),
}),
startUrl: "https://example.com",
},
async ({ page }) => {
const title = await page.title();
console.log(`Page title: ${title}`);
return { title };
},
);
```
Run it headless:
```bash theme={null}
npx libretto run src/workflows/scrape-page.ts --headless
```
This confirms your local setup works and shows the basic run loop.
Expand the smoke workflow into a minimal real workflow you can iterate on.
## Compare browser automation tools
If you are choosing between Libretto and another browser automation tool, these comparisons explain the production trade-offs:
Compare deterministic scripts with a runtime browser agent.
Compare generated workflows with act(), observe(), and runtime inference.
Compare browser recording with agent-built workflows and validation loops.
---
title: First workflow
url: "https://libretto-docs.vercel.app/docs/get-started/first-workflow.md"
---
> Author a minimal workflow, run it, and inspect the result.
## Agent prompt
> Ask me what website and workflow I want to demonstrate. If I’m not sure, give me a few examples of simple workflows I could do. Then open a Libretto browser session for the site I choose. After I finish, create a Libretto workflow.
## Manual
Create `src/workflows/scrape-page.ts`:
```ts src/workflows/scrape-page.ts
import { workflow } from "libretto";
import { z } from "zod";
export default workflow(
"scrape-page",
{
input: z.object({}),
output: z.object({
title: z.string(),
}),
startUrl: "https://example.com",
},
async ({ page }) => {
const title = await page.title();
console.log(`Page title: ${title}`);
return { title };
},
);
```
```bash theme={null}
npx libretto run src/workflows/scrape-page.ts
```
The object you `return` is the workflow output. On a hosted run, that output is `result` on the job. See [Get the workflow output](/libretto-cloud-api/jobs-and-logs#get-the-workflow-output).
When a step fails or behaves unexpectedly, open a named debug session first:
```bash theme={null}
npx libretto open https://example.com --session debug-example
```
Then inspect and prototype with the same session:
```bash theme={null}
npx libretto snapshot --session debug-example
npx libretto exec --session debug-example "await page.url()"
```
When the prototype works, move the logic back into the workflow file and run again.
Choose where to run workflows in production: Libretto Cloud Hosting or an alternative provider.
---
title: Deploying
url: "https://libretto-docs.vercel.app/docs/get-started/deploying.md"
description: "Libretto has two production paths: Start here if you want the shortest path from local workflow to hosted runs. Use this if you want a provider other than..."
---
> Pick a production path and deploy.
## Agent prompt
> Help me deploy my Libretto workflow and choose the right production path.
>
> First, ask me one question: do I want managed hosting (Libretto Cloud Hosting) or an alternative provider?
>
> Then:
>
> * If I choose managed hosting, follow the Libretto Cloud Hosting docs to authenticate, deploy, and run a hosted workflow.
> * If I choose an alternative provider, use the alternative providers docs and ask whether I want Kernel, Browserbase, Steel, AWS, or GCP, then guide me through that path.
>
> After setup, provide:
>
> 1. commands executed
> 2. files/config edited
> 3. deployment/run status
> 4. next recommended docs page
>
> Do not make unrelated changes.
## Manual
Libretto has two production paths:
* **Libretto Cloud Hosting**: managed infrastructure, fastest path to production.
* **Alternative providers**: run the browser on Kernel, Browserbase, or Steel, or self-host the workflow runtime on AWS or GCP.
## Option A: Libretto Cloud Hosting (managed)
Start here if you want the shortest path from local workflow to hosted runs.
* [Cloud overview](/libretto-cloud-hosting/overview)
* [Cloud authentication](/libretto-cloud-hosting/authentication)
* [Cloud deployments](/libretto-cloud-hosting/deployments)
## Option B: Alternative providers
Use this if you want a provider other than Libretto Cloud Hosting.
* [Alternative providers overview](/alternative-providers/overview)
* [Kernel](/alternative-providers/kernel)
* [Browserbase](/alternative-providers/browserbase)
* [Steel](/alternative-providers/steel)
* [Deploy on GCP](/alternative-providers/gcp)
* [Deploy on AWS](/alternative-providers/aws)
## After deployment
To read the object a hosted workflow returned, poll `jobs/get` and use `result`. See [Get the workflow output](/libretto-cloud-api/jobs-and-logs#get-the-workflow-output).
Use these workflow guides to build, debug, and optimize production automations:
Give your agent a goal and a URL, then review the generated browser automation.
Demonstrate a workflow manually and let your agent turn the recorded steps into code.
Reproduce failures, inspect live page state, and fix broken automations.
Replace UI automation with direct API calls when a site exposes usable network traffic.
Other references:
* Conceptual model: [Understand Libretto](/understand-libretto/core-concepts)
* Command details: [CLI reference](/reference/cli/open-and-connect)
* Runtime API details: [Library API](/reference/runtime/workflow)
---
title: One-shot workflow generation
url: "https://libretto-docs.vercel.app/docs/guides/one-shot-workflow-generation.md"
description: "One-shot generation is the fastest way to go from an idea to a working automation. You describe what you want in a single prompt, and your coding agent opens a..."
---
> Give your agent a goal and a URL, and get back a complete browser automation script.
One-shot generation is the fastest way to go from an idea to a working automation. You describe what you want in a single prompt, and your coding agent opens a browser, explores the site, and writes a complete workflow file.
### Steps
Describe the **site**, the **data or action** you want, and the **input/output shape** you want the workflow to expose as Zod schemas. The more specific you are, the better your results.
```text Example prompt
Use the Libretto skill. Go on https://sfbay.craigslist.org and scrape the first 10 "free stuff" listings for title, location, and link.
```
Include "Use the Libretto skill" so your agent uses Libretto's CLI tools instead of writing a Playwright script from scratch.
The agent opens a browser window on your screen. If the site requires authentication, the agent will ask you to log in manually. Do that, then tell the agent you're done.
```bash theme={null}
# What the agent runs behind the scenes
npx libretto open https://sfbay.craigslist.org --headless --session one-shot-flow
```
If the site needs login, make sure your prompt doesn't say `--headless`. You can mention "I need to log in first" in your prompt to be explicit.
The agent takes snapshots and tests selectors against the live DOM. You'll see it running commands like `npx libretto snapshot` and `npx libretto exec` in your terminal.
You don't need to do anything during this phase, but you can redirect the agent if it seems stuck:
> The listings are in the main content area, not the sidebar.
The agent writes a TypeScript file that exports a `workflow()`. Here's roughly what to expect:
```typescript theme={null}
import { workflow } from "libretto";
import { z } from "zod";
const outputSchema = z.object({
listings: z.array(z.object({
title: z.string(),
location: z.string(),
link: z.string().url(),
})),
});
export default workflow(
"freeStuff",
{
input: z.object({}),
output: outputSchema,
startUrl: "https://sfbay.craigslist.org/search/zip",
},
async (ctx) => {
const { page } = ctx;
await page.waitForSelector(".result-row");
const rows = await page.locator(".result-row").all();
const listings = [];
for (const row of rows.slice(0, 10)) {
const title = await row.locator(".result-title").textContent();
const link = await row.locator("a").getAttribute("href");
// ... extract location
}
return { listings };
},
);
```
Things to check:
* **`startUrl`** is set to the workflow's entry page
* **Input/output schemas** match what you asked for
* **Selectors** look reasonable (class names, data attributes, or ARIA roles, not brittle positional selectors)
* **Pagination** logic is present if you asked for more items than fit on one page
The agent runs the workflow headless and shows you the output. Check that the returned data looks right.
```bash theme={null}
# What the agent runs
npx libretto run ./free-stuff.ts --headless
```
If the output is wrong, tell the agent what's off:
> The location is always empty. It looks like it's reading the wrong element.
The agent will re-inspect the page and fix the issue.
### When to use this approach
* You're automating a site for the first time and don't know its structure
* The task is self-contained and clearly scoped ("get the first 10 listings")
* You want a working script with minimal back-and-forth
* You don't need to demonstrate the workflow manually first
### Tips
After you log in, tell the agent to save the session with `npx libretto save`.
Future runs can restore your login state so you don't have to authenticate
every time.
Make sure your coding agent has the Libretto skill installed before starting.
Run `npm create libretto@latest` or `npx libretto setup` in your project root
if you haven't already.
### Related guides
Show the agent your workflow manually and let it turn your actions into code.
Speed up an existing browser script by switching to direct API calls.
---
title: Interactive workflow building
url: "https://libretto-docs.vercel.app/docs/guides/interactive-workflow-building.md"
description: "Some workflows are too complex to describe in words alone, especially in healthcare software and legacy web apps where the interaction sequence matters and the..."
---
> Record your actions in the browser and let your agent turn them into automation code.
Some workflows are too complex to describe in words alone, especially in healthcare software and legacy web apps where the interaction sequence matters and the UI has unusual patterns. Interactive script building lets you perform the workflow yourself while Libretto records every click, fill, and navigation. Your agent then reads the action log and translates what you did into a reusable automation script.
This approach combines your knowledge of the application (you drive the browser and show the agent the workflow) with the agent's ability to figure out the right selectors and write reliable Playwright code.
### Steps
Describe the **site**, the **workflow** you're going to demonstrate, and the **input/output shape** you want. Mention that you'll show the steps manually.
```text Example prompt
Use the Libretto skill. I'm going to show you a workflow in eClinicalWorks to look up a patient's primary insurance ID. Turn it into a script that takes patient name and DOB as input and returns the insurance ID. URL is https://your-ehr.example.com
```
Include "Use the Libretto skill" so your coding agent uses Libretto's CLI tools instead of writing a Playwright script from scratch.
The agent opens a headed browser window on your screen. If the site requires login, do that first. Then walk through the workflow exactly as you normally would: search for a patient, open their record, navigate to the insurance tab, whatever the task requires.
Libretto records every click, form fill, and navigation in the background. You don't need to do anything special, just use the app normally.
When you're done, tell the agent what you did and where the result ended up:
> I'm done. I searched by patient name, opened their chart, and clicked the Insurance tab. The primary insurance ID is visible in the Patient Info section on screen.
Call out anything non-obvious about what you did:
> I clicked the second search result because the first row is always a header. Also, the insurance tab sometimes takes a few seconds to load.
Take your time. The recording captures everything, so there's no penalty for pausing to think or scrolling around. If you make a mistake, just undo it naturally. The agent can filter out dead ends.
The agent reads the action log that Libretto recorded: every click, fill, and navigation along with the selectors and page context for each one. You'll see it run commands like:
```bash theme={null}
tail -n 20 .libretto/sessions/interactive-flow/actions.jsonl | jq .
```
It uses this log as a blueprint to write a TypeScript workflow file that replicates your steps programmatically. The agent may also snapshot the page or test selectors against the live DOM to make sure everything works.
If the agent asks clarifying questions about what you did, answer them. Usually the action log plus your summary is enough.
The agent writes a TypeScript file that exports a `workflow()`. Things to check:
* **`startUrl`** is set to the workflow's entry page
* **Input/output schemas** match what you asked for
* **Selectors** look reasonable (class names, data attributes, or ARIA roles, not brittle positional selectors)
* **Parameterization**: values you typed during the demo should be replaced with input parameters, not hardcoded
* **Wait logic**: if you mentioned something takes time to load, make sure there's a `waitForSelector` or similar
If something's off, tell the agent:
> The patient name is hardcoded. It should come from the input parameter. Also, the insurance tab selector looks fragile, can you use the tab's text instead?
The agent runs the workflow headless with test parameters and shows you the output. Check that the returned data looks right.
```bash theme={null}
# What the agent runs
npx libretto run ./get-insurance-id.ts --headless \
--params '{"patientName": "Jane Smith", "dob": "1985-04-12"}'
```
If the output is wrong, tell the agent what's off:
> It returned an empty string for the insurance ID. I think the tab content hadn't loaded yet when it tried to read the value.
The agent will re-inspect the page and fix the issue.
### When to use this approach
* The workflow involves many steps and is hard to describe concisely
* You're working with EHR, healthcare, or legacy enterprise software with unusual UI patterns
* The workflow involves conditional paths that are easier to show than explain
### Tips
After you log in, tell the agent to save the session with `npx libretto save`.
Future runs can restore your login state so you don't have to authenticate
every time.
### Related guides
Let the agent explore a site and build the workflow without your involvement.
Reproduce failures, inspect live page state, and fix broken automations.
---
title: Debugging workflows
url: "https://libretto-docs.vercel.app/docs/guides/debugging-workflows.md"
description: "There are two common debugging scenarios: connecting to a remote browser session that's already open (e.g. a production run that failed), and reproducing a..."
---
> Reproduce failures, inspect live page state, and fix broken browser automations.
There are two common debugging scenarios: connecting to a remote browser session that's already open (e.g. a production run that failed), and reproducing a failure locally from error logs.
### Remote debugging (connect to an open session)
When a workflow fails in production or a remote environment, the browser often stays open at the point of failure. You can connect to it directly with Libretto and debug the live page state.
Get the CDP (Chrome DevTools Protocol) endpoint URL from your deployment logs. Then connect:
```bash theme={null}
npx libretto connect --session remote-debug
```
Tell the agent what went wrong and point it at the open session.
```text Example prompt
Use the Libretto skill. I have a remote browser session open at --session remote-debug. The eligibility check workflow failed with a broken selector error. Inspect the current page state and figure out what changed.
```
The agent can snapshot the page, test selectors, and execute code against the live browser without restarting the workflow.
The agent patches the workflow file based on what it found in the live page. Check the diff and verify the fix addresses the root cause.
### Local debugging (reproduce from error logs)
When you have error output from a failed run (stack traces, log files, GCP logs, etc.), you can have your agent reproduce and fix the issue locally.
Describe the **script**, what it's **supposed to do**, and what's **going wrong**. Include the error output.
```text Example prompt
Use the Libretto skill. The workflow at ./integration.ts is supposed to go to Availity and perform an eligibility check for a patient. But I'm getting a broken selector error. Fix it.
```
Paste the error or stack trace directly into your prompt.
The agent runs the script in headed mode so you can see the browser. It stops at the failure point with the browser still open.
```bash theme={null}
# What the agent runs
npx libretto run ./integration.ts --session debug-flow --headed
```
If you notice something useful (a popup that wasn't there before, a redesigned page), mention it to save the agent time.
The agent snapshots the broken page state, identifies what's wrong, and tests new selectors against the live DOM. You'll see it running `npx libretto snapshot` and `npx libretto exec` commands while the browser stays open.
If you have context that would help, share it:
> They redesigned the eligibility form last week. The submit button used to be in a sidebar but now it's inline.
The agent patches the workflow file. Check the diff:
* Is the new selector reasonable? (`data-testid`, ARIA role, or visible text are more stable than class names)
* Did it address the **root cause** or just the immediate symptom?
* If the site changed its markup, are there other selectors in the file that might have the same problem?
The agent re-runs the workflow headless to confirm the fix works.
```bash theme={null}
npx libretto run ./integration.ts --headless
```
If it fails again, the browser stays open and the agent repeats the diagnose/fix cycle.
### Using `pause()` as a breakpoint
If you need the workflow to stop at a specific point (not at failure, but at a known state you want to inspect), ask the agent to add a `pause()` call:
```typescript theme={null}
import { workflow, pause } from "libretto";
import { z } from "zod";
export default workflow(
"eligibilityCheck",
{
input: z.object({
memberId: z.string(),
}),
output: z.void(),
},
async (ctx, input) => {
const { session, page } = ctx;
await page.goto("https://availity.com");
await page.locator("#memberSearch").fill(input.memberId);
// Pause here to inspect the page before submitting
await pause(session);
await page.locator("button[type='submit']").click();
// ...
},
);
```
The workflow halts at the `pause()` with the browser open. The agent can also drive this autonomously by adding `pause()` calls where it wants to inspect, running the workflow, and calling `npx libretto resume --session ` to continue when it's ready. `pause()` is a no-op when `NODE_ENV === "production"`, so it's safe to leave in during development.
### Common errors
**Broken selectors:** the most common failure. A selector that worked last week no longer matches because the site updated its markup. Tell the agent what changed if you know, or just let it snapshot and figure it out.
**Popups blocking the workflow:** a modal, cookie banner, or session-expiry dialog appears unexpectedly. Tell the agent about the popup and ask it to add recovery logic using `attemptWithRecovery()` so future runs handle it automatically.
**Timeout errors:** a `waitForSelector` or locator action times out because the expected element never appeared. The page might show a loading spinner, an error state, or a redirect. The agent can snapshot to see what actually rendered.
### Tips
Paste your error message into the prompt. Agents do a better job debugging
when they have the stack trace.
### Related guides
Build a new automation from scratch without any prior knowledge of the site.
Show the workflow manually and let your agent turn it into reusable code.
---
title: Convert to network requests
url: "https://libretto-docs.vercel.app/docs/guides/convert-to-network-requests.md"
description: "Browser automation is reliable, but it's not always the fastest approach. When a site's internal API is accessible from within the browser context, calling..."
---
> Convert browser automations to direct API calls for speed and reliability.
Browser automation is reliable, but it's not always the fastest approach. When a site's internal API is accessible from within the browser context, calling those endpoints directly is faster and less fragile than driving the UI. No selectors to maintain, no page rendering to wait for, and no DOM changes to break your script.
Libretto captures all network traffic during a browser session, so your agent can inspect exactly which API calls the site makes and convert a UI-based workflow to direct requests.
Not every site is a good candidate for network conversion. Stay with browser automation if:
* The site has enterprise bot protection (Akamai, PerimeterX, Shape Security) **and** monkey-patches `window.fetch` with call-stack inspection
* The request you want to make is normally loaded as a document, script, image, stylesheet, or iframe rather than fetch/XHR
* The site does API-level monitoring that correlates request timing to UI interactions
* The data you need is rendered client-side and doesn't come from a clean API response
In these cases, stick with your existing Playwright automation or use passive interception (`page.on('response', ...)`) to capture API data without making extra requests.
### Steps
Point the agent at the **existing workflow file** and ask it to convert to network requests.
```text Example prompt
Use the Libretto skill. We have a browser script at ./integration.ts that automates going to Hacker News and getting the first 10 posts. Convert it to direct network requests instead.
```
Include "Use the Libretto skill" so your agent uses Libretto's network capture tools instead of guessing at API endpoints.
The agent runs the existing script to capture all network requests and responses, then examines the log to find API endpoints that return the data you need.
```bash theme={null}
# What the agent runs
npx libretto run ./integration.ts
jq . .libretto/sessions/conversion-flow/network.jsonl
```
If the site requires login, the agent opens a headed browser and you'll log in as usual. Otherwise you don't need to do anything during this phase.
The agent reports what API endpoints it found and whether the site has bot protection. It recommends one of two approaches:
* **In-browser fetch**: call endpoints directly from within the browser's JavaScript context. The requests share the browser's cookies and TLS fingerprint, but they still look like fetch/XHR requests. Use this when the real site also calls that endpoint with fetch or XHR.
* **Passive interception**: set up a `page.on('response', ...)` listener and let the site's own code make the requests. Zero detection risk because no extra requests are made, but you're limited to whatever requests the site naturally triggers. Safer, but less flexible. Use this when the site has bot protection.
If the agent's recommendation looks reasonable, let it proceed. If you'd rather use one approach over the other, say so:
> Use passive interception, I don't want to risk triggering their bot detection.
The agent rewrites the workflow to use network requests instead of DOM extraction. Things to check:
* **Endpoints:** are the URLs and HTTP methods correct?
* **Auth/cookies:** does the new version handle authentication the same way as the original?
* **Output shape:** the return type should be identical to the browser-based version
* **Error handling:** API calls should check response status codes and handle failures gracefully
* **Pagination:** if the original script paginated through UI, the new version should paginate through the API
If something's off:
> The original script also grabbed the comment count, but the new version doesn't fetch that field from the API.
The agent runs the rewritten workflow headless and shows you the output. Compare it to what the browser-based version returned. The data should match.
```bash theme={null}
# What the agent runs
npx libretto run ./integration.ts --headless
```
If the output is wrong or incomplete, tell the agent what's off:
> The scores are all null. It looks like the API response has a different field name for that.
### When to convert to network requests
* The site exposes a usable JSON API behind the UI
* The target requests are normally made with fetch/XHR by the site itself
* You need to paginate deeply (fetching page 50 without clicking "next" 49 times)
* You want data the UI doesn't display (hidden fields, metadata, IDs)
* Speed and reliability matter more than DOM fidelity
### Related guides
Start from scratch. Give your agent a goal and let it build the workflow.
Reproduce failures and fix broken automations interactively.
---
title: Core concepts
url: "https://libretto-docs.vercel.app/docs/understand-libretto/core-concepts.md"
description: "Libretto ships two interfaces: All Libretto state lives in a .libretto/ directory at your project root: config.json: Workspace settings such as viewport,..."
---
> How Libretto organizes browsers, sessions, and state.
### CLI vs Library API
Libretto ships two interfaces:
* **CLI** (`npx libretto `): the primary interface for both agents and humans. Commands open browsers, take snapshots, execute Playwright code, run workflow files, and manage sessions. Every command accepts `--session ` to target a specific browser session.
* **Library API** (`import { workflow } from "libretto"`): used inside workflow files you run with `npx libretto run`. The `workflow()` function wraps your automation handler, validates input with a Zod schema, and gives the handler typed access to `page`, `session`, and parsed input.
### The `.libretto/` directory
All Libretto state lives in a `.libretto/` directory at your project root:
```bash theme={null}
.libretto/
├── config.json # Workspace settings such as viewport defaults
├── sessions/
│ └── /
│ ├── state.json # Debug port, browser PID, session status
│ ├── logs.jsonl # Structured CLI and runtime logs
│ ├── network.jsonl # Captured HTTP requests and responses
│ ├── actions.jsonl # Recorded user and agent actions
│ └── snapshots/ # PNG screenshots and HTML captures
│ └── /
└── profiles/
└── .json # Saved auth state (cookies, localStorage)
```
**`config.json`:** Workspace settings such as viewport, browser provider, and session-mode defaults. Created by `npm create libretto@latest` or `npx libretto setup`. See [Configuration](/understand-libretto/configuration) for details.
Sessions and profiles are automatically git-ignored by a `.libretto/.gitignore` file created during setup. The config file and skill files are meant to be committed.
### Sessions
A **session** is a named browser context. When you run `npx libretto open https://example.com --session my-session`, Libretto launches a Chromium instance and registers it under that name. Subsequent commands (`snapshot`, `exec`, `pages`) all target that session by name.
Sessions are created automatically when you run `open`, `connect`, or `run`, and cleaned up with `npx libretto close`.
If you don't pass `--session`, Libretto generates a unique session name automatically. Sessions are independent: you can have multiple sessions open at the same time, each pointing to a different browser or URL.
#### Session files
**`state.json`:** Metadata Libretto uses to reconnect to a browser session: the CDP debug port, the browser process PID, and the session status (`active`, `paused`, `completed`, `failed`, `exited`).
**`logs.jsonl`:** Structured JSONL log of CLI events for the session. Useful for tracing what happened during a run.
**`network.jsonl`:** One entry per HTTP request/response captured while the session was open. Each entry includes `ts`, `method`, `url`, `status`, `contentType`, and `responseBody`. Query with `jq`:
```bash theme={null}
# Show all POST requests
jq 'select(.method == "POST")' .libretto/sessions/my-session/network.jsonl
```
**`actions.jsonl`:** One entry per user or agent action. User entries include `bestSemanticSelector`, `nearbyText`, and coordinates. Agent entries include the Playwright locator and duration. Query with `jq`:
```bash theme={null}
# Last 20 actions
tail -n 20 .libretto/sessions/my-session/actions.jsonl | jq .
```
**`snapshots/`:** One subdirectory per `snapshot` run, containing the captured PNG and HTML file.
For authenticated sites, see [Website authentication](/understand-libretto/website-authentication) to learn how to declare credentials, use TOTP secrets, and save reusable login profiles.
---
title: How workflow generation works
url: "https://libretto-docs.vercel.app/docs/understand-libretto/how-workflow-generation-works.md"
description: "Whether the agent is generating a workflow from scratch, recording your actions, or debugging a broken script, it follows the same four-phase process. Each..."
---
> What happens under the hood when your agent builds a browser automation.
Whether the agent is generating a workflow from scratch, recording your actions, or debugging a broken script, it follows the same four-phase process. Each phase is designed around a specific constraint of how AI agents interact with browsers.
### 1. Browser session
The agent starts by launching a browser and registering it as a named session. The session becomes the agent's handle to the browser for everything that follows: snapshots, interactions, and validation all target the session by name.
Sessions track all state (network traffic, actions, snapshots) in `.libretto/sessions//`. This gives the agent a persistent record of what it has seen and done, so it can refer back to earlier observations without re-inspecting the page.
If the site requires authentication, the agent opens the browser in headed mode and asks you to log in. It cannot handle login flows on its own because most login pages include CAPTCHAs or multi-factor prompts that require a human.
### 2. Page snapshot
Rather than reading the full page DOM, the agent captures a screenshot and compact accessibility snapshot. The snapshot output gives the agent a token-efficient view of selectors, interactive elements, and visible state.
The compact snapshot strips away irrelevant markup while preserving the information the agent needs to reason about what's on the page and how to interact with it. This keeps the agent's context window small while still giving it a detailed understanding of the page.
The agent snapshots frequently: before its first interaction, after navigation, and any time it needs to understand what changed. For large pages, it can inspect a subtree from the latest full snapshot by passing a printed ref back to `snapshot`.
### 3. Interaction prototyping
Before writing any code, the agent tests its plan against the live browser. It runs Playwright expressions one at a time through `exec`, validating that each selector actually targets the right element and each action produces the expected result.
The agent iterates between `snapshot` and `exec` during this phase. A typical loop looks like: snapshot the page to find a selector, exec an action using that selector, snapshot again to confirm the result. This cycle repeats until the agent has working selectors for each step of the workflow.
Prototyping against the live page is what separates Libretto from writing a Playwright script from scratch. Instead of guessing at selectors and hoping they work, the agent confirms each one interactively before committing it to the final script.
### 4. Code generation and validation
Once the agent has validated all the interactions, it writes a TypeScript file that exports a `workflow()` with Zod input and output schemas. The workflow uses the same Playwright selectors the agent already tested, so the script is grounded in what actually worked on the live page.
The agent then runs the workflow headless to verify it works end-to-end without any manual intervention. If the run fails, the agent re-enters the snapshot-and-prototype loop (phases 2 and 3) to diagnose and fix the issue, then tries the headless run again.
Validation requires a successful headless run with correct output. The agent does not consider a workflow complete until it has passed this check.
### How the workflow guides fit in
Each [workflow guide](/guides/one-shot-workflow-generation) follows this same four-phase process with different starting points:
* **One-shot generation:** The agent drives the entire process. You provide a prompt, the agent handles all four phases.
* **Interactive building:** You drive phases 1 and 2 by performing the workflow in the browser while Libretto records your actions. The agent handles phases 3 and 4.
* **Debugging:** You start at a failed workflow (phase 4) and the agent uses phases 2 and 3 to diagnose and fix it.
---
title: Configuration
url: "https://libretto-docs.vercel.app/docs/understand-libretto/configuration.md"
description: "Both npm create libretto@latest and npx libretto setup handle initial configuration for you. The commands on this page are for changing settings after the..."
---
> Change viewport, browser provider, or other workspace settings after initial setup.
Both `npm create libretto@latest` and `npx libretto setup` handle initial configuration for you. The commands on this page are for changing settings after the fact.
### Environment variables
Libretto automatically loads the repo root `.env` file before running CLI commands. Put provider credentials there:
```dotenv theme={null}
# inside .env
KERNEL_API_KEY=
BROWSERBASE_API_KEY=
BROWSERBASE_PROJECT_ID=
STEEL_API_KEY=
```
Use `.libretto/config.json` for persistent workspace preferences like the default browser provider.
### Config file reference
The config file is at `.libretto/config.json`. You can edit it directly.
```json theme={null}
{
"version": 1,
"provider": "local",
"viewport": { "width": 1280, "height": 800 },
"sessionMode": "write-access"
}
```
Config schema version.
Deprecated. This key is ignored by `npx libretto snapshot`, which now prints a compact accessibility tree directly instead of using a configured analysis model.
Optional. The browser provider to use. Must be `"local"`, `"kernel"`, `"browserbase"`, `"steel"`, or `"libretto-cloud"`. Defaults to `"local"`. Can be overridden per-command with `--provider` or the `LIBRETTO_PROVIDER` environment variable. Resolution order: `--provider` flag → `LIBRETTO_PROVIDER` env var → this config field → `"local"`.
If you deploy to a cloud host using `kernel`, `browserbase`, `steel`, or `libretto-cloud`, set `provider` here too. Then local `open`, `run`, and debugging use the same browser as production — the container's Chromium isn't identical to your local one, and the drift causes inconsistent rendering and timing.
Optional, manually set. Default browser window size (width and height in pixels) used by `open` and `run` when you don't pass `--viewport`. Defaults to `1366x768` if not set.
Optional, manually set. Default access mode for new sessions created by `open`, `connect`, and `run`. Must be `"read-only"` or `"write-access"`. Defaults to `"write-access"` when omitted. Pass `--read-only` or `--write-access` to `open`, `connect`, or `run` to override when creating a session.
Optional, manually set. Sets the initial position of the headed browser window on screen. Has no effect in headless mode.
---
title: "Automation & bot detection"
url: "https://libretto-docs.vercel.app/docs/understand-libretto/automation-and-bot-detection.md"
description: "Libretto supports four distinct approaches to capturing data and automating web interactions. Each makes different trade-offs between detection risk, setup..."
---
> Choose the right integration strategy and understand bot detection trade-offs.
### Overview
Libretto supports four distinct approaches to capturing data and automating web interactions. Each makes different trade-offs between detection risk, setup complexity, data quality, and control. Knowing the trade-offs helps you pick the right approach for your target site.
| Approach | Bot detection risk | Best for |
| -------------------------------------------- | ------------------ | --------------------------------------------------- |
| Regular Playwright | Low-Moderate | Simple DOM extraction, server-rendered sites |
| Passive interception (`page.on('response')`) | Low | SPAs that load data via API calls during navigation |
| In-browser fetch (`pageRequest()`) | Moderate | API endpoints normally called with fetch/XHR |
| Direct HTTP from Node.js | Very high | Sites with no bot detection where API speed matters |
### Assessing bot detection
Bot detection avoidance is best-effort. Libretto cannot guarantee your
automation will go undetected. Using Libretto with authenticated accounts may
violate the terms of service of those services. Understand the risks before
automating against any site you don't control.
Libretto captures all network traffic and page state during a session, which lets you (or your agent) check what bot detection measures a site uses before committing to an automation approach:
* **Network log inspection.** Query `.libretto/sessions//network.jsonl` with `jq` to review all requests and responses. Look for calls to bot detection services (Cloudflare, Akamai, PerimeterX, DataDome) or challenge endpoints.
* **Fetch patching check.** Run `npx libretto exec` to evaluate `window.fetch.toString()` in the browser console. If it returns actual JavaScript (not `"[native code]"`), the site monkey-patches fetch and you should prefer passive interception over in-browser fetch.
* **Request type comparison.** Compare requests in `network.jsonl` before replacing browser behavior with `pageRequest()`. Browsers attach request-context headers that say what caused the request. A top-level navigation has `sec-fetch-dest: document` and `sec-fetch-mode: navigate`. A JavaScript fetch has `sec-fetch-dest: empty` and `sec-fetch-mode: cors` or `same-origin`. Script, image, stylesheet, and iframe loads have their own shapes too.
* **Snapshot inspection.** Use `npx libretto snapshot` to check for challenge pages, CAPTCHAs, or interstitials that indicate detection.
***
### Approach details
Standard Playwright usage: navigate pages, click elements, fill forms, and read DOM content using selectors and `page.evaluate()`.
```typescript theme={null}
// Navigate and interact
await page.goto('https://example.com/search');
await page.fill('#query', 'search term');
await page.click('#submit');
await page.waitForSelector('.results');
// Extract data from the DOM
const results = await page.evaluate(() => {
return Array.from(document.querySelectorAll('.result-item')).map(el => ({
title: el.querySelector('h2')?.textContent,
price: el.querySelector('.price')?.textContent,
}));
});
```
**Pros:**
* Simplest approach, uses Playwright as intended
* No need to understand the site's API structure
* Works with any site regardless of how data is rendered (server-side, client-side, or hybrid)
* Data extraction is visual/DOM-based, which maps naturally to what a user sees
* Easy to debug with `headless: false` and Playwright's trace viewer
* Integrates directly with Libretto's step-based workflow and recovery features
**Cons:**
* Slower than API-based approaches because it requires full page rendering
* Fragile against DOM changes, since selectors break when the site updates its markup
* Harder to get structured data because you're scraping rendered HTML rather than clean API responses
* Cannot access data that isn't rendered in the DOM (e.g., API responses with fields the UI doesn't display)
**Bot detection risk: LOW-MODERATE**
Plain Playwright is detectable by browser fingerprinting (Layer 1). Sites with any enterprise bot protection will likely flag it. Sites without active detection won't notice.
Use `playwright-extra` with the stealth plugin to patch common fingerprint leaks, or run Playwright with a persistent browser context that looks more like a real browser profile.
Listen to network responses the browser naturally makes as you navigate. You don't make any extra requests, you just capture the data flowing through.
```typescript theme={null}
const capturedData: any[] = [];
page.on('response', async (response) => {
const url = response.url();
if (url.includes('/api/search/results')) {
const json = await response.json();
capturedData.push(json);
}
});
// Trigger the data load by interacting with the UI normally
await page.goto('https://example.com/search?q=term');
await page.waitForSelector('.results');
// capturedData now has the raw API response
```
**Pros:**
* Zero additional bot detection risk from network requests because you're not making any extra calls. The requests that happen are the ones the site's own code triggers.
* Gets clean, structured API data (JSON) rather than scraped DOM content
* API responses often contain more data than the UI displays (hidden fields, IDs, metadata)
* Not fragile against DOM changes, since the API contract tends to be more stable than CSS selectors
* Works with Playwright's existing page context with no additional setup
**Cons:**
* You only get data that the page naturally loads, so you must trigger the right UI flow to cause the requests you need
* Still requires Playwright browser automation to drive the page, so you have the browser fingerprinting risk for the navigation itself
* Timing can be tricky. You must set up the listener before the navigation that triggers the request.
* Responses may be paginated or partial. The site's UI might lazy-load data, requiring you to trigger scrolling or "load more" interactions.
* If the site uses GraphQL or batched API calls, parsing the right data out of responses requires understanding the API structure
* Some responses may be encrypted or obfuscated by bot protection services
**Bot detection risk: LOW**
The network requests themselves carry zero additional risk since they originate from the site's own JavaScript. The only risk is from the browser automation layer needed to drive the UI. No extra fetch calls means no anomalous network patterns for API-level monitoring to flag.
Execute fetch calls from within the browser page's JavaScript context. The requests originate from the browser process with the browser's cookies, session, and TLS fingerprint. They still look like fetch/XHR requests. Libretto's `pageRequest()` function provides a typed wrapper for this pattern.
```typescript theme={null}
const data = await page.evaluate(async () => {
const res = await fetch('/api/search/results?q=term&page=2', {
headers: {
'Content-Type': 'application/json',
'X-Requested-With': 'XMLHttpRequest',
},
});
return res.json();
});
```
**Pros:**
* Requests come from the real browser with the same TLS fingerprint, cookies, origin, and HTTP/2 settings. This works best for endpoints the site's own app calls with fetch or XHR.
* Full control over which endpoints you call and with what parameters, no need to trigger UI flows
* Can call endpoints the UI doesn't naturally hit (e.g., fetch page 50 of results without clicking "next" 49 times)
* Gets clean, structured API data (JSON)
* Faster than driving the UI: skip page rendering and go straight to the data
**Cons:**
* Requires understanding the site's API: you need to know the endpoint URLs, required headers, authentication tokens, and request body format. You'll need to reverse-engineer the site's network traffic first.
* Does not inherit the request type of the browser primitive the site normally uses. A browser fetch is sent as `resourceType: "fetch"` with headers like `sec-fetch-dest: empty` and `sec-fetch-mode: cors`, while a page navigation is sent as `resourceType: "document"` with `sec-fetch-dest: document`, `sec-fetch-mode: navigate`, `sec-fetch-user: ?1`, and `upgrade-insecure-requests: 1`. Script, image, CSS, and iframe loads have different request shapes too.
* Browser JavaScript generally cannot set the key `Sec-Fetch-*` headers manually. Copying headers into a fetch call usually does not make it look like a different kind of browser request.
* Vulnerable to fetch/XHR monkey-patching. If the site wraps `window.fetch`, your calls may be intercepted and flagged because the call stack won't match the site's expected code paths.
* Riskier for full document URLs, such as search result pages. Use `page.goto()` and parse the loaded document, or capture the responses the site's own app naturally triggers.
* Still requires a Playwright browser to be running (for the execution context)
* API endpoints can change without notice
* Must handle authentication tokens and CSRF tokens that the site's own code normally manages
**Bot detection risk: MODERATE**
The requests are genuine browser requests, but they still expose a fetch/XHR request context. The risk comes from browser fingerprinting, request type mismatches, fetch/XHR monkey-patching, and timing or pattern analysis if your requests don't match normal UI flow.
Rule of thumb: match the browser primitive to the site's real request type. Use `page.goto()` or a link click for page HTML, `pageRequest()` for API requests the site normally makes with fetch/XHR, and passive interception when you can let the site's own code make the request.
Make HTTP requests directly from Node.js using the built-in `fetch` API. No browser involved.
```typescript theme={null}
const response = await fetch('https://example.com/api/search/results?q=term&page=1', {
headers: {
'User-Agent': 'Mozilla/5.0 ...',
'Cookie': 'session=abc123; ...',
},
});
const data = await response.json();
```
**Pros:**
* Fastest approach, with no browser overhead, no page rendering, and minimal memory usage
* Simple code: just HTTP requests, no browser lifecycle management
* Easy to parallelize. Make many concurrent requests without launching multiple browser instances.
* Lowest resource consumption, suitable for high-volume data collection
**Cons:**
* No cookies unless manually managed. You must extract cookies from a browser session and replicate them, including HttpOnly cookies you can't access from JS.
* No browser-specific headers. `sec-ch-ua`, `sec-fetch-*`, and other headers that browsers add automatically must be manually fabricated.
* No JavaScript execution. If the site requires JS to set cookies, generate tokens, or solve challenges, you can't do it.
* CSRF and auth tokens must be manually extracted and refreshed
* Breaks easily. API changes, new security headers, or updated bot protection will break requests with no fallback.
**Bot detection risk: VERY HIGH.** This approach is detectable at nearly every layer. TLS fingerprinting alone will catch Node.js HTTP clients on any site with even basic bot protection. The TLS fingerprint is fundamentally different from any real browser, and this is one of the strongest detection signals. This approach only works reliably against sites with zero bot detection, or against documented public APIs that expect programmatic access.
***
### Decision guide
**Recommended approach:** Use in-browser fetch (`pageRequest()`) for verified API endpoints that the site normally calls with fetch/XHR. It gives you full control over which endpoints you call, structured JSON responses, and the real browser's network fingerprint.
For high-security sites with aggressive bot detection (Cloudflare, Akamai, PerimeterX, DataDome), use Regular Playwright for navigation and passive `page.on('response')` interception for data capture. This avoids making any extra requests that could trigger detection.
**Use Regular Playwright when:**
* The data you need is visible in the DOM and straightforward to extract with selectors
* The site doesn't have aggressive bot protection, or you're using stealth plugins
* You want the simplest implementation that integrates with Libretto's recovery features
* The data is rendered server-side and doesn't come from a separate API call
**Use passive interception (`page.on('response')`) when:**
* The site loads data via API calls during normal navigation (most modern SPAs)
* You want structured JSON data without reverse-engineering the full API
* Minimizing detection risk is important
* You're already navigating through the UI and want to passively capture data along the way
**Use in-browser fetch (`pageRequest()`) when:**
* You need data from API endpoints that the UI doesn't naturally trigger (e.g., deep pagination, bulk exports)
* You've verified the site doesn't monkey-patch `fetch` (or you can work around it)
* You've verified the target endpoint is normally called with fetch/XHR, not loaded as a document, script, image, stylesheet, or iframe
* You want maximum control over which data you fetch and when
* You've already reverse-engineered the relevant API endpoints
**Use Direct Node.js HTTP when:**
* The target site has zero bot detection
* Speed and resource efficiency are the primary concerns
* You're hitting a public/documented API (not scraping a website)
* You need to make thousands of concurrent requests
---
title: Website authentication
url: "https://libretto-docs.vercel.app/docs/understand-libretto/website-authentication.md"
description: "Libretto supports two website authentication tools: By default, Libretto-generated login workflows combine both: the workflow starts with the named auth..."
---
> Use credentials for scripted login, auth profiles for saved browser state, and `librettoAuthenticate` to recover when a saved session is missing or expired.
Libretto supports two website authentication tools:
* `credentials` are secrets such as usernames, passwords, API keys, and TOTP shared secrets. Use them when the workflow can log in with Playwright.
* `authProfile` is named browser state for a signed-in session. Use it when a workflow should start from an existing login or preserve login state across runs.
By default, Libretto-generated login workflows combine both: the workflow starts with the named auth profile, checks whether it is signed in, and signs in with credentials when the profile is missing, expired, or logged out.
```typescript theme={null}
import { librettoAuthenticate, workflow } from "libretto";
import { z } from "zod";
export default workflow("portalReport", {
startUrl: "https://portal.example.com",
credentials: ["username", "password"],
authProfile: {
name: "portal",
refresh: true,
},
input: z.object({
reportId: z.string(),
}),
output: z.object({
title: z.string(),
}),
async handler(ctx, input) {
const { page } = ctx;
await librettoAuthenticate(ctx, {
credentials: input.credentials,
isSignedIn: async ({ page }) =>
await page
.getByRole("button", { name: /account|sign out/i })
.isVisible()
.catch(() => false),
signIn: async ({ page }, credentials) => {
await page.goto("https://portal.example.com/login");
await page.getByLabel("Email").fill(credentials.username);
await page.getByLabel("Password").fill(credentials.password);
await page.getByRole("button", { name: /log in/i }).click();
},
});
await page.goto(`https://portal.example.com/reports/${input.reportId}`);
const title = await page.locator("h1").innerText();
return { title };
},
});
```
In this pattern, the auth profile handles the common case where the browser is already signed in. The `signIn` step handles the recovery case where the profile is missing, expired, or logged out. If sign-in succeeds and `refresh: true` is set, the run saves the updated browser state back to the profile for future runs.
### Credentials
Credentials are separate from normal workflow input. Declare the names the workflow needs, then read the resolved values from `input.credentials`. Do not pass secrets through `--params`.
For local runs, store matching variables in `.env`:
```dotenv theme={null}
LIBRETTO_CLOUD_USERNAME=alice@example.com
LIBRETTO_CLOUD_PASSWORD=secret
LIBRETTO_CLOUD_TOTP_SECRET=JBSWY3DPEHPK3PXP
```
Libretto removes the `LIBRETTO_CLOUD_` prefix and lowercases the rest, so `LIBRETTO_CLOUD_USERNAME` becomes `input.credentials.username`.
For hosted runs, store the same credential names in Libretto Cloud. See [Libretto Cloud credentials](/libretto-cloud-api/credentials).
Never put secrets in workflow params, logs, or source code. Use declared credentials backed by `.env` locally and Libretto Cloud credentials in hosted runs.
### Auth profiles
An auth profile is named browser state for a login session. Local profiles live in `.libretto/profiles/.json`; hosted profiles are provider-native browser profiles managed by Libretto Cloud and the active browser provider.
Use the workflow-level `authProfile` option:
```typescript theme={null}
authProfile: "portal"
authProfile: {
name: "portal",
refresh: true,
}
```
Use `{ name, refresh: true }` when successful runs should persist updated browser state back to the profile. On local runs, this updates the local `.libretto/profiles/.json` file. On hosted runs, it asks the browser provider to persist changes to the provider-native profile.
The preferred way to create a local profile is to sign in through a headed Libretto session and save it:
```bash theme={null}
npx libretto open https://portal.example.com --headed --session portal-login
# Log in manually in the browser window.
npx libretto save portal --session portal-login --sites portal.example.com
```
Use this when the login cannot be scripted with Playwright, such as CAPTCHAs, device approvals, or magic links. For repeatable SMS one-time codes on Libretto Cloud, see [`claimSmsOtp`](/reference/runtime/sms-otp). Once an auth profile is saved, the workflow can use `authProfile: "portal"` or `authProfile: { name: "portal", refresh: true }` without repeating the manual login every run.
If you already have a signed-in Chrome profile and explicitly want to copy from it, start that Chrome profile with remote debugging enabled and import only the sites you need:
```bash theme={null}
npx libretto import-chrome-profiles portal --cdp-url http://127.0.0.1:9222 --sites portal.example.com
```
Chrome often needs to be closed and relaunched with a temporary user-data directory before remote debugging can attach. Importing from Chrome can close or relaunch that browser window, so confirm with the user before doing it.
Use `--sites` only when saving or importing a local profile. It controls which site storage is copied into the local profile. See [CLI profiles](/reference/cli/profiles).
### Hosted website authentication
Hosted runs do not upload local `.libretto/profiles/.json` files. They use provider-native profiles with the workflow's `authProfile.name`. `libretto cloud deploy` registers missing profile names, and hosted runs populate or refresh the provider profile when sign-in succeeds.
For the hosted model, provider behavior, and profile persistence details, see [Website authentication in Libretto Cloud](/libretto-cloud-hosting/website-authentication).
### Runtime helpers
Use [`librettoAuthenticate`](/reference/runtime/authentication) when a workflow has an auth profile and scripted sign-in. The helper runs your `isSignedIn` check, calls your `signIn` function if needed, and checks again before the workflow continues.
Use [`claimSmsOtp`](/reference/runtime/sms-otp) inside `signIn` (or any scripted login) when the portal texts a one-time code. Provision the inbox outside the workflow, claim it before send-code, then wait for the code.
---
title: Error recovery
url: "https://libretto-docs.vercel.app/docs/understand-libretto/error-handling-and-recovery.md"
description: "Libretto helps your agent handle failures in two ways: inspect failed runs so it can fix the deterministic workflow, or add a narrow runtime recovery action..."
---
Libretto helps your agent handle failures in two ways: inspect failed runs so it can fix the deterministic workflow, or add a narrow runtime recovery action for expected nondeterminism.
Most workflow failures should be fixed with better selectors, waits, or assertions. Runtime recovery is for cases where the workflow is on the right path but the site sometimes shows unexpected UI that blocks the next action.
## Debugging failed runs
When a workflow fails during development, the Libretto CLI helps your agent debug the code by preserving the browser session. The agent can run headed, add `pause(ctx.session)` at useful checkpoints, inspect the page state, iterate on code, and use `resume` to continue from the pause before redeploying.
For deployed workflows on the hosted platform, a failed run automatically starts an analysis agent. It reviews the error, logs, recording, screenshots, and browser state so it can explain what went wrong and suggest the code change.
## Runtime recovery actions
Add `recoveryAction` to a workflow when you want Libretto to recover after a supported Page or Locator action fails. Libretto calls the recovery action, then retries the original action once.
```typescript theme={null}
export default workflow("reviewOrder", {
input,
output,
recoveryAction: popupRecoveryAction({
provider: "openai",
apiKey: process.env.OPENAI_API_KEY!,
model: "gpt-5.5",
maxSteps: 3,
}),
handler: async ({ page }, params) => {
await page.goto(params.url);
await page.locator("#review").click();
return { complete: true };
},
});
```
## AI vision recovery
The computer use recovery action looks at the current screen and takes one or more browser actions to get back to the expected path. It is useful for nondeterministic blockers such as cookie banners, popups, modals, interstitials, and overlays that intercept clicks.
It uses a viewport screenshot, asks the model for an action, scales the returned screenshot coordinates to Playwright coordinates, and executes the action.
`popupRecoveryAction()` is the built-in preset for closing popups and other blockers. Use `computerUseRecoveryAction()` when you want to provide your own instruction.
Simple sites without nondeterministic UI usually do not need AI vision recovery. For complicated sites automated through the DOM, add it when exploration shows blockers across sessions, accounts, or time. Do not use it to make business decisions that belong in the workflow handler.
Supported provider shortcut models are `gpt-5.5` and `claude-sonnet-4-6`.
---
title: Playwright debugging agent
url: "https://libretto-docs.vercel.app/docs/understand-libretto/autofix-debugging.md"
description: How Libretto investigates Playwright failures and opens pull requests that fix broken scripts.
---
When a Playwright automation fails, Libretto's Playwright debugging agent
investigates the failure against the live website and automatically opens a pull
request that fixes the broken script. It turns a broken run into a reviewable
change instead of a pager alert.
You add one call in your script's failure path; Libretto does the rest. For the
API and configuration, see the
[Playwright debugging agent reference](/reference/runtime/playwright-debugger).
## Why it inspects the live page
A stack trace and a static DOM snapshot are rarely enough to fix a browser
automation. A selector like `input[name="username"]` might have failed because
the real field is `name="login"`, because the page redirected, or because an
element loads late — and the source code alone cannot tell you which.
The debugging agent does not guess. It runs an agent loop on the
[`libretto-browser-tools`](https://www.npmjs.com/package/libretto-browser-tools) SDK and
drives the supplied failed page in its existing browser context. Authentication,
storage, open tabs, network routes, and in-memory state remain available while
the agent confirms the cause. Fixes are grounded in what the agent actually
observed on the page.
## The flow
1. **Capture.** On failure, the debugger records the error, stack, URL, title,
screenshot, and DOM snapshot, and reads the relevant source files from your
repo at the base branch.
2. **Investigate.** The agent snapshots the failed page's live accessibility
tree and runs Playwright code in the same browser context (for example,
checking whether a selector resolves) until it is confident about the root
cause.
3. **Fix.** It produces a minimal, full-file change for the files that must
change — or, if the evidence is insufficient, it proposes nothing.
4. **Open a PR.** The change is committed to a new branch and opened as a pull
request whose description cites the failure and the evidence behind the fix.
## What you need
* **A connected GitHub repository.** Install the Libretto GitHub App and link
the repo so Libretto can open PRs on it.
* **A `LIBRETTO_API_KEY`.** The agent exchanges it for a short-lived,
repo-scoped GitHub token — you never manage a raw GitHub token in production.
* **The debugger call in your script.** Add
`playwrightDebugger.debugFailure(error, page)` in your automation's `catch`
block before Playwright teardown.
The [setup flow](https://libretto.sh/setup) walks through connecting GitHub,
minting the API key, and adding the debugger to an existing script.
## Relationship to error recovery
The Playwright debugging agent fixes the deterministic workflow *after* a
failure by opening a PR. For expected nondeterminism that should be handled
*during* a run, use a narrow runtime recovery action instead — see
[Error recovery](/understand-libretto/error-handling-and-recovery).
---
title: "open & connect"
url: "https://libretto-docs.vercel.app/docs/reference/cli/open-and-connect.md"
description: "The open command launches a browser and navigates to a URL, creating a new named session. It is the starting point for any interactive workflow: once a session..."
---
> Launch a browser session or attach to an existing Chrome DevTools Protocol endpoint.
### open
The `open` command launches a browser and navigates to a URL, creating a new named session. It is the starting point for any interactive workflow: once a session is open, `exec`, `snapshot`, and `pages` all work against it.
```bash theme={null}
npx libretto open https://example.com
npx libretto open https://example.com --headless --session debug-example
```
#### When to use `open`
* At the start of script authoring when you need live page state to decide how the workflow should work.
* When the user needs to log in manually before automation begins (use `--headed`).
* Any time you need a fresh, isolated browser instance on a specific URL.
#### Flags
The URL to open. Passed as the first positional argument.
Run the browser in headed (visible) mode. This is the default when neither
flag is passed.
Run the browser in headless mode. Useful for automated runs that don't need a
visible window.
Name for this session. If omitted, Libretto generates a unique name
automatically. Use a consistent name to target the session with later
commands.
Viewport size in `WIDTHxHEIGHT` format, for example `1920x1080`. Falls back to
the value in `.libretto/config.json`, then `1366x768`.
Browser provider to use. One of `local`, `kernel`, `browserbase`, `steel`, or `libretto-cloud`. Defaults to `local`.
**Resolution order:** `--provider` flag → `LIBRETTO_PROVIDER` env var → `provider` field in `.libretto/config.json` → `"local"`.
If a saved auth profile exists for the URL's domain, `open` automatically
loads it, injecting the saved cookies and localStorage into the new session
before navigating. You can override this by passing `--auth-profile`
explicitly, or skip profile loading by not having a saved profile for that
domain.
#### Examples
```bash theme={null}
# Open in headed mode (default)
npx libretto open https://example.com --headed
# Open in headless mode with an explicit session name
npx libretto open https://example.com --headless --session debug-example
# Open with a custom viewport
npx libretto open https://example.com --viewport 1440x900 --session my-session
# Open for a manual login flow, then save the session
npx libretto open https://linkedin.com --headed --session app-login
# ... user logs in ...
npx libretto save linkedin.com --session app-login
```
***
### Cloud browser providers
By default, `open` launches a local Chromium instance. You can instead run the browser in the cloud using the `--provider` flag (or `LIBRETTO_PROVIDER` env var, or `provider` in `.libretto/config.json`).
#### Available providers
| Provider | Value | Required environment variables |
| ------------------------ | ---------------- | ----------------------------------------------- |
| Local Chromium (default) | `local` | None |
| Kernel | `kernel` | `KERNEL_API_KEY` |
| Browserbase | `browserbase` | `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID` |
| Steel | `steel` | `STEEL_API_KEY` |
| Libretto Cloud | `libretto-cloud` | `LIBRETTO_API_KEY` |
#### Configuration
You can set the provider in three ways (highest precedence first):
1. **CLI flag:** `--provider kernel` (or `-p kernel`)
2. **Environment variable:** `LIBRETTO_PROVIDER=kernel`
3. **Config file:** add `"provider": "kernel"` to `.libretto/config.json`
If none is set, the default is `local`.
#### Examples
```bash theme={null}
# Open with Kernel cloud browser
export KERNEL_API_KEY="your-key"
npx libretto open https://example.com --provider kernel
# Open with Browserbase
export BROWSERBASE_API_KEY="your-key"
export BROWSERBASE_PROJECT_ID="your-project-id"
npx libretto open https://example.com -p browserbase
# Open with Steel
export STEEL_API_KEY="your-key"
npx libretto open https://example.com --provider steel
# Open with Libretto Cloud
export LIBRETTO_API_KEY="your-key"
npx libretto open https://example.com --provider libretto-cloud
# Set provider via config so you don't need the flag every time
# .libretto/config.json: { "version": 1, "provider": "kernel" }
npx libretto open https://example.com
```
Cloud providers ignore `--headed` / `--headless` and `--viewport` flags since
the browser runs remotely. The session is always headless from the local
machine's perspective.
***
### connect
The `connect` command attaches to an existing Chrome DevTools Protocol (CDP) endpoint rather than launching a new browser. Use it to drive a browser that is already running, for example one started with `--remote-debugging-port`, an Electron application, or any other CDP-compatible target.
```bash theme={null}
npx libretto connect http://127.0.0.1:9222 --session my-session
npx libretto connect ws://127.0.0.1:9223 --session another-session
```
#### When to use `connect`
* You have an existing browser process you want to automate without restarting it.
* You are driving an Electron app exposed over CDP.
* You want to attach to a remote browser in a CI environment that has already navigated to the right state.
For executing a default-exported `workflow()` file against that same CDP endpoint without an interactive session first, use [`run --cdp`](/reference/cli/run-and-resume#run-against-an-external-cdp-browser) instead.
#### Flags
The CDP endpoint URL to connect to. This can be either an HTTP or WebSocket
URL and is passed as the first positional argument. Example:
`http://127.0.0.1:9222`.
Name for this session. Recommended to set explicitly when using `connect` so
you can reference it later.
#### After connecting
Once connected, all session-scoped commands work normally against the attached browser:
* `exec`: run Playwright TypeScript code
* `snapshot`: capture a screenshot and compact accessibility tree
* `pages`: list open pages
Libretto does **not** manage the lifecycle of a connected process. Running `npx libretto close --session ` clears the Libretto session record but does **not** terminate the remote browser or Electron app.
#### Examples
```bash theme={null}
# Attach to a Chrome instance started with --remote-debugging-port
npx libretto connect http://127.0.0.1:9222 --session chrome-debug
# Inspect the attached page
npx libretto snapshot --session chrome-debug
# Run code against it
npx libretto exec --session chrome-debug "await page.url()"
```
Execute Playwright TypeScript against the open page.
Capture a screenshot and compact accessibility tree.
---
title: sessions
url: "https://libretto-docs.vercel.app/docs/reference/cli/sessions.md"
description: "Almost every Libretto command accepts --session to target a specific browser session. When you omit --session on commands that support auto-generation..."
---
> Manage named browser sessions and control session access modes.
### The `--session` flag
Almost every Libretto command accepts `--session ` to target a specific browser session. When you omit `--session` on commands that support auto-generation (`open`, `run`), Libretto creates a unique name automatically.
Session state is stored under `.libretto/sessions//`:
```txt
.libretto/
sessions/
/
state.json
logs.jsonl
network.jsonl
actions.jsonl
snapshots/
```
Session directories are git-ignored. Each session runs an isolated browser instance on a dynamic port.
***
### close
The `close` command closes a browser session and cleans up its state.
```bash theme={null}
npx libretto close --session debug-example
npx libretto close --all
```
#### When to use `close`
* When you are done with a session.
* When an exploration session is no longer helping progress and you want to free up the browser.
* For full workspace cleanup at the end of a task.
When using `connect` to attach to an external CDP endpoint, `close` clears the
Libretto session record but **does not terminate the remote browser process**.
#### Flags
The session to close. Required unless `--all` is passed.
Close all tracked sessions in this workspace.
Force-kill sessions that do not respond to SIGTERM. Requires `--all`.
#### Examples
```bash theme={null}
# Close a named session
npx libretto close --session debug-example
# Close all sessions in the workspace
npx libretto close --all
# Close all sessions, force-killing any that are unresponsive
npx libretto close --all --force
```
***
### Read-only sessions
Read-only mode prevents any mutating browser actions (clicks, typing, navigation, form fills) while still allowing inspection. This is useful for diagnosing live production sessions without risking accidental state changes.
#### Starting a read-only session
Pass `--read-only` to `open`, `connect`, or `run`:
```bash theme={null}
npx libretto open https://example.com --read-only --session diag
npx libretto connect ws://localhost:9222 --read-only --session remote-diag
npx libretto run ./workflow.ts --read-only --session test-run
```
You can also manually set `sessionMode` in `.libretto/config.json` to change the default for all new sessions:
```json theme={null}
{
"version": 1,
"sessionMode": "read-only"
}
```
Pass `--write-access` to `open`, `connect`, or `run` to override a `read-only` config default when creating a session.
#### Changing session mode
View or change the mode of an existing session with `session-mode`:
```bash theme={null}
# View current mode
npx libretto session-mode --session my-session
# Switch to read-only
npx libretto session-mode read-only --session my-session
# Switch back to write-access
npx libretto session-mode write-access --session my-session
```
#### What's allowed in read-only mode
| Command | Allowed |
| --------------- | ------- |
| `snapshot` | Yes |
| `readonly-exec` | Yes |
| `pages` | Yes |
| `close` | Yes |
| `session-mode` | Yes |
| `exec` | No |
#### `readonly-exec`
A restricted version of `exec` that only allows read operations on the page. Available methods include:
* **Page reads**: `url()`, `title()`, `content()`, `viewportSize`, `waitForLoadState`, `waitForURL`
* **Locator factories**: `locator()`, `getByRole()`, `getByText()`, `getByLabel()`, `getByPlaceholder()`, `getByAltText()`, `getByTitle()`, `getByTestId()`
* **Locator reads**: `textContent()`, `innerText()`, `boundingBox()`, `count()`, `getAttribute()`, `inputValue()`, `isVisible()`, `isHidden()`, `isEnabled()`, `isChecked()`
* **Network**: `get(url)` (GET/HEAD only, no request bodies)
* **Viewport**: `scrollBy(deltaX, deltaY)` for scrolling by pixel offset
* **Other**: `state`, `console`, `URL`, `Buffer`
Any mutating operation (click, fill, goto, reload, etc.) throws a `ReadonlyExecDenied` error.
```bash theme={null}
# Read page title
npx libretto readonly-exec --session diag "return await page.title()"
# Check if an element is visible
npx libretto readonly-exec --session diag "return await page.locator('#submit').isVisible()"
# Get text content of a section
npx libretto readonly-exec --session diag "return await page.locator('.results').textContent()"
```
---
title: profiles
url: "https://libretto-docs.vercel.app/docs/reference/cli/profiles.md"
description: "The save command saves the current browser session's cookies, localStorage, and IndexedDB as a named local auth profile. Workflows load it by declaring..."
---
> Save and reuse authenticated browser state across runs.
### save
The `save` command saves the current browser session's cookies, localStorage, and IndexedDB as a named local auth profile. Workflows load it by declaring `authProfile`.
```bash theme={null}
npx libretto save linkedin --session app-login --sites linkedin.com
```
#### When to use `save`
Only use `save` when you want to save or reuse authenticated browser state. A typical flow:
```bash theme={null}
npx libretto open https://linkedin.com --headed --session app-login
```
The browser window is visible. Log in as usual.
```bash theme={null}
npx libretto save linkedin --session app-login --sites linkedin.com
```
The profile is saved to `.libretto/profiles/linkedin.json`.
Declare `authProfile: "linkedin"` in the workflow, then run it normally:
```bash theme={null}
npx libretto run ./integration.ts
```
#### Flags
The local profile name. Passed as the first positional argument. Example:
`linkedin`, `twitter`, or `twitter2`.
The session to save. Use the same name you passed to `npx libretto open --session`.
Comma-separated site or domain list to capture, for example
`linkedin.com,auth.linkedin.com`.
Subdomains do not need to be listed separately when the parent domain is enough
for the login. For example, `linkedin.com` captures cookies for
`www.linkedin.com` and `auth.linkedin.com`. Add multiple sites when the login
uses separate parent domains, such as `example.com,example-login.com`.
### Storage-state profiles and persistent browser profiles
The `save` command creates a Playwright storage-state profile. It preserves
cookies, localStorage, and IndexedDB, which is sufficient for most websites. It
does not preserve sessionStorage, service-worker memory, or authentication that
the server binds to a specific browser process.
Use a persistent browser profile when signing in again after loading a saved
auth profile invalidates the session. Launch Chrome with a dedicated
`--user-data-dir`, keep that browser process running, and attach Libretto with
`connect`.
A persistent browser profile contains credentials and the browser's complete
local state. Give each account a separate directory, restrict filesystem
access, and do not run multiple browser processes against the same directory.
### import-chrome-profiles
The `import-chrome-profiles` command imports cookies, localStorage, and IndexedDB
from an existing Chrome DevTools Protocol session into a named local profile.
The profile name is the local Libretto profile you want to create. The `--sites`
list decides which signed-in sites are copied from Chrome.
```bash theme={null}
npx libretto import-chrome-profiles twitter --cdp-url http://127.0.0.1:9222 --sites x.com,twitter.com
```
Start Chrome with remote debugging enabled, log in normally, then run the fetch
command. The CDP URL comes from the Chrome process you launched with
`--remote-debugging-port`; for example, port `9222` gives
`http://127.0.0.1:9222`. The profile is saved under
`.libretto/profiles/.json`.
The command asks before attaching because disconnecting from an existing CDP
session can close or relaunch that Chrome window. Use `--yes` only when the
user has already consented.
Recent Chrome versions reject remote debugging against the default user-data
directory; if Chrome prints that error, copy the desired profile to a temporary
user-data directory and launch Chrome from that copy.
### cloud profiles list
List hosted auth profile names known to Libretto Cloud:
```bash theme={null}
npx libretto cloud profiles list
```
`libretto cloud deploy` automatically registers any `authProfile` names declared
by deployed workflows. Hosted runs use the browser provider's native profile API;
local profile files are not uploaded.
Local profiles and cloud profiles are intentionally separate. There is no command
to copy a local profile file into a cloud profile, or to download a cloud profile
into `.libretto/profiles/`. Local profiles are Playwright storage-state JSON for
local runs; cloud profiles are provider-native browser profiles managed by the
hosted browser provider.
### cloud profiles delete
Delete a hosted auth profile name and its provider mappings:
```bash theme={null}
npx libretto cloud profiles delete twitter
```
***
### Profile storage
Profiles are stored in `.libretto/profiles/.json`. They are:
* Machine-local, not shared across environments or team members.
* Git-ignored by default.
* Subject to session expiry. If authentication stops working, repeat the login-and-save flow.
Profiles contain session cookies that are effectively credentials. The
`.libretto/` directory is already git-ignored, but double-check your
`.gitignore` if you're storing Libretto state in a non-standard location.
---
title: snapshot
url: "https://libretto-docs.vercel.app/docs/reference/cli/snapshot.md"
description: The snapshot command is the primary page observation tool. It captures a screenshot and prints a compact accessibility tree for the current page so agents can...
---
> Capture a screenshot and compact accessibility snapshot of the current page.
The `snapshot` command is the primary page observation tool. It captures a screenshot and prints a compact accessibility tree for the current page so agents can inspect page structure without sending page state to a separate analysis model.
Use `snapshot` before guessing at selectors, after workflow failures, and whenever the visible page state is unclear.
```bash theme={null}
npx libretto snapshot --session debug-example
```
### Arguments
Optional element ref to scope output to that subtree, for example `l16` or
`e16`. Each call captures a fresh screenshot and accessibility tree, then
scopes the printed tree to that ref.
### Required flags
The session to snapshot.
### Optional flags
Target a specific page ID within the session. Use `npx libretto pages --session ` to list page IDs when a popup or new tab is open. See [pages](/reference/cli/pages) for details.
### What snapshot produces
For each run, `snapshot` saves a screenshot under `.libretto/sessions//snapshots//page.png`.
The command prints:
* the screenshot path
* a compact accessibility tree for the page or requested subtree
* a hint for inspecting subtree refs from the latest full snapshot
### When to use snapshot
* Before writing a selector. Use snapshot to confirm the element structure rather than guessing.
* After a workflow step fails. Inspect the exact page state the failure left behind.
* When the page has rendered content that isn't obvious from the URL alone.
* When you need a scoped view of a large page. Run a full snapshot, then inspect relevant refs with `snapshot [`.
Use ref forms printed in the tree, such as `l16`. Numeric-suffix aliases such
as `e16` also match `l16`.
### Configuration
`snapshot` does not require AI provider credentials or a configured model. The legacy `snapshotModel` config key is deprecated and ignored by the default snapshot flow.
### Examples
```bash theme={null}
# Basic snapshot
npx libretto snapshot --session debug-example
# Snapshot a specific page in a multi-page session
npx libretto snapshot --session debug-example --page
# Inspect a subtree from the latest full snapshot
npx libretto snapshot ][ --session debug-example
```
Run Playwright code to prototype interactions after using snapshot to identify elements.
Run a full workflow file and use snapshot to debug failures.
---
title: exec
url: "https://libretto-docs.vercel.app/docs/reference/cli/exec.md"
description: "The exec command runs TypeScript Playwright code against a live browser session. Use it to validate selectors, inspect page data, prototype individual steps,..."
---
> Execute Playwright TypeScript in a persistent REPL for an open browser page.
The `exec` command runs TypeScript Playwright code against a live browser session. Use it to validate selectors, inspect page data, prototype individual steps, and experiment with interactions before encoding them in a workflow file.
`exec` evaluates code in a persistent REPL scoped to the browser session. Values come from expressions, top-level `await` is supported, and declarations remain available to later `exec` calls in the same session.
```bash theme={null}
npx libretto exec --session debug-example "await page.url()"
```
### Usage
Pass the code as a quoted string argument:
```bash theme={null}
npx libretto exec --session debug-example "await page.url()"
npx libretto exec --session debug-example "await page.locator('button').count()"
npx libretto exec --session debug-example "await page.locator('button:has-text(\"Continue\")').click()"
```
Pipe code into `exec -` for complex or multi-line scripts:
```bash theme={null}
echo "await page.url()" | npx libretto exec - --session debug-example
```
```bash theme={null}
cat <<'EOF' | npx libretto exec - --session debug-example
async function tableRows(selector: string) {
const rows = await page.locator(`${selector} tbody tr`).all();
const data = [];
for (const row of rows) {
const cells = await row.locator('td').allTextContents();
data.push(cells);
}
return data;
}
EOF
npx libretto exec --session debug-example "await tableRows('table')"
```
### Available globals
Inside the code you pass to `exec`, these variables are available without any imports:
| Global | Type | Description |
| --------------- | ---------------- | ----------------------------------------- |
| `page` | `Page` | The active Playwright page |
| `frame` | `Frame` | The active page's main frame |
| `context` | `BrowserContext` | The browser context for the session |
| `browser` | `Browser` | The browser instance |
| `fetch` | `typeof fetch` | The global fetch function |
| `Buffer` | `typeof Buffer` | Node.js `Buffer` |
| `console` | `Console` | Standard console (`log`, `warn`, `error`) |
| `setTimeout` | `function` | Schedule a callback after a delay |
| `setInterval` | `function` | Schedule a repeating callback |
| `clearTimeout` | `function` | Cancel a scheduled `setTimeout` |
| `clearInterval` | `function` | Cancel a scheduled `setInterval` |
| `URL` | `typeof URL` | The WHATWG `URL` constructor |
### Persistent REPL
Each browser session has a persistent `exec` REPL. Define helper functions once, then reuse them in later calls:
```bash theme={null}
cat <<'EOF' | npx libretto exec - --session debug-example
async function textOf(selector: string) {
return await page.locator(selector).textContent();
}
EOF
npx libretto exec --session debug-example "await textOf('h1')"
```
The `page` and `frame` globals are refreshed for each call, including calls that use `--page `.
### Flags
The Playwright TypeScript code to execute, passed as the first positional
argument. Pass `-` to read from stdin.
The session to execute against.
Target a specific page ID within the session. Use `npx libretto pages --session ` to list page IDs when a popup or new tab is open.
Enable ghost cursor and highlight visualization. Shows a visible cursor trace
and element highlights as Playwright interacts with the page.
After a successful `exec`, wait for the page to settle and print a compact
accessibility-tree diff of what changed. Use this for exploratory mutations
when you do not know what will change. Omit it when you already know what to
check — return that value from `exec`, or run `snapshot` afterward.
### Return values
If the code evaluates to a value, `exec` prints it to stdout:
* Strings are printed as-is.
* All other values are printed as pretty-printed JSON.
* If the code evaluates to `undefined`, `exec` prints `Executed successfully`.
```bash theme={null}
npx libretto exec --session debug-example "await page.title()"
# My Page Title
npx libretto exec --session debug-example "await page.locator('li').count()"
# 12
```
### Rules
**Let failures throw.** Do not hide `exec` failures with `try/catch` or
`.catch()`. Swallowed errors make debugging harder. Surface them so you can
see exactly what failed.
**Do not run multiple `exec` commands in parallel.** Each `exec` call drives
the same browser page. Running them concurrently causes race conditions.
* Use `exec` for focused inspection and short-lived interaction experiments.
* Use `exec -` (stdin) for complex multi-line scripts.
* Validate a selector with `exec` before encoding it in a workflow file.
* Use `exec` to prototype a single step, then move the working code into your `.ts` workflow file.
* Do not use top-level `return`; write the expression you want to inspect.
### Examples
```bash theme={null}
# Print the current URL
npx libretto exec --session debug-example "await page.url()"
# Count how many buttons are on the page
npx libretto exec --session debug-example "await page.locator('button').count()"
# Click a button
npx libretto exec --session debug-example "await page.locator('button:has-text(\"Continue\")').click()"
# Read a value from an input field
npx libretto exec --session debug-example "await page.locator('input[name=\"email\"]').inputValue()"
# Run against a specific page in a session
npx libretto exec --session debug-example --page "await page.url()"
# Pipe from stdin (multi-line, named session)
echo "await page.url()" | npx libretto exec - --session debug-example
```
Use snapshot to identify selectors before running exec.
Move validated exec code into a workflow file and run it end to end.
---
title: "run & resume"
url: "https://libretto-docs.vercel.app/docs/reference/cli/run-and-resume.md"
description: The run command executes the default export from a TypeScript workflow file against a live browser. Use it to verify a workflow after creating or editing it....
---
> Execute a workflow file and resume paused workflows.
### run
The `run` command executes the default export from a TypeScript workflow file against a live browser. Use it to verify a workflow after creating or editing it.
```bash theme={null}
npx libretto run ./integration.ts
npx libretto run ./integration.ts --headless
```
#### Syntax
```bash theme={null}
npx libretto run [flags]
```
* ``: path to the TypeScript workflow file. The file must have a default-exported `workflow()`.
#### Flags
Run the browser in headless mode. Use this for the normal fix-and-verify loop.
Run the browser in headed (visible) mode. This is the default when neither
flag is passed.
Name for this run session. Auto-generated if omitted. Use an explicit name to
target the session with `exec`, `snapshot`, or `resume` after a failure or
pause.
Inline JSON input for the workflow, passed as a quoted string. When the
workflow uses Zod schemas, Libretto validates this input against
`schemas.input` before the handler runs. Example:
`--params '{"status":"open"}'`.
Path to a JSON file to use as workflow input. Cannot be used together with
`--params`. When the workflow uses Zod schemas, the file contents are
validated against `schemas.input`.
Viewport size in `WIDTHxHEIGHT` format, for example `1920x1080`. Falls back to
`.libretto/config.json`, then `1366x768`.
Path to a `tsconfig.json` file for module resolution during workflow
compilation.
Disable ghost cursor and element highlight visualization in headed mode.
Browser provider to use for this run. Must be `local`, `kernel`, `browserbase`,
`steel`, or `libretto-cloud`. Overrides `LIBRETTO_PROVIDER` and the `provider` setting
in `.libretto/config.json`. Cannot be combined with `--cdp`.
Connect to an existing Chrome DevTools Protocol endpoint instead of launching a
browser. Use this for Electron apps or Chrome started with
`--remote-debugging-port`. Cannot be combined with `--provider`, `--headed`,
`--headless`, or `--viewport`. Libretto attaches to the selected page without
navigating to workflow `startUrl`, so the existing URL and authentication
state stay intact. Closing the Libretto session disconnects from CDP and does
not terminate the remote browser.
When using `--cdp`, target a specific discovered page id such as `page-0` or
`page-1`. Omit to use the default (last operational page). Requires `--cdp`.
To keep local debugging and workflow runs on the same browser provider, set
`provider` in `.libretto/config.json`. See [Alternative
providers](/alternative-providers/overview) for Kernel, Browserbase, Steel, AWS, and
GCP setup.
#### Run against an external CDP browser
Use `--cdp` when the browser already exists (Electron, remote debugging Chrome, CI browser). Use interactive [`connect`](/reference/cli/open-and-connect#connect) to explore with `exec` / `snapshot`; use `run --cdp` to execute a workflow file against that same endpoint. Unlike a normal `run`, `--cdp` does not open workflow `startUrl` — put the browser on the page you want before the run, or navigate inside the handler.
```bash theme={null}
# Chrome or Electron started with --remote-debugging-port=9222
npx libretto run ./integration.ts --cdp http://127.0.0.1:9222
# Target a specific window/page (ids from `libretto pages` on a connect session)
npx libretto run ./integration.ts --cdp http://127.0.0.1:9222 --page page-1
```
#### Behavior on failure
When a workflow fails, Libretto keeps the browser open at the point of failure. You can then use `snapshot` and `exec` to inspect the live page state before editing the workflow code.
```bash theme={null}
# Workflow fails, browser stays open
npx libretto run ./integration.ts --session debug-flow --headed
# Inspect the failure state
npx libretto snapshot --session debug-flow
# Prototype a fix
npx libretto exec --session debug-flow "await page.locator('.error-message').textContent()"
# Re-run after fixing the code
npx libretto run ./integration.ts --headless
```
#### Validation loop
Prefer `run --headless` for the normal fix-and-verify loop. When the headless run passes, do a final headed run if you or the user wants to watch the finished workflow:
```bash theme={null}
# Fix/verify loop, fast, no visible browser
npx libretto run ./integration.ts --headless
# Final confirmation run, shows the browser
npx libretto run ./integration.ts --headed
```
#### Examples
```bash theme={null}
# Basic run
npx libretto run ./integration.ts
# Headless run with inline params
npx libretto run ./integration.ts --headless --params '{"status":"open"}'
# Run with a params file
npx libretto run ./integration.ts --params-file ./params.json
# Run with explicit session name for post-failure inspection
npx libretto run ./integration.ts --session debug-flow --headed
# Run against an external CDP / Electron browser
npx libretto run ./integration.ts --cdp http://127.0.0.1:9222
```
***
### resume
The `resume` command unpauses a workflow that has stopped at an `await pause(session)` call. Use it repeatedly until the workflow completes or pauses again at the next breakpoint.
```bash theme={null}
npx libretto resume --session debug-example
```
#### Flags
The session name of the paused workflow to resume.
#### The `pause()` API
Insert `await pause(session)` calls in your workflow file to create interactive breakpoints, similar to debugger breakpoints in the browser flow. The workflow stops at each `pause()` call and waits for `resume` before continuing.
```typescript theme={null}
import { workflow, pause } from "libretto";
import { z } from "zod";
export default workflow(
"myWorkflow",
{
input: z.object({}),
output: z.object({
done: z.boolean(),
}),
},
async (ctx) => {
const { session, page } = ctx;
await page.goto("https://linkedin.com");
// Pause here for inspection
await pause(session);
await page.locator("#submit").click();
// Pause again before the final step
await pause(session);
return { done: true };
},
);
```
`pause()` is a **no-op when `NODE_ENV === "production"`**. You can leave
`pause()` calls in your workflow code during development and they will be
silently skipped in production.
#### Complete debugging flow
```bash theme={null}
npx libretto run ./integration.ts --session debug-flow --headed
```
If the workflow hits a `pause()`, it prints `Workflow paused.` and returns. The browser stays open.
```bash theme={null}
npx libretto snapshot --session debug-flow
npx libretto exec --session debug-flow "await page.url()"
```
```bash theme={null}
npx libretto resume --session debug-flow
```
Keep running `resume` until the workflow prints `Integration completed.` or fails with an error.
Edit the workflow file to fix any issues found during inspection, then re-run:
```bash theme={null}
npx libretto run ./integration.ts --headless
```
Inspect page state after a failure or pause.
Prototype fixes against the paused browser before editing code.
---
title: session logs
url: "https://libretto-docs.vercel.app/docs/reference/cli/session-logs.md"
description: Libretto automatically records network requests and browser actions to JSONL log files during every session. Your agent reads these files directly to...
---
> Understand the JSONL log files Libretto captures during every session.
Libretto automatically records network requests and browser actions to JSONL log files during every session. Your agent reads these files directly to reverse-engineer APIs, reconstruct workflows from user behavior, and debug failures.
### Log file locations
```txt
.libretto/sessions//
logs.jsonl # CLI and system events
network.jsonl # HTTP requests and responses
actions.jsonl # User and agent browser actions
```
***
### network.jsonl
One JSON object per line, one entry per HTTP request/response captured while the session was open.
#### Key fields
| Field | Description |
| -------------- | ------------------------------------------ |
| `ts` | ISO timestamp of the request |
| `method` | HTTP method (`GET`, `POST`, `PUT`, etc.) |
| `url` | Full request URL |
| `status` | HTTP response status code |
| `contentType` | Response content type |
| `responseBody` | Response body string (may be `null`) |
| `postData` | Request body for POST/PUT requests |
| `pageId` | Playwright page ID that produced the entry |
#### Querying examples
```bash theme={null}
# All POST requests
jq 'select(.method == "POST")' .libretto/sessions//network.jsonl
# Find requests to a specific endpoint
jq 'select(.url | contains("/api/"))' .libretto/sessions//network.jsonl
# View JSON API responses
jq 'select(.contentType | contains("application/json")) | .responseBody' \
.libretto/sessions//network.jsonl
# Count requests by HTTP method
jq -r '.method' .libretto/sessions//network.jsonl | sort | uniq -c
```
***
### actions.jsonl
One JSON object per line, one entry per browser interaction. Libretto records both actions you perform manually in the browser (`source: "user"`) and actions the agent performs programmatically (`source: "agent"`).
#### Key fields
| Field | Description |
| ---------------------- | ---------------------------------------------------------------- |
| `ts` | ISO timestamp |
| `source` | `user` (manual DOM event) or `agent` (Playwright call) |
| `action` | Action name: `click`, `dblclick`, `fill`, `goto`, `reload`, etc. |
| `selector` | Locator used by the agent |
| `bestSemanticSelector` | Canonical selector from the user DOM event |
| `nearbyText` | Visible text near the event target |
| `coordinates` | `{x, y}` for pointer events |
| `value` | Typed, selected, or submitted value |
| `url` | Navigation target for goto-style actions |
| `duration` | Elapsed time in milliseconds (agent entries) |
| `success` | `true` if the action completed, `false` on failure |
| `error` | Error message when the action failed |
Agent entries describe what Playwright tried to do (`selector`, `duration`). User entries describe what DOM element was actually interacted with (`bestSemanticSelector`, `nearbyText`, `coordinates`).
#### Querying examples
```bash theme={null}
# Last 20 actions
tail -n 20 .libretto/sessions//actions.jsonl | jq .
# Show only user-initiated actions
jq 'select(.source == "user")' .libretto/sessions//actions.jsonl
# Find all failed actions
jq 'select(.success == false)' .libretto/sessions//actions.jsonl
# Extract selector and action for agent entries
jq 'select(.source == "agent") | {action: .action, selector: .selector}' \
.libretto/sessions//actions.jsonl
```
***
### logs.jsonl
Structured CLI and system log. Contains debug output from Libretto itself, including command execution, errors, and internal events.
```bash theme={null}
# View the last 20 log entries
tail -n 20 .libretto/sessions//logs.jsonl | jq .
```
---
title: pages
url: "https://libretto-docs.vercel.app/docs/reference/cli/pages.md"
description: "The pages command lists all open pages (tabs) in a session and prints their IDs and URLs. After running pages, pass the target page ID to other commands with..."
---
> List open browser tabs in a session and target specific pages.
### pages
The `pages` command lists all open pages (tabs) in a session and prints their IDs and URLs.
```bash theme={null}
npx libretto pages --session debug-example
```
#### When to use `pages`
* A popup or new tab opened during navigation or interaction.
* `exec` or `snapshot` fails because more than one page is open in the session.
* You are not sure which page holds the relevant state.
After running `pages`, pass the target page ID to other commands with `--page `:
```bash theme={null}
# List pages
npx libretto pages --session debug-example
# Target a specific page
npx libretto exec --session debug-example --page "await page.url()"
npx libretto snapshot --session debug-example --page
```
#### Flags
The session to list pages for.
---
title: Workflow
url: "https://libretto-docs.vercel.app/docs/reference/runtime/workflow.md"
description: "The workflow() factory is the entry point for every Libretto automation. You wrap your Playwright logic in a typed handler, define Zod schemas for the workflow..."
---
> Define and run reusable browser automation workflows.
The `workflow()` factory is the entry point for every Libretto automation. You wrap your Playwright logic in a typed handler, define Zod schemas for the workflow input and output, export the result, and the CLI (or your own runner) takes care of launching a browser, validating input, wiring up context, and invoking your handler.
### `workflow()`
Creates a named `LibrettoWorkflow` from input/output Zod schemas and a handler function.
```typescript theme={null}
function workflow<
InputSchema extends z.ZodType,
OutputSchema extends z.ZodType,
>(
name: string,
schemas: {
input: InputSchema;
output: OutputSchema;
},
handler: LibrettoWorkflowHandler<
z.infer,
z.infer
>,
): LibrettoWorkflow;
```
The handler receives a `LibrettoWorkflowContext` and typed `input`, and must return a `Promise]