open & connect - Libretto

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, 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

# 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):

CLI flag: --provider kernel (or -p kernel)
Environment variable: LIBRETTO_PROVIDER=kernel
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

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

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 compact accessibility tree
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

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

exec

Execute Playwright TypeScript against the open page.

snapshot

Capture a screenshot and compact accessibility tree.

​open

​When to use open

​Flags

​Examples

​Cloud browser providers

​Available providers

​Configuration

​Examples

​connect

​When to use connect

​Flags

​After connecting

​Examples

exec

snapshot

open

When to use `open`

Flags

Examples

Cloud browser providers

Available providers

Configuration

Examples

connect

When to use `connect`

Flags

After connecting

Examples