Connect with the CLI scaffolder

If your AI builder has a terminal (Cursor, Claude Code, GitHub Copilot, Codex CLI, Bolt.new, Replit Agent) this is the fastest way to start. The create-brainerce-store scaffolder spins up a Next.js storefront already wired to the Brainerce SDK, ready to be redesigned by your AI of choice.

Prerequisites

• A Brainerce store with at least one sales channel. If not, see Create a sales channel.
• Node.js 20.19+, 22.13+, or 24 and above (node -v to check). The installer stops with a clear message on older 20.x and 22.x builds, because a dependency of the generated storefront needs these minimums, so "Node 20" on its own is not enough.

Quick steps

1. In Brainerce: Sales Channels → your channel → Build with AI (bottom of the tab list). Use a computer for this step, because the button is not on the phone layout.

2. Copy the Quick Start one-liner. It looks like:

   npx create-brainerce-store@latest --connection-id vc_Fpi183aYc3WAqQnphxzWM

3. Paste into your IDE's terminal and run it.

4. cd into the new folder, pnpm dev, open http://localhost:3000, and your real catalog is there.

The --connection-id flag is filled in for you, so the scaffolder skips the "what's your channel ID" prompt entirely.

1. Open Build with AI

In the dashboard, open Sales Channels and click into the channel you want to connect. The channel's settings open with the tab list down the left: General, Permissions, Inventory and Upsell & Cross-sell under a Channel heading, then Danger Zone under Handle with care. Build with AI is the violet button at the very bottom of that list, below Danger Zone, so scroll the list down if you don't see it.

You need a computer for this. On a phone the tab list becomes a row of pills across the top and Build with AI is not shown at all, so there is no way to reach the CLI one-liner from a phone. The steps below assume a desktop browser anyway, since you'll be pasting into a terminal.

The Build with AI modal opens with three blocks: Quick Start (the CLI command), AI Prompt (for browser AI tools), and MCP Server (the docs server URL). For the CLI path you only need the first one.

2. Run the Quick Start command

The Quick Start block has a copy button. Click it, then paste in your IDE's terminal:

npx create-brainerce-store@latest --connection-id vc_…

The command:

• Asks two questions: the project name (pre-filled with a slug of your channel name, fetched from Brainerce) and your package manager (pnpm, npm, yarn, or bun, with the one it detects preselected).
• Writes the Connection ID straight into the new project's .env.local.
• Installs dependencies with the manager you picked.

No interactive Connection-ID prompt and no key-pasting; that part is handled by the flag.

Want it fully unattended? Add a project name (e.g. npx create-brainerce-store@latest my-shop --connection-id vc_…) and both prompts are skipped. The package manager is auto-detected from how you invoked the command; add --pkg-manager pnpm (or npm/yarn/bun) only to override that detection.

No Connection ID to hand? Run npx create-brainerce-store@latest my-shop without the flag. It opens a browser approval instead of asking you to paste anything: approve the page, and it fetches the ID itself. If you have no store or no sales channel yet, that approval creates them for you, so there is nothing to set up in the dashboard first.

Building first, connecting later? Add --defer-connection. The scaffolder writes a placeholder ID and skips the approval entirely, so an AI builder can construct the whole storefront without stopping. When it is done, run npm run connect inside the project for the one approval. The trade-off is smaller than it sounds: with no channel to read, the scaffold assumes English for the interface texts, which is the one thing connecting later does not change. Prices are not affected. The storefront reads your store's real currency when it runs, so it shows shekels the moment it is connected, whatever the scaffold assumed.

Adding your first products while you connect

A brand new store has no products in it, so a storefront that connects to one shows an empty grid. You can put a few starter products in during the same approval, without creating an API key:

npm run connect -- --seed-products '[{"name":"Burr Grinder","basePrice":389},{"name":"Ceramic Pour-Over 600ml","basePrice":149}]'

Each product needs a name and a basePrice, and can take a description. Up to 20 of them, and nothing else: no SKU, no options or variants, no categories, no images. They arrive as simple, active products that you can edit in the dashboard afterwards like any other.

On Windows PowerShell that quoting breaks. Put the identical text in an environment variable instead and run npm run connect on its own:

$env:BRAINERCE_SEED_PRODUCTS='[{"name":"Burr Grinder","basePrice":389}]'
npm run connect

The same flag works wherever you approve. If you skipped --defer-connection and let the scaffolder do the approval instead, put it on that line:

npx create-brainerce-store@latest my-shop --seed-products '[{"name":"Burr Grinder","basePrice":389}]'

