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

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

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
.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](/understand-libretto/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`:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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`:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](/understand-libretto/website-authentication) to learn how to declare credentials, use TOTP secrets, and save reusable login profiles.