Skip to main content
Explanation

Safety and human approval

Overview​

The StoreFront CLI can change a live store. An agent can misread an instruction or produce the wrong content, so the toolchain puts several checks between a request and your shoppers: previews, an explicit acknowledgement for live changes, pushes that cannot overwrite newer work, and approvals that only you can give.

These checks reduce risk. They do not guarantee that a change is correct, harmless or reversible. Review what your agent proposes, start on a test storefront, and make small changes you can check.

Previews come first​

A preview shows a change on your real storefront without saving it. The agent stages its local files in a preview session (sf preview start, sf preview stage) and then prints a private link (sf preview open) that opens the storefront with the staged content in your browser. Nothing durable is written.

  • The preview link works once and expires after two minutes. Open it straight away, and do not share it.
  • A preview session lasts up to 8 hours. sf preview end closes it sooner.
  • A preview works on a locked storefront and in a browser that is not signed in to UltraCart.

The agent skill tells the agent to preview a visual change before pushing it, and to check the page at desktop and phone widths.

What --live means​

--live is a flag the agent must add to a command when the change reaches shoppers or customers. Without it, the CLI refuses the command with live_ack_required. The flag is an acknowledgement, not permission: the skill tells the agent to add it only once you have agreed to the change.

Where --live is needed, and what else is needed with it:

  • Your active theme. Writing a file in the theme shoppers see needs --live and publish permission on the signed-in user. Writing an inactive theme's .cjson files needs neither.
  • Page bodies. A page body, such as /about/body.cjson, sits outside every theme and has no draft copy, so writing one always needs --live and publish permission.
  • Text files and menus, always. Every sf files put needs --live, even for a file in an inactive theme, because a theme can be activated between the read and the write. Every sf menus push needs --live, because a store menu belongs to no theme and renders on every page that uses it.
  • Shared store data, on any theme. Page settings and attributes, item content and prices, site attributes, store menus, redirects, storefront languages, tracking settings, upsells and experiments are not part of a theme. A change to any of them is live as soon as it is written, even when you are building on an inactive theme. Built-in messages belong to a theme (the active one unless the agent names another), and a change to the active theme's messages is also live at once.

Permissions come from the UltraCart user who signed in. A user without write or publish permission gets permission_required, and the agent stops; changing a user's permissions is done in the admin.

Guarded writes cannot overwrite newer work​

When the agent reads a page or container with sf pull (or sf containers pull, sf menus pull), the CLI saves a baseline file beside it that records the exact version it read. A later push sends that version as an If-Match precondition. If anyone saved the content in between, for example a teammate in the Visual Builder, the push is refused with version_conflict and nothing is written. The agent then reads the new version and redoes its change on top of it.

  • A write that times out or fails may still have been saved. The CLI reads the content back to settle what happened, and never retries a write on its own.
  • sf push --dry-run runs every check the real push runs and shows the widget-level changes, without writing.
  • Not every resource has this protection. Page attributes and settings, site attributes and theme colors and fonts have no If-Match, and an admin screen saved afterwards can overwrite a change made through the CLI. The agent is told to coordinate edits and read again after writing.

After a push, reload any Visual Builder tab that has that page open before saving there. An older copy left open in the editor can overwrite the newer version.

You approve risky changes in the UltraCart admin​

Some changes need a person's approval before they run: deleting content, changing prices, changing live campaigns and flows, and the other actions listed in Changes that need approval. The approval is given in the UltraCart admin, with an authenticator app code. There is no command that approves a request, so an agent cannot approve its own change.

How a request moves:

  • The agent runs the command with a one-sentence reason (--reason). The CLI asks UltraCart for an approval of that exact change.
  • The command prints a link and a short code. The agent relays both to you word for word. It never opens the approval page itself and never asks for your authenticator code.
  • You open the link, check that the code and the described change match, and approve or deny with your authenticator app. The person asked is the UltraCart user who signed in the CLI, or a colleague on the same account that you name (--delegate <email>) who holds the admin permission for that kind of change.
  • After you approve, the agent runs the same command again with --approval <id>. UltraCart checks that the approval matches the change and uses it once.

Some approvals open a 10-minute approval session: you enter your code once, and later requests in those 10 minutes need only a click. The most sensitive actions ask for a fresh code every time, even inside a session. A denied request means the agent stops; it does not ask again without telling you why.

Changes that need approval​

This is the full list of approval-gated actions in the current beta (CLI 0.2.0-beta.3). The commands are what your agent runs; you see a plain description of each change on the approval page.