What it needs is an approval, so some runs cannot use it. The permission to add these products comes from the approval itself and lasts about ten minutes. A run started with a Connection ID you already had never asks you to approve anything, so it has no permission to add products, and a deferred scaffold does its approving later, inside the project, which is where the flag goes on that path. Each of those tells you so and names the command that would work, rather than connecting and quietly leaving the store empty. It also cannot be repeated: a second attempt would need a second approval. In every one of those cases you add products in the dashboard instead, under Products, or bring them in from Shopify or WooCommerce with Apps > Browse > Migration Tool.

If some products go in and others are refused, the command tells you which by name and why. The ones it names as not created are not in your store, and you add those yourself.

3. What you get

my-shop/
├─ src/
│  ├─ app/               # Next.js app router routes — home, product, cart, checkout
│  ├─ components/        # Building blocks for the storefront UI
│  ├─ ui/                # Presentational layer — safe for an AI builder to restyle
│  └─ core/lib/brainerce.ts  # SDK client, pre-configured from .env.local
├─ AGENTS.md             # Instructions for AI builders working in this codebase
├─ CLAUDE.md             # Same, for Claude Code
├─ AI-GUIDE.md           # Longer walkthrough for AI builders
├─ TRANSLATIONS.md       # How to add languages
├─ .mcp.json             # Pre-wired MCP server for AI tooling
├─ .env.local            # vc_* Connection ID lives here
└─ package.json

What a new storefront includes today

A storefront scaffolded today arrives with a good deal already built, so you do not have to ask your AI builder for any of it:

⛔ These arrive with a new storefront only. An existing shop does not get them by upgrading. There is nothing to install, no update to accept and nothing to republish. Your shop is your own code sitting on your own hosting, so an improvement to this starter kit reaches it only when someone copies the change across. If your shop has no search box today, it will still have no search box tomorrow. Ask your developer, or your AI builder, to add the specific thing you want. See a feature you turned on is not showing on your website.

Two things a new storefront still does not do by itself, because they need your settings passed through and no starter kit can guess them:

• Prices in other currencies. If you use Regions, the shop has to ask which region the visitor is in. Until it does, everyone on earth is shown your default region's prices, and the page looks perfectly normal while doing it.
• Your "Only N left" number. The starter kit says "Only 5 left" because 5 is written into it. The threshold you set on the channel is not read. See Set up low-stock alerts.

Marketing tracking is already wired

The scaffolded storefront comes ready for Google Analytics 4, Google Tag Manager, the Meta pixel and the TikTok pixel. You do not paste a tracking ID and your AI builder does not need to add any tracking code. Connect the Google app under Apps and the storefront picks up the tracking ID by itself within about five minutes. Product views, add-to-cart, checkout starts and purchases all start reporting, with no republish.

Google is the only app in the store that can feed it today. The Meta and TikTok apps are built but have not been released, so there is nowhere to enter a Facebook or TikTok pixel ID in the dashboard. The storefront is ready for them; the apps are what is missing. Until they ship, fire those pixels through your own Google Tag Manager container instead.

Two things to know: a Google Tag Manager container ID is the one value you enter yourself (under Apps → Google → Analytics), and these tags set cookies, so if you sell to the EU or UK, ask your AI builder to add a consent banner. See Google Analytics, Google Tag Manager and the Meta pixel.

A newsletter signup is already in the footer

The scaffolded storefront ships an email capture form in the footer, wired up and working, so you do not ask your AI builder to add one.

It is a confirmed opt-in, so nobody is subscribed by filling it in. Brainerce emails the person a link, and they are only on your list once they click it. That is why the form says "check your email" and not "you're subscribed". Leave that wording alone, because it is the true one. The contact shows up under Customers straight away, marked Not subscribed, and flips over when they click. Full detail in Newsletter signup.

Signing up hands out no discount code. If you want "10% off your first order", create a coupon under Coupons with the first order only condition and ask your AI builder to show that code in the form's success message. There is a commented line in the component marking exactly where.

Don't want a mailing list? Ask your builder to delete the <NewsletterSignup /> block from the footer; nothing else depends on it.

The rewards panel appears on its own once you run a programme

The account page ships a rewards panel: the shopper's points balance, their tier and how far they are from the next one, and the rewards they can redeem. It shows nothing at all until a loyalty programme is running, so a store without one sees an ordinary account page, and a store that starts one later gets the panel without republishing anything or asking an AI builder for it.

You cannot start a loyalty programme yet. Loyalty is built but has not been released to stores, so there is no Loyalty entry in your sidebar and nothing to switch on today, which means this panel stays hidden however new your storefront is. It is there so that the day loyalty ships, your shop already shows it. See what Brainerce does not do.

