Skip to main content
The snapshot command is the primary page observation tool. It captures a screenshot and the full HTML of the current page, then sends both to an AI model for analysis against your stated objective. Use snapshot before guessing at selectors, after workflow failures, and whenever the visible page state is unclear. 
npx libretto snapshot \
  --objective "Find the sign-in form and submit button" \
  --context "I just opened the login page and need the email field, password field, and submit button."

​
Required flags

​
--objective
string
required
What you want the AI to find, analyze, or explain. A single objective can include multiple questions or analysis tasks — you don’t need to run separate snapshots for each question.
​
--context
string
required
Background information that helps the AI understand the current state of the page. Describe what you just did, what you expected to happen, and what the page should contain.

​
Optional flags

​
--session
string
required
The session to snapshot.
​
--page
string
Target a specific page ID within the session. Use npx libretto pages --session <name> to list page IDs when a popup or new tab is open. See pages & close for details.

​
What snapshot produces

For each run, snapshot saves three files under .libretto/sessions/<session>/snapshots/<snapshot-id>/:
FileContents
page.pngFull-page screenshot
page.htmlRaw page HTML
page.condensed.htmlToken-optimized condensed HTML sent to the model
The command prints the paths to all three files before the AI analysis output.

​
When to use snapshot

  • Before writing a selector — use snapshot to confirm the element structure rather than guessing.
  • After a workflow step fails — inspect the exact page state the failure left behind.
  • When the page has rendered content that isn’t obvious from the URL alone.
  • When you need answers to multiple questions about a page in a single call.
A single --objective can ask several things at once. For example: "Find the submit button selector, confirm whether there are validation errors, and identify the field that currently has focus." Batching questions into one snapshot is more efficient than calling snapshot repeatedly.

​
Timeout

Snapshot sends a request to an external AI API and waits for the full analysis response. Depending on page complexity and model speed, this can take 30–90 seconds or more.
If you are calling snapshot from a shell script or wrapping it in another tool, set a timeout of at least 2 minutes to avoid premature cancellation.

​
Configuration

Snapshot analysis requires a configured AI model. Run npx libretto init on first setup, or use npx libretto ai configure <provider> to set or change the model later. Credentials are read from environment variables or a .env file at your project root. Supported providers: openai, anthropic, gemini, vertex.

​
Examples

# Basic snapshot — find a form
npx libretto snapshot \
  --objective "Find the sign-in form and submit button" \
  --context "I just opened the login page and need the email field, password field, and submit button."

# Snapshot a specific session after a failure
npx libretto snapshot \
  --session debug-example \
  --objective "Explain why the table is empty" \
  --context "I opened the referrals page, applied filters, and expected rows to appear."

# Snapshot a specific page in a multi-page session
npx libretto snapshot \
  --session debug-example \
  --page <page-id> \
  --objective "Find the active form" \
  --context "A modal opened after clicking the Edit button. I need the form fields inside it."

# Snapshot during debugging — ask multiple things at once
npx libretto snapshot \
  --session debug-flow \
  --objective "Find the blocking error or broken selector target. Also describe the current page URL and any visible error messages." \
  --context "The workflow just failed after trying to continue from the review step, and I need to identify the visible blocker on the current page."

exec

Run Playwright code to prototype interactions after using snapshot to identify elements.

run & resume

Run a full workflow file and use snapshot to debug failures.

Build docs developers (and LLMs) love

Get started for freeTalk to us