Snapshots and reports
Overview
Your agent can record how a storefront is laid out, compare that record with the live site later, and turn it into a PDF you can share.
- A snapshot is a read-only record of a storefront at one moment: its pages, menus, files, site settings, redirects, theme colors and fonts, languages and search facets. Take one when a project is handed off, and keep it with the project's records.
- A diff compares a snapshot with a newer one, or with the live storefront. It lists what changed, which pages moved, and which menu links now lead nowhere. The agent skill tells the agent to report those gaps to you before it changes anything, because a change made since the snapshot may be deliberate.
- A report is a PDF made from a snapshot: a cover, the page tree, the menus, a page of search listing checks, desktop and phone screenshots of each pictured page, and an appendix of redirects.
Example requests
- "The relaunch is finished. Take a snapshot of the storefront so I have a record of how it was handed off."
- "Before you start on the new landing pages, compare the storefront with last quarter's snapshot and tell me what changed."
- "Make a PDF of the site for the client, with the home page and every page the menus link to."
- "Picture the staged pages in the report, before they launch."
Commands
| Command | What it does |
|---|---|
sf snapshot take <dir> | Write a snapshot of one theme (the active theme unless --theme names another) to a new or empty directory |
sf snapshot take <dir> --no-content | Record .cjson files by hash only, without saving their content |
sf snapshot diff <dir> --live | Compare a snapshot with the storefront as it is now |
sf snapshot diff <older-dir> <newer-dir> | Compare two snapshots |
sf report <dir> --out <file.pdf> | Write a PDF of the snapshot, with desktop (1440px) and phone (390px) screenshots |
sf report ... --all, --pages <path> | Picture every page, or only the pages you name |
sf report ... --session <id> | Picture staged content from a preview session instead of the live site |
sf report ... --hide-overlays | Hide fixed and sticky elements, such as a sticky header, chat button or cookie bar |
What a snapshot holds
A snapshot directory holds one JSON file per area, the content of each .cjson file (page bodies and theme containers) under cjson/, and SNAPSHOT.md, a readable summary to keep with your records. Timestamps, versions and etags are left out, so an unchanged storefront snapshots the same way twice.
It does not record other themes, file contents other than .cjson, secrets, tracking settings, upsells, experiments or communications.
The directory must be new or empty, so an earlier snapshot is never overwritten. The command warns about menu links to pages that do not exist.
What a diff reports
- Dead menu links. A menu entry that names a page follows that page when it moves, so it breaks only when the page is deleted. A custom entry holds a plain URL, and is reported dead when its URL named a page that is gone with no redirect from it.
- Moved pages, matched by the page's id, with any other fields that changed.
- Added, removed and changed items in each area, with the changed fields.
- Whether the active theme changed.
The diff exits with 0 when nothing differs, 1 when something differs, 2 when the command was refused, and 3 when the rate limit paused it. With --live, the signed-in profile must be on the same merchant as the snapshot.
There is no restore command. The agent fixes each gap with the command that owns that area, such as sf menus push, sf redirects add, sf pages move or sf containers revert, so approvals and stale-write checks still apply.
What a report shows
By default the report pictures the home page and every page the snapshot's menus link to. More than 50 pages is refused unless --max-pages raises the limit, and each page takes about 10 to 30 seconds. Pages load signed out in a fresh headless Chrome, so you need Chrome installed (--chrome <path> names it when it is not in the usual place).
The page tree, menus, settings and redirects come from the snapshot, so take a fresh snapshot first when the layout may have changed.
The "Search listing checks" page lists site-wide search settings worth reviewing, such as Prevent Indexing left on or canonical links off, and visible pages whose title or description is missing, a placeholder, shared with other pages, or longer than about 160 characters.
A page that cannot be captured is noted in the PDF and in the command's output, and the command exits 1. The output also warns when a page shows text shaped like an email address or a phone number. Look through the PDF before you send it.
What it costs
These commands make many UltraCart API calls, and every run reports how many it made:
| Command | About this many calls |
|---|---|
sf snapshot take | One per 25 pages and per 50 .cjson files, plus about 10 (--no-content skips the .cjson calls) |
sf snapshot diff --live | One per 25 pages, plus about 15 |
sf report | Two per run (one preview link per width), plus two more for each run that continues it |
The calls count against UltraCart's rate limit, which is shared by every tool and sign-in on the same machine and account. When too few calls are left, sf snapshot take and sf snapshot diff --live refuse at once with rate_limited and say when room comes back. When the limit is reached during a run, they wait as long as the server says, up to --wait seconds (600 by default), and then pause with exit code 3.
A paused snapshot keeps its reads in <dir>/.partial, and a paused report keeps its finished screenshots in <out>.parts. Run the same command again to continue; nothing is read twice. A live diff always starts over.
What it cannot do
- Restore a storefront from a snapshot. A snapshot is a record, not a backup. Fix each difference with the command for that area.
- Record communications, upsells, experiments, tracking or other themes.
- Picture pages behind a sign-in. Report pages load as a signed-out shopper sees them.
What needs approval
Nothing. Taking a snapshot, comparing it and making a report only read the storefront. Fixing what a diff finds goes through each area's own commands and their approval rules. See Changes that need approval.
Related documentation
- Pages and themes: moving pages and the redirects that follow
- Menus, search and site settings: fixing dead menu links
- Redirects and 404s: redirecting an old page address