Connect your store to the StoreFront CLI
Overview
To let your agent read or change a store, you connect a workspace to your UltraCart account. You do this once per workspace with three commands: create a profile, sign in, and bind the workspace to that profile.
Local work, such as validating files and browsing the element catalog, needs no sign-in. Everything that reads from or writes to a store does.
Prerequisites
- The CLI installed and a workspace created (Install and set up).
- An UltraCart user login for the account you are connecting. That user needs StoreFront access; the CLI can only do what the signed-in user is allowed to do.
- An UltraCart account that is enabled for the beta. If it is not, you find out at sign-in (see If the CLI says beta_access_required).
Sign in and bind the workspace
Run these from inside your workspace folder. my-store is a name you choose for the profile; use something you will recognize, such as northwind.
uc-storefront profile create my-store
uc-storefront auth login --profile my-store
uc-storefront profile bind my-store
uc-storefront profile show
uc-storefront sf storefronts
profile createmakes a named profile on this computer. A profile holds no password; it is a label the CLI keeps your sign-in under.auth loginsigns in through UltraCart's device flow. The CLI prints a web address and a short code. Open the address in your own browser, sign in to UltraCart as you normally do, and approve the code. You never paste a password or an API key into the terminal or the chat. If an agent runs this command for you, it relays the address and code to you, and you complete the sign-in yourself.profile bindties this workspace folder to that profile, so every command run here uses it. To also guard against signing in to the wrong account, pass the expected merchant ID:uc-storefront profile bind my-store --merchant-id <your merchant ID>.profile showandsf storefrontsconfirm which merchant you are signed in to and list its storefronts. Check that the merchant shown is the store you mean before you ask the agent to change anything.
Before every remote command, the CLI checks that the signed-in merchant matches the profile and the workspace binding, and stops if they disagree.
Where your sign-in is kept
Your sign-in is stored in your operating system's credential store: Keychain on macOS, Credential Manager on Windows, and Secret Service (such as GNOME Keyring) on Linux. It is never written to the workspace or to ultracart.json, so ultracart.json can be committed to version control. Keep the workspace binding (.ultracart/storefront.json), pulled baselines (*.sf.json) and merchant content out of public repositories; init prints the ignore rules to use.
Containers and hosted agents usually have no credential store. There the CLI can keep the sign-in in an encrypted file instead, with a key that you, not the agent, put in the platform's secret store. See Run on a hosted or containerized agent.
To sign out and remove the stored sign-in, run uc-storefront auth logout --profile my-store.
How long a sign-in lasts
A sign-in lasts up to 90 days, or 30 days if it is not used. uc-storefront auth status shows when yours expires. With fewer than 7 days left, commands that sign in print a one-line reminder, at most once a day.
To renew it, run uc-storefront auth login again. Do not work around an expired sign-in with another profile or an API key.
auth status works offline and reports what is stored on this computer. auth status --remote also checks with UltraCart, including whether your account has beta access, and may refresh your sign-in.
One workspace per merchant
Keep each merchant in its own workspace folder, bound to its own profile. A workspace that has an ultracart.json file never borrows another workspace's binding or a default profile: if it is not bound, commands stop and ask you to bind it or name a profile. That rule keeps an agent from writing to the wrong store because of where it happened to run a command.
If you manage several stores, for example as an agency, a layout such as storefronts/<client>/ with one bound workspace per client keeps them apart.
If the CLI says beta_access_required
beta_access_required means your UltraCart account is not enabled for the StoreFront CLI beta yet. Installing the CLI does not enable an account; UltraCart does.
- Stop remote work. Retrying, switching profiles, or using an API key does not get around it, and the agent skill tells agents not to try.
- Contact UltraCart support and ask for StoreFront CLI beta access. Include your Merchant ID (MID).
- While you wait, local work still runs: validating files, browsing the element catalog, and authoring content offline.
Start on a test storefront
Connect a test storefront first, or work on an inactive theme, and try a few changes there before you change your live store. An inactive theme still shares item content, menus and site settings with your live store, so those changes go live at once. Install and set up explains which changes are shared.
Next steps
- Safety and human approval: what is live, what is guarded, and what you approve
- What it can do: example requests for each area
- Troubleshooting: sign-in, access and setup problems