Skip to main content
Explanation

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​

  1. Pull. sf pull reads a page body or theme container into a new local file, and writes a baseline file beside it.
  2. Reserve IDs. Before adding widgets, the agent reserves real widget IDs from UltraCart with sf ids. It never makes them up.
  3. Edit. The agent changes the local file with the CLI's local commands, such as add, update, move, remove or an apply plan. Nothing is sent to UltraCart.
  4. Validate. validate checks the file against the element catalog.
  5. Look at it. sf render renders one widget, and sf preview shows whole pages in your browser with the change staged. Neither writes anything.
  6. Dry-run the push. sf push --dry-run runs every check the real push runs and shows what would change, without writing.
  7. Push. sf push writes 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.

ContentStored asRead and write with
A theme container, such as a header, footer or checkout sectionA .cjson file in a themesf pull, sf push
A page body, such as /about/body.cjsonA .cjson file outside every themesf pull, sf push (always live)
An item's own content block, such as a specs blockA database row for that item and slotsf containers pull, sf containers push with --owner-type item or itemid
An upsell offer's pageA database row for that offersf containers with --owner-type upsell
An email bodyA database row for that emailsf containers with --owner-type email
The front or back of a postcardTwo database rows, one per sidesf 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_conflict and 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, and sf containers push --create a new container row. A create is refused if the target already exists, so it cannot overwrite one. sf containers push --create --remap-ids copies 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 search searches 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.

CommandWhat it does
cjson tree, treePrint the widget hierarchy with canonical paths and widget IDs
cjson find, findSearch widgets by type, title or content
cjson inspect, inspect, getRead one widget, selected by path or #id, within an output budget
cjson context, contextRead one widget with its schema, placement rules and diagnostics
cjson add, addAdd a widget under a parent
cjson update, updateChange a widget's settings with JSON Pointer assignments, or remove one with --unset
cjson move, move, cjson remove, removeMove a widget and its children, or delete them
cjson apply, applyApply an ordered plan of adds, updates, moves and removes as one atomic change
cjson initStart a new CJSON document
cjson translations, cjson translateList a file's text settings, and set translations for one
cjson validate, validateValidate 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 render renders 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, end show 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 diff compares 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 measure measures responsive image widths in a preview after a layout change. See Files and assets.
  • sf push --dry-run runs 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-run does the same for container rows.

Writing​

  • The active theme and page bodies need --live and 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 versions and sf files revert restore 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 version and sf containers revert do 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.

Was this page helpful?