Skip to main content
All Libretto state lives in a .libretto/ directory at your project root. This page covers the config file, environment variables, sessions, and auth profiles.
Add .libretto/ to your .gitignore. Libretto creates a .libretto/.gitignore that automatically ignores sessions/ and profiles/, but the config.json file itself is not ignored. If you prefer to exclude the entire directory, add .libretto/ to your root .gitignore.

​
Config file

Location: .libretto/config.json The config file controls snapshot analysis and the default viewport. The easiest way to create or update it is through the CLI: 
npx libretto ai configure <openai|anthropic|gemini|vertex>
You can also edit the file directly. The full schema is: 
{
  "version": 1,
  "ai": {
    "model": "openai/gpt-5.4",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "viewport": { "width": 1280, "height": 800 }
}

​
Fields

​
version
number
required
Config schema version. Always 1.
​
ai
object
Configures the model used for snapshot analysis. Snapshot analysis is required — without it, npx libretto snapshot will fail.
​
ai.model
string
A provider/model-id string, for example openai/gpt-5.4, anthropic/claude-sonnet-4-6, google/gemini-3-flash-preview, or vertex/gemini-2.5-pro. This is the model Libretto sends screenshot and HTML data to when you run snapshot.
​
ai.updatedAt
string
ISO 8601 timestamp of the last time the AI config was written. Set automatically by npx libretto ai configure.
​
viewport
object
Default viewport size used by open and run when you don’t pass --viewport. Precedence: CLI --viewport flag > config.json > built-in default of 1366x768.
​
viewport.width
number
Viewport width in pixels. Must be a positive integer.
​
viewport.height
number
Viewport height in pixels. Must be a positive integer.
​
windowPosition
object
Optional. Sets the initial position of the headed browser window on screen. Has no effect in headless mode.
​
windowPosition.x
number
Horizontal position in pixels from the left edge of the screen.
​
windowPosition.y
number
Vertical position in pixels from the top of the screen.

​
AI provider setup

To set your model, run: 
npx libretto ai configure <provider>
Accepted provider shorthands and their default models:
ProviderDefault model
openaiopenai/gpt-5.4
anthropicanthropic/claude-sonnet-4-6
geminigoogle/gemini-3-flash-preview
vertexvertex/gemini-2.5-pro
You can also pass a full provider/model-id string to pin a specific version: 
npx libretto ai configure openai/gpt-4o
To view the current configuration: 
npx libretto ai configure
To clear it: 
npx libretto ai configure --clear

​
Environment variables

Provider credentials are read from your shell environment or a .env file at the project root. Set the variable for your chosen provider: 
OPENAI_API_KEY=sk-...
You also need to install the matching Vercel AI SDK peer dependency: 
npm install @ai-sdk/openai
All four peer dependencies are optional — install only the one you need.

​
Sessions

Each Libretto session gets its own directory under .libretto/sessions/<name>/. Sessions are created automatically when you run npx libretto open and are cleaned up with npx libretto close. Session directory layout: 
.libretto/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
    └── <run-id>/

​
Session files

state.json — Metadata Libretto uses to reconnect to a running browser: the CDP debug port, the browser process PID, and the session status (running, paused, 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. Sessions are git-ignored by .libretto/.gitignore.

​
Profiles

Profiles save browser session state — cookies, localStorage, and other persistent storage — so you can reuse authenticated state across runs without logging in again each time. Location: .libretto/profiles/<domain>.json

​
Saving a profile

  1. Open the site in headed mode so you can log in manually: 
    npx libretto open https://app.example.com --headed
  2. Log in to the site in the browser window.
  3. Save the current session state as a profile: 
    npx libretto save app.example.com

​
Using a profile

Pass --auth-profile <domain> to run: 
npx libretto run ./integration.ts main --auth-profile app.example.com
Sessions can expire. If a profile stops working, repeat the login and save flow to refresh it.
Profiles are machine-local and git-ignored. They are not safe to commit or share — they contain authentication tokens for live accounts.

Build docs developers (and LLMs) love

Get started for freeTalk to us