Skip to main content

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.

Capture a screenshot and compact accessibility snapshot of the current page.
The snapshot command is the primary page observation tool. It captures a screenshot and prints a compact accessibility tree for the current page so agents can inspect page structure without sending page state to a separate analysis model. Use snapshot before guessing at selectors, after workflow failures, and whenever the visible page state is unclear. 
npx libretto snapshot --session debug-example

​
Arguments

​
ref
string
Optional element ref to scope output to that subtree, for example l16 or e16. Run an unscoped snapshot first; subtree snapshots capture a fresh screenshot but reuse the latest cached tree for that page.

​
Required flags

​
--session
string
required
The session to snapshot.

​
Optional flags

​
--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 for details.

​
What snapshot produces

For each run, snapshot saves a screenshot under .libretto/sessions/<session>/snapshots/<snapshot-id>/page.png. The command prints:
  • the screenshot path
  • a compact accessibility tree for the page or requested subtree
  • a hint for inspecting subtree refs from the latest full snapshot

​
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 a scoped view of a large page. Run a full snapshot, then inspect relevant refs with snapshot <ref>.
Use ref forms printed in the tree, such as l16. Numeric-suffix aliases such as e16 also match l16.

​
Configuration

snapshot does not require AI provider credentials or a configured model. The legacy snapshotModel config key is deprecated and ignored by the default snapshot flow.

​
Examples

# Basic snapshot
npx libretto snapshot --session debug-example

# Snapshot a specific page in a multi-page session
npx libretto snapshot --session debug-example --page <page-id>

# Inspect a subtree from the latest full snapshot
npx libretto snapshot <ref> --session debug-example

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.