Redeeming gives the shopper a one-time coupon code, not an automatic discount. The panel spends their points and shows the code, and they still have to enter it at checkout. That is how the feature works everywhere in Brainerce, so leave the wording that tells them to do it.

The balance shown is what they can spend today. Points from a fresh order sit pending for the number of days you set before they can be used, so a shopper who just bought something will not see those points yet. That is the setting under Loyalty, not a bug in the storefront.

The panel loads Brainerce's own rewards widget where it can. Rather than drawing the balance and rewards itself, a storefront scaffolded today asks Brainerce for a rewards panel and shows that inside the account page. The point of it for you is that rewards features Brainerce adds later turn up in your shop without anyone editing or republishing it. If that panel cannot load, for instance while the shopper's connection drops, the shop's own version takes over and the shopper still sees their balance, tier and rewards, so nothing looks broken. Either way it stays completely hidden until a programme is running, and no programme can be started today.

This still only arrives with a storefront scaffolded now. An existing shop does not start using the Brainerce-hosted panel by itself. It keeps the version it was built with until someone copies the change across, the same as everything else in this list.

A "refer a friend" link greets the visitor and remembers who sent them

The starter kit also handles the other half of a rewards programme: the share link one customer sends another. A referral link is your shop's address with a code on the end, like https://your-shop.com/?ref=REF-4KD92QP1.

A visitor who arrives on one gets a small message at the top of the home page reading "Rachel sent you a gift", with the welcome gift named underneath when you have set one up, and a link to create an account and claim it. If Brainerce does not have a first name for the person who shared the link, it says "A friend sent you a gift" instead.

The code is remembered for 30 days, which is the part that actually earns the referrer their reward. Almost nobody signs up on the page they land on: they browse, they leave, they come back next week. The shop keeps the code in that visitor's browser and puts it back when they eventually register, and the register page confirms it with "Your friend's invitation is applied". After they register the code is forgotten, so the next person to create an account on that computer is not credited to the same referrer by mistake.

It is remembered per browser, not per person. If someone opens the link on their phone and then registers on their laptop, the referrer gets nothing. There is no way to attach the referral by hand afterwards.

When the greeting does not appear at all, which is the part most often reported as a bug:

• The link points at anything other than the home page. A ?ref= code on a product page or a category page shows no greeting and, more importantly, is not remembered either, so that visitor cannot be credited even if they register. Share links must point at the shop's front page.
• There is no ?ref= code in the address, or it has been mangled by the app it was pasted through.
• Your store has no referral programme running, or Brainerce does not recognise that code.

In all of those the shop simply shows an ordinary home page. Nothing errors and nothing is logged for you to find, which is why a broken share link looks like nothing at all.

You cannot run a referral programme yet. Referrals are part of Loyalty, which is built but has not been released to stores, so there is nothing to switch on and no share links for your customers to send. Every visitor sees an ordinary home page today. It is in the starter kit so that your shop already works the day it ships. See what Brainerce does not do.

Open AGENTS.md first. It's a primer for your AI tool: it explains the SDK's data shapes, which hooks to use, and the patterns the scaffolder uses. Pointing Cursor or Claude Code at this file before you prompt makes a noticeable difference in the quality of the first design.

4. Run it

From inside the new folder:

cd my-shop
pnpm install   # only needed if the scaffolder didn't install
pnpm dev

Open http://localhost:3000. You should see a storefront listing the products you've published to this sales channel, with working cart and checkout.

If the page loads but the catalog is empty, jump back to your Brainerce dashboard and confirm at least one product has this channel toggled on under Publish to Platforms. See Create a sales channel, step 6.

While you're developing locally, the channel should stay in Test mode. That's the default after creation, and a Test channel with an empty Domain box accepts any host, including localhost. Only flip the channel to Live mode (and lock it to your production domain) when you're ready to publish to the real world; see Test mode vs Live mode.

The "accepts any host" part stops the moment you type something into Domain, and this catches people out because it sounds like a Live-only rule. It isn't. Once a Test channel has a Domain recorded, it checks addresses exactly like a Live one, and the check includes the port: a channel whose Domain reads localhost:3000 will refuse a shop running on localhost:5173, and refuse a plain localhost with no port too. If you record a Domain on a Test channel, record the full address your dev server actually prints, port and all.

Already published, and want to keep running locally against that same channel? You don't have to flip back and take the shop down for everyone. Add http://localhost:3000 as an extra chip in the Domains box on the channel's General tab and it works alongside your real domain. It does not enable social sign-in from localhost, because "Sign in with Google" always returns through your registered domain. See Keep building after you go Live.

