Skip to main content
This guide walks you through installing Libretto, connecting an AI provider, opening a browser, and taking your first snapshot.
1

Install the package

Install Libretto from npm:
npm install libretto
Libretto requires Node.js 18 or later. It installs Playwright as a direct dependency, so you don’t need a separate Playwright install.
2

Initialize your workspace

Run init once per project. This command downloads Chromium if it isn’t already installed, creates the .libretto/ directory structure, writes a .libretto/.gitignore, and copies the agent skill files into .agents/skills/libretto and .claude/skills/libretto.
npx libretto init
Run init yourself in a terminal — not through an agent. It may prompt for input and starts a Chromium download that takes a moment.
3

Configure an AI provider

Snapshot analysis requires a vision-capable model. Choose your provider:
npx libretto ai configure openai
# or
npx libretto ai configure anthropic
# or
npx libretto ai configure gemini
# or
npx libretto ai configure vertex
This writes the selected model to .libretto/config.json. The default models are:
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 model string to use a specific version:
npx libretto ai configure openai/gpt-4o
Provider credentials are read from your shell environment or a .env file at the project root. Set the appropriate key:
export OPENAI_API_KEY=sk-...
Libretto uses the Vercel AI SDK under the hood. Install only the peer dependency for your chosen provider:
npm install @ai-sdk/openai
4

Open a browser

Launch a headed Chromium window and navigate to a URL:
npx libretto open https://example.com
To use a named session (recommended when running multiple automations):
npx libretto open https://example.com --session my-session
Use --headless if you don’t need to see the browser:
npx libretto open https://example.com --headless --session my-session
5

Take a snapshot

snapshot captures a PNG screenshot and the page HTML, then sends both to your configured vision model. Always provide --objective (what you want the model to find or analyze) and --context (what you know about the current state):
npx libretto snapshot \
  --objective "Find the main heading and any call-to-action buttons" \
  --context "I just opened the example.com homepage and want to identify the key interactive elements."
With a named session:
npx libretto snapshot \
  --session my-session \
  --objective "Explain why the table is empty" \
  --context "I applied filters on the referrals page and expected rows to appear."
The model returns a structured summary of selectors, element descriptions, and any relevant observations — without putting raw HTML into your agent’s context.
A single snapshot objective can include multiple questions. Instead of running several snapshots, combine them: --objective "Find the submit button and check whether the form has validation errors."
6

Execute Playwright code

Use exec to run Playwright TypeScript against the open page. The code runs in a context that has page, context, browser, state, fetch, and Buffer available as globals:
npx libretto exec "return await page.url()"

npx libretto exec "return await page.locator('button').count()"

npx libretto exec "await page.locator('button:has-text(\"Continue\")').click()"
For longer scripts, pipe from stdin with -:
echo "return await page.url()" | npx libretto exec - --session my-session
Let failures throw. Don’t wrap exec code in try/catch — surfacing errors is how you debug.
7

Run a workflow file

Once you’ve built a workflow file, run it with npx libretto run:
npx libretto run ./integration.ts main
Run headless with input parameters:
npx libretto run ./integration.ts main --headless --params '{"status":"open"}'
Run with a saved auth profile:
npx libretto run ./integration.ts main --auth-profile app.example.com
The second argument (main) is the name of the exported workflow() instance in the file. See the Library API reference for how to structure workflow files.

​
What’s next

If you’re using a coding agent like Claude or another AI assistant, load the Libretto skill so your agent knows how to use these commands effectively. After running npx libretto init, the skill is available at .agents/skills/libretto/SKILL.md and .claude/skills/libretto/SKILL.md.
Once Libretto is set up, explore the full command set: 
npx libretto --help
Common commands to try next: 
npx libretto network                    # view captured HTTP requests
npx libretto actions                    # view recorded user/agent actions
npx libretto pages                      # list open pages in the session
npx libretto save app.example.com       # save authenticated browser state
npx libretto close                      # close the browser
npx libretto close --all                # close all sessions

Build docs developers (and LLMs) love

Get started for freeTalk to us