Skip to main content

Documentation Index

Fetch the complete documentation index at: https://libretto.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

How Libretto organizes browsers, sessions, and state.

​
CLI vs Library API

Libretto ships two interfaces:
  • CLI (npx libretto <command>): 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 <name> 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 and gives it typed access to page and session.

​
The .libretto/ directory

All Libretto state lives in a .libretto/ directory at your project root: 
.libretto/
├── config.json              # Workspace settings such as viewport defaults
├── sessions/
│   └── <name>/
│       ├── 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
│           └── <snapshot-id>/
└── profiles/
    └── <domain>.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 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: 
# 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: 
# 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 to learn how to pass credentials, TOTP secrets, and save reusable login profiles.