CommandWhat you approveCode
sf blog-posts deleteDeleting that blog postOne code covers the next 10 minutes
sf files deleteDeleting that fileOne code covers the next 10 minutes
sf redirects delete --idsEach batch of up to 5,000 redirect rulesOne code covers the next 10 minutes
sf files put --allow-script, or sf files revert of a .js fileExactly those script bytes, after UltraCart reviews themFresh code every time
sf files put --allow-template, sf files revert --allow-template, sf template wire, unwire, move and createExactly those template bytes (or that version), after UltraCart reviews themFresh code every time
sf experiments start-page, start-urlStarting that experimentOne code covers the next 10 minutes
sf experiments end --winnerEnding it with that winner, which cannot be undoneFresh code every time
sf experiments end --no-winnerEnding it and returning visitors to the originalOne code covers the next 10 minutes
sf upsells offers enable, sf upsells paths enableSwitching it on, the only way one goes onOne code covers the next 10 minutes
sf items set-attributes --applyEach batch of up to 200 itemsOne code covers the next 10 minutes
sf items pricing setThat price change, shown old to newOne code covers the next 10 minutes
sf items preorder set turning pre-order on or offThat change, for the item or each variation namedOne code covers the next 10 minutes
sf items variations set that stops a child item sellingThat list of changesOne code covers the next 10 minutes
sf items set-default-page --planEach call of up to 200 itemsOne code covers the next 10 minutes
sf comms twilio deleteRemoving the account's Twilio account from UltraCartOne code covers the next 10 minutes
sf comms domains deleteRemoving that sending domainOne code covers the next 10 minutes
sf comms sequences remove-step on a live campaign or flowRemoving that step, and archiving what it sentOne code covers the next 10 minutes
sf comms sequences move-step on a live campaign or flowMoving that stepOne code covers the next 10 minutes
sf comms sequences set-config turning a postcard step onTurning that step on, after which it mails printed cardsOne code covers the next 10 minutes
sf comms segments update --filter on a segment a live campaign or flow usesThat segment's new ruleOne code covers the next 10 minutes
sf comms transactional updateThat subject, delivery option or sender changeOne code covers the next 10 minutes
sf comms settings set with a sender or SMS numberThat default sender or SMS number changeOne code covers the next 10 minutes
sf comms providers importImporting those provider lists and subscribing every memberOne code covers the next 10 minutes
sf comms postcards mail-testPrinting and mailing one test card to that addressFresh code every time
sf comms flows backfillEnrolling and mailing past customers through that flowOne code covers the next 10 minutes
sf pages moveMoving that page and every page under it, and whether old addresses redirectOne code covers the next 10 minutes
sf site seo-set turning Canonical Links or Schema.org off, or Prevent Indexing on or offExactly those switchesTurning Prevent Indexing on: fresh code every time; otherwise one code covers the next 10 minutes
sf tracking html push that puts HTML in a slotExactly that HTML, after UltraCart reviews itThe approval says whether a session covers it
sf tracking affiliate-networks create or update that adds or changes a pixel or its conversion typeExactly that change, after UltraCart reviews the pixelThe approval says whether a session covers it
sf tracking affiliate-networks deleteDeleting that networkOne code covers the next 10 minutes
sf tracking integration set turning a provider on, loosening its consent gate, setting a script host or turning on Google Tag GatewayExactly that change; the server decides, and --dry-run says whether one is neededOne code covers the next 10 minutes
sf tracking integration clear that removes a consent gate something else still firesClearing that providerOne code covers the next 10 minutes
sf tracking smart-attribution set while active or making it active, and deleteExactly that change, or deleting the configurationOne code covers the next 10 minutes

Each sign-in can have at most 5 requests waiting at once. sf approvals list shows them, and sf approvals cancel <id> withdraws one.

Secrets are entered in the admin, never in the chat​

Some setup needs a credential, such as a Twilio auth token or a Mailgun API key. The agent never asks you for it in the conversation. It runs sf secrets request (or a command with @request), which prints a link and a code. You open the link and type the value into the UltraCart admin. The agent gets back a handle (sec_...) that stands in for the value, works only for that one field, and expires.

If you paste a password, key or token into the chat anyway, treat it as exposed: rotate it with its provider. The agent is told not to use or repeat it.

Know the blast radius​

Some changes reach further than the page you are looking at:

  • Templates. A template edit changes every page that uses that template.
  • Shared data. Item content, page data, site attributes and menus are shared by every theme, so an inactive theme does not isolate them.
  • Communications. A change to a live campaign or flow reaches customers at once. A transactional email change applies to the next matching order. Turning a flow on enrolls every customer its trigger fires for from then on.
  • Velocity. UltraCart blocks the IP address of a machine that writes forbidden Velocity template content, for 31 days. The CLI validates content before a write, and the agent is told to run the dry run first; validation never triggers a block.

The agent skill tells the agent to name the affected pages or customers before a broad change, and to run a dry run first where one exists.

Undo: versions and revert​

UltraCart keeps a version history for StoreFront files and containers, so most content changes can be rolled back.

  • sf files versions and sf files revert restore an earlier version of a page body, theme file or asset. A revert saves a new version, so the revert can itself be undone.
  • sf containers versions and sf containers revert do the same for item, upsell, email and postcard containers, which are stored as records rather than files.
  • The agent also keeps the originals it pulled, in your workspace.

Recovery has limits. A deleted file cannot be restored from its history. Some actions have no undo at all, including a blog post deletion, an email already delivered and a postcard already mailed, and restoring one file may not reverse related changes. If a write fails or the result looks wrong, stop and check the store's current state before running more commands.

Was this page helpful?