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 endcloses 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
--liveand publish permission on the signed-in user. Writing an inactive theme's.cjsonfiles 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--liveand publish permission. - Text files and menus, always. Every
sf files putneeds--live, even for a file in an inactive theme, because a theme can be activated between the read and the write. Everysf menus pushneeds--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-runruns 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.
| Command | What you approve | Code |
|---|---|---|
sf blog-posts delete | Deleting that blog post | One code covers the next 10 minutes |
sf files delete | Deleting that file | One code covers the next 10 minutes |
sf redirects delete --ids | Each batch of up to 5,000 redirect rules | One code covers the next 10 minutes |
sf files put --allow-script, or sf files revert of a .js file | Exactly those script bytes, after UltraCart reviews them | Fresh code every time |
sf files put --allow-template, sf files revert --allow-template, sf template wire, unwire, move and create | Exactly those template bytes (or that version), after UltraCart reviews them | Fresh code every time |
sf experiments start-page, start-url | Starting that experiment | One code covers the next 10 minutes |
sf experiments end --winner | Ending it with that winner, which cannot be undone | Fresh code every time |
sf experiments end --no-winner | Ending it and returning visitors to the original | One code covers the next 10 minutes |
sf upsells offers enable, sf upsells paths enable | Switching it on, the only way one goes on | One code covers the next 10 minutes |
sf items set-attributes --apply | Each batch of up to 200 items | One code covers the next 10 minutes |
sf items pricing set | That price change, shown old to new | One code covers the next 10 minutes |
sf items preorder set turning pre-order on or off | That change, for the item or each variation named | One code covers the next 10 minutes |
sf items variations set that stops a child item selling | That list of changes | One code covers the next 10 minutes |
sf items set-default-page --plan | Each call of up to 200 items | One code covers the next 10 minutes |
sf comms twilio delete | Removing the account's Twilio account from UltraCart | One code covers the next 10 minutes |
sf comms domains delete | Removing that sending domain | One code covers the next 10 minutes |
sf comms sequences remove-step on a live campaign or flow | Removing that step, and archiving what it sent | One code covers the next 10 minutes |
sf comms sequences move-step on a live campaign or flow | Moving that step | One code covers the next 10 minutes |
sf comms sequences set-config turning a postcard step on | Turning that step on, after which it mails printed cards | One code covers the next 10 minutes |
sf comms segments update --filter on a segment a live campaign or flow uses | That segment's new rule | One code covers the next 10 minutes |
sf comms transactional update | That subject, delivery option or sender change | One code covers the next 10 minutes |
sf comms settings set with a sender or SMS number | That default sender or SMS number change | One code covers the next 10 minutes |
sf comms providers import | Importing those provider lists and subscribing every member | One code covers the next 10 minutes |
sf comms postcards mail-test | Printing and mailing one test card to that address | Fresh code every time |
sf comms flows backfill | Enrolling and mailing past customers through that flow | One code covers the next 10 minutes |
sf pages move | Moving that page and every page under it, and whether old addresses redirect | One code covers the next 10 minutes |
sf site seo-set turning Canonical Links or Schema.org off, or Prevent Indexing on or off | Exactly those switches | Turning Prevent Indexing on: fresh code every time; otherwise one code covers the next 10 minutes |
sf tracking html push that puts HTML in a slot | Exactly that HTML, after UltraCart reviews it | The approval says whether a session covers it |
sf tracking affiliate-networks create or update that adds or changes a pixel or its conversion type | Exactly that change, after UltraCart reviews the pixel | The approval says whether a session covers it |
sf tracking affiliate-networks delete | Deleting that network | One 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 Gateway | Exactly that change; the server decides, and --dry-run says whether one is needed | One code covers the next 10 minutes |
sf tracking integration clear that removes a consent gate something else still fires | Clearing that provider | One code covers the next 10 minutes |
sf tracking smart-attribution set while active or making it active, and delete | Exactly that change, or deleting the configuration | One 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 versionsandsf files revertrestore 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 versionsandsf containers revertdo 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.
Related documentation
- Connect your store: profiles, sign-in and workspace binding
- What it can do: each area's live rules and approvals
- Troubleshooting: refusal codes you may see
- File Manager: restore and compare file versions in the admin