exec

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.

1npx libretto exec --session debug-example "await page.url()"

Usage

Pass the code as a quoted string argument:

123npx 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()"

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:

1234567cat <<'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 <page-id>.

Flags

path codestringrequired

The Playwright TypeScript code to execute, passed as the first positional argument. Pass - to read from stdin.

path --sessionstringrequired

The session to execute against.

path --pagestring

Target a specific page ID within the session. Use npx libretto pages --session <name> to list page IDs when a popup or new tab is open.

path --visualizeboolean

Enable ghost cursor and highlight visualization. Shows a visible cursor trace and element highlights as Playwright interacts with the page.

path --diff-snapshotboolean

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.

12345npx 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

1234567891011121314151617# 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 <page-id> "await page.url()"

# Pipe from stdin (multi-line, named session)
echo "await page.url()" | npx libretto exec - --session debug-example

snapshot

Use snapshot to identify selectors before running exec.

run & resume

Move validated exec code into a workflow file and run it end to end.

Ask AI about this page