Skip to main content
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. 
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

​
url
string
required
The URL to open. Passed as the first positional argument.
​
--headed
boolean
Run the browser in headed (visible) mode. This is the default when neither flag is passed.
​
--headless
boolean
Run the browser in headless mode. Useful for automated runs that don’t need a visible window.
​
--session
string
Name for this session. If omitted, Libretto generates a unique name automatically. Use a consistent name to target the session with later commands.
​
--viewport
string
Viewport size in WIDTHxHEIGHT format, for example 1920x1080. Falls back to the value in .libretto/config.json, then 1366x768.
​
--provider, -p
string
Browser provider to use. One of local, kernel, or browserbase. 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

# 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

ProviderValueRequired environment variables
Local Chromium (default)localNone
KernelkernelKERNEL_API_KEY
BrowserbasebrowserbaseBROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID

​
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

# 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

# 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. 
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.

​
Flags

​
cdp-url
string
required
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.
​
--session
string
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 analyze the page
  • pages: list open pages
Libretto does not manage the lifecycle of a connected process. Running npx libretto close --session <name> clears the Libretto session record but does not terminate the remote browser or Electron app.

​
Examples

# 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 \
  --objective "What is the current page state?" \
  --context "Just attached to a running browser."

# Run code against it
npx libretto exec --session chrome-debug "return await page.url()"

exec

Execute Playwright TypeScript against the open page.

snapshot

Capture a screenshot and analyze page state.