Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Core concepts

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, validates input with a Zod schema, and gives the handler typed access to page, session, and parsed input.

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 declare credentials, use TOTP secrets, and save reusable login profiles.
Libretto
Powered byHolocron