5. Now hand it to your AI builder

Once the storefront is running, the AI writes against the real SDK from the first prompt. Open the project in Cursor / Claude Code / Copilot, and start with prompts like:

• "Redesign the home page to be a dark hero with a featured collection grid."
• "Add a back-in-stock alert form to sold-out products using the Brainerce SDK."
• "Change the product page layout to a two-column with gallery on the left and add-to-cart on the right."

The AI sees the real product types, real cart hooks, real checkout, with no rewrites later.

Ask for features Brainerce actually has. An AI builder will not tell you that a feature does not exist. Ask it for a wishlist, a page where customers sign themselves up to a subscription, or a page where a shopper buys a gift card, and it will happily build something that looks right and is not connected to anything, because there is nothing in Brainerce for it to connect to. Those three in particular are not supported; see what Brainerce does not do. Redeeming a gift card is a different matter and is fully supported, so "add a gift-card code field to the checkout that shows the remaining balance" is a good prompt, while "add a page where customers buy gift cards" is not. Everything on the required-features checklist is real, and that is the safest list to prompt from.

Want the AI to consult the live Brainerce docs and capabilities while it builds? Add the Brainerce MCP server. The Build with AI modal shows the URL under MCP Server (https://mcp-docs.brainerce.com/sse). Register it in your AI tool of choice (Cursor, Claude Code, Lovable, base44) and prompts can call get-sdk-docs, get-required-features, get-critical-rules, and more without any manual context juggling.

6. Publishing it to a real web address

The scaffolder runs on your machine (or inside an AI builder like ChatGPT or Bolt), and it has no way of knowing what web address your shop will end up on. So it does not write one into the project. Nothing is broken: the storefront works out what address it is being served on from each visitor's request, whether that's localhost while you build or a real domain once you publish.

You should still tell it your real address once you know it. Add this to the environment variables of wherever you host the shop (Vercel, Netlify, Render, Railway, Cloudflare; every host has an "Environment variables" screen):

SITE_URL=https://your-shop.com

Set it and two things get better: your Google listings, sitemap and social share links use one fixed address instead of whatever address each request came in on, and preview versions of your site stop competing with the real one in search results.

Do not put this in .env.local for a published shop. That file stays on your own computer. It is deliberately excluded when the project is pushed to GitHub, so a value you write there never reaches your host.

Older shops: projects scaffolded before this change have a line reading NEXT_PUBLIC_SITE_URL=http://localhost:3000 in .env.local. If that file travelled with your project to your host, your sitemap and Google listings are pointing at localhost, an address only your own computer can reach. Delete the line, and set SITE_URL on your host instead. The old name still works if you'd rather not rename it.

Hosting on OpenAI Sites (ChatGPT)? Setting SITE_URL is required, not optional

Some hosts never tell the shop what address visitors are using, and OpenAI Sites (addresses ending in .chatgpt.site) is one of them. On those hosts the shop cannot work out its own address from the request: every request looks like it arrived on localhost. There, SITE_URL is the only way the shop learns its address. Without it, the shop introduces itself to Brainerce as localhost, and a channel that has a Domain recorded refuses those requests, so product pages then fail even though the products and their slugs are perfectly fine. This applies in Test mode too: a Test channel with a Domain recorded checks addresses just like a Live one.

So on OpenAI Sites (and any host where things work on your computer but not once published): set SITE_URL in the host's environment variables, and make sure the same address is recorded under Sales Channels → your channel → Domain.

Shops scaffolded before this change showed this failure as a misleading "Page not found" (404) on every product page. Newer shops show a "Something went wrong, try again" page instead, and the real reason is written to the host's server log. Either way, the fix is the same: set SITE_URL.

Publishing also means setting the Domain on your channel

Setting SITE_URL is only half of going live. A channel in Live mode only answers requests coming from the web address recorded on the channel itself. That check happens on Brainerce's side, and no setting inside your project can satisfy it. If your shop's address isn't the one on the channel, every request is refused, and the shop loads empty.

So when you publish: put the address in SITE_URL and in Sales Channels → your channel → Domain. See Test mode vs Live mode.

Troubleshooting

What's next?

• Add a product to fill the catalog the storefront will display.
• What are sales channels is a recap of the model, especially the multi-brand piece.
• Building on Lovable instead? Switch to Connect from Lovable.
• Google Analytics, Google Tag Manager and the Meta pixel covers what turns on by itself, and what you set yourself.