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

# snapshot

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

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx libretto snapshot --session debug-example
```

### Arguments

<ParamField path="ref" type="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.
</ParamField>

### Required flags

<ParamField path="--session" type="string" required>
  The session to snapshot.
</ParamField>

### Optional flags

<ParamField path="--page" type="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](./pages) for details.
</ParamField>

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

<Tip>
  Use ref forms printed in the tree, such as `l16`. Numeric-suffix aliases such
  as `e16` also match `l16`.
</Tip>

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

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

<CardGroup cols={2}>
  <Card title="exec" icon="code" href="./exec">
    Run Playwright code to prototype interactions after using snapshot to identify elements.
  </Card>

  <Card title="run & resume" icon="play" href="./run-and-resume">
    Run a full workflow file and use snapshot to debug failures.
  </Card>
</CardGroup>