The local editing workflow
Overview
Your agent never edits a live page in place. It reads the content into a local file, changes the file on your computer, checks it, shows you a preview, and only then writes it back. This page explains that loop, so you can follow what your agent is doing and know where to look when something goes wrong.
StoreFront content is stored as CJSON: a JSON tree of widgets, the same content the Visual Builder edits. What the agent builds stays editable in the Visual Builder.
The loop
- Pull.
sf pullreads a page body or theme container into a new local file, and writes a baseline file beside it. - Reserve IDs. Before adding widgets, the agent reserves real widget IDs from UltraCart with
sf ids. It never makes them up. - Edit. The agent changes the local file with the CLI's local commands, such as
add,update,move,removeor anapplyplan. Nothing is sent to UltraCart. - Validate.
validatechecks the file against the element catalog. - Look at it.
sf renderrenders one widget, andsf previewshows whole pages in your browser with the change staged. Neither writes anything. - Dry-run the push.
sf push --dry-runruns every check the real push runs and shows what would change, without writing. - Push.
sf pushwrites the file back, refusing if anyone saved the content since the pull.
The agent skill tells the agent to preview a visual change before pushing it, and to ask you before any live write.
Where content lives
Which commands reach a piece of content depends on how UltraCart stores it.
| Content | Stored as | Read and write with |
|---|---|---|
| A theme container, such as a header, footer or checkout section | A .cjson file in a theme | sf pull, sf push |
A page body, such as /about/body.cjson | A .cjson file outside every theme | sf pull, sf push (always live) |
| An item's own content block, such as a specs block | A database row for that item and slot | sf containers pull, sf containers push with --owner-type item or itemid |
| An upsell offer's page | A database row for that offer | sf containers with --owner-type upsell |
| An email body | A database row for that email | sf containers with --owner-type email |
| The front or back of a postcard | Two database rows, one per side | sf containers with --owner-type postcardfront or postcardback |
The two families are not interchangeable: sf pull takes only a .cjson file path, and sf containers refuses the theme and page owner types with a pointer to sf pull. sf containers list answers which item containers exist, for example which items carry a specs block, or what one product has.
For an item container, the agent addresses the item by its merchant item ID (--owner-type itemid), the ID a storefront page carries. Every item receipt names the merchant item ID the command reached, so you can check it hit the right item.
Baselines and stale-write refusal
When the agent pulls content, the CLI writes a baseline file beside it, named <file>.sf.json. The baseline records the merchant, the destination and a hash of the exact version read.
- A push sends that hash as a precondition. If anyone saved the content since the pull, for example a teammate in the Visual Builder, the push is refused with
version_conflictand nothing is written. The agent pulls again into a new file and redoes its change on top. - The destination comes from the baseline. A push goes back where the file came from. A different destination is refused, so the agent pulls to a new file to write elsewhere.
- A pull never overwrites a local file or baseline. Each pull goes to a new file.
- A copy has no baseline. The agent pushes the pulled file itself, not a renamed copy.
- New content uses
--create.sf push --create --to <path>creates a new theme container, andsf containers push --createa new container row. A create is refused if the target already exists, so it cannot overwrite one.sf containers push --create --remap-idscopies a container to another owner with fresh widget IDs.
Page attributes and settings, site attributes and theme colors and fonts are not edited through this loop and have no baseline. See Guarded writes cannot overwrite newer work.
Finding the right file
A page is usually built from several files: the page's own body and the theme containers its template includes. The agent finds the right one before it edits:
sf template find --uri <page>names the template a page uses and the file that renders it.sf locate --uri <page> <selector or widget id>names the file and widget behind something you saw on the page, such as a heatmap selector. See Analytics and tracking.sf files searchsearches file names and contents on the server, without pulling every file.
Editing locally
The local commands read and change one CJSON file on your computer. They make no network calls.
| Command | What it does |
|---|---|
cjson tree, tree | Print the widget hierarchy with canonical paths and widget IDs |
cjson find, find | Search widgets by type, title or content |
cjson inspect, inspect, get | Read one widget, selected by path or #id, within an output budget |
cjson context, context | Read one widget with its schema, placement rules and diagnostics |
cjson add, add | Add a widget under a parent |
cjson update, update | Change a widget's settings with JSON Pointer assignments, or remove one with --unset |
cjson move, move, cjson remove, remove | Move a widget and its children, or delete them |
cjson apply, apply | Apply an ordered plan of adds, updates, moves and removes as one atomic change |
cjson init | Start a new CJSON document |
cjson translations, cjson translate | List a file's text settings, and set translations for one |
cjson validate, validate | Validate the file against the element catalog |
Every edit validates before it writes, and writes the file in one step. --dry-run shows what would change without writing. An edit that would drop a language from a translated setting is refused unless the agent says that is intended.
validate reads the file alone. Zero errors does not promise that a push will succeed: a push compares the file with its baseline and holds the widgets and settings the agent added to stricter rules.
Checking before writing
sf renderrenders one widget against a theme and returns HTML, without writing. It needs a page address, and the item, group or test order the widget depends on. It shows what a shopper sees by default, or every branch the way the Visual Builder shows it with--edit-mode. Content that depends on the cart, a sign-in or the session still needs a preview.sf preview start,stage,open,endshow whole pages in your browser with local files staged in place of the saved ones. This is the only way to look at a page body or an item container before it is published. See Previews come first.sf preview diffcompares the saved page with the staged page at one or more widths, signed out, and writes full-page screenshots with the changed pixels highlighted.sf sizes measuremeasures responsive image widths in a preview after a layout change. See Files and assets.sf push --dry-runruns every check the push runs (local and server validation, compiling, Velocity checks, the live and removal acknowledgements and the version check) and prints the widget-level change, without writing.sf containers push --dry-rundoes the same for container rows.
Writing
- The active theme and page bodies need
--liveand publish permission. A page body sits outside every theme and has no draft copy, so writing one is always live. An inactive theme's containers can be written without--live. See What --live means. - Removing widgets needs
--allow-removals. A push that drops widget IDs present in the baseline is refused without it. - A failed or timed-out write may still have been saved. The CLI reads the content back to settle what happened, and never retries a write on its own.
- Reload the Visual Builder after a push. An older copy left open in the editor can overwrite the newer version. Before the agent pushes an email body or a postcard side, it asks you to close that email or postcard in the admin's editor for the same reason.
Undo
- Pulled originals. The agent keeps the files it pulled in your project folder, so you can see what changed.
- File history.
sf files versionsandsf files revertrestore an earlier version of a page body or theme container as a new version, so the revert can itself be undone. History ends when a file is deleted. - Container history.
sf containers versions,sf containers versionandsf containers revertdo the same for item, upsell, email and postcard containers. Every write is recorded, including the first one, so reverting to the oldest entry removes a container that did not exist before, and that removal can be reverted too. - After a revert, pull again. A revert does not change local files, so an earlier pull and its baseline are stale.
Restoring content cannot recall an email already delivered or a postcard already mailed.
Related documentation
- Safety and human approval: previews,
--live, approvals and version history - Element catalog, guides and recipes: how the agent knows which settings each element accepts
- Pages and themes: pages, templates and themes
- StoreFront Visual Builder: the editor that edits the same content