Skip to main content
Execute Playwright TypeScript code against the 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. 
npx libretto exec --session debug-example "return await page.url()"

​
Usage

Pass the code as a quoted string argument:
npx libretto exec --session debug-example "return await page.url()"
npx libretto exec --session debug-example "return 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:
GlobalTypeDescription
pagePageThe active Playwright page
contextBrowserContextThe browser context for the session
browserBrowserThe browser instance
stateRecord<string, unknown>A mutable object scoped to this exec call
fetchtypeof fetchThe global fetch function
Buffertypeof BufferNode.js Buffer
networkLogfunctionRead captured network log entries
actionLogfunctionRead captured action log entries
consoleConsoleStandard console (log, warn, error)
setTimeoutfunctionSchedule a callback after a delay
setIntervalfunctionSchedule a repeating callback
clearTimeoutfunctionCancel a scheduled setTimeout
clearIntervalfunctionCancel a scheduled setInterval
URLtypeof URLThe WHATWG URL constructor

​
Flags

​
code
string
required
The Playwright TypeScript code to execute, passed as the first positional argument. Pass - to read from stdin.
​
--session
string
required
The session to execute against.
​
--page
string
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.
​
--visualize
boolean
Enable ghost cursor and highlight visualization. Shows a visible cursor trace and element highlights as Playwright interacts with the page.

​
Return values

If the code returns a value, exec prints it to stdout:
  • Strings are printed as-is.
  • All other values are printed as pretty-printed JSON.
  • If the code returns nothing (undefined), exec prints Executed successfully.
npx libretto exec --session debug-example "return await page.title()"
# My Page Title

npx libretto exec --session debug-example "return 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.

​
Examples

# Return the current URL
npx libretto exec --session debug-example "return await page.url()"

# Count how many buttons are on the page
npx libretto exec --session debug-example "return 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 "return await page.locator('input[name=\"email\"]').inputValue()"

# Run against a named session
npx libretto exec --session debug-example "return await page.url()"

# Run against a specific page in a session
npx libretto exec --session debug-example --page <page-id> "return await page.url()"

# Pipe from stdin (multi-line, named session)
echo "return 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.