Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
@spree/cli
3.6.2
Patch Changes
#15063
f114556Thanks @damianlegawiec! - Thespreecommand now starts frombin/spree.js, which loads the builtdist/index.js. Runningspreeworks the same as before.#15022
8890e33Thanks @damianlegawiec! - Removed the CLI's leftover Changesets dev dependencies and scripts; releases run from the repository root. Nothing changes for users of thespreecommand.
3.6.1
Patch Changes
- #14989
70ab2cdThanks @damianlegawiec! - When Docker runs out of network addresses,spree init,spree devand the other commands that start containers now explain why and how to remove the old networks, instead of showing only the raw Docker error.
3.6.0
Minor Changes
- #14975
f86d75cThanks @damianlegawiec! - Renamed the CLI commands and flags that were named after Rails tools, so each command describes what it does rather than which Rails tool runs it.spree testreplacesspree rspec,spree add <extension>replacesspree bundle add,spree migrate:rollback --steps nreplacesSTEP=n,spree build --reset-depsreplaces--reset-bundle, andspree plugin newtakes--backend-name/--no-backend.spree rails,spree rake,spree bundle,spree routes,spree rspecand the old flags still work and print a notice naming the replacement; they will be removed in Spree 7.0.spree testnow creates the test database when it is missing, so the suite runs on a fresh project with no setup step. Also fixed the setup-link hintspree initprinted, which named a command that does not exist.
3.5.0
Minor Changes
- #14980
6c126abThanks @damianlegawiec! -spree upgradenow moves the dashboard packages and the Admin and Seller SDKs to the Spree version. From Spree 6.0 these packages share the version of the Spree gems, and a range on an older line such as^1.0.0-rc.7would never reach it on its own. The packages move to the Spree version the server runs after its update, so a CLI built for an earlier release still moves them all the way. A package pinned to an exact version moves to that version and stays pinned; before,updateleft it on the old release while the server moved on. A release candidate pin moving to a final version becomes a^range instead, since pnpm writes release candidates back as exact versions on its own. The upgrade then dedupes each app, so a dependency the new release pins, such as@codemirror/view, isn't left installed twice and failing type checks. Yarn 2 and later is now also recognised from thepackageManagerfield. For a storefront on an older@spree/sdkline, the upgrade names the exact range to move to.
Patch Changes
#14978
2df9371Thanks @damianlegawiec! -spree upgrade,spree db:resetandspree db:consolenow say plainly when Docker is not running, and show Docker's own error for other failures instead of the command that failed.spree upgradenow asks before running the upgrade tasks (data backfills), so they can be skipped like the other steps.
3.4.1
Patch Changes
#14948
317c01aThanks @damianlegawiec! -spree upgraderunsbundle installitself when the gems in the container no longer matchGemfile.lock, instead of stopping and asking for it, and fails only if the bundle is still broken afterwards.#14966
88411f1Thanks @damianlegawiec! - The dashboard and seller panel starters now tell search engines not to index them: a<meta name="robots" content="noindex, nofollow">in each shell, for a panel served from a static host, alongside theX-Robots-Tagheader the Rails engine adds when it serves a panel itself.
3.4.0
Minor Changes
#14926
e0e980eThanks @damianlegawiec! -spree add <extension>installs an official extension in one step: Stripe, PayPal, Adyen, Avalara AvaTax, Klaviyo, EasyPost, Meilisearch, the MCP server and OpenTelemetry. It ejects a project still on the prebuilt image (after asking), adds the gem at the right version, runs the extension's installer and migrations, installs its dashboard plugin when it has one, and restarts a running server. A failed install puts the Gemfile back as it was. Extensions outside the list install withspree add --gem <name> --npm <package>, after a confirmation. New projects' agent instructions point coding agents atspree add.#14908
02ac2cfThanks @damianlegawiec! - Addedspree add ai, which installs the Spree agent skills and connects Claude Code, Cursor and VS Code to the Spree docs MCP server, so existing projects can get the same AI agent setup as new ones. It keeps the servers a project's config files already list and is safe to re-run. New projects now run it during setup: the agent skills question reads "Set up AI coding agents?" and covers both, and--docs-mcp/--no-docs-mcpanswer the docs half on their own.#14890
57469feThanks @damianlegawiec! -spree devnow opens the Admin Dashboard in the browser once it is ready. Pass--no-opento skip it.
Patch Changes
- #14906
6bcdb66Thanks @damianlegawiec! - New projects now ask whether to install the Spree agent skills (default yes;--agent-skills/--no-agent-skillsskip the question). The generatedAGENTS.mdis now the main instructions file for coding agents, withCLAUDE.mdimporting it, and it requires agents to run every command through the Spree CLI.spree add dashboardandspree add seller-dashboardnow include aCLAUDE.mdthat imports the app'sAGENTS.md, so Claude Code reads it too.
3.3.0
Minor Changes
#14866
cbde8feThanks @damianlegawiec! -spree api upload <file>uploads a file and prints thesigned_idto pass to the endpoint that uses it. Add--privatefor documents, imports and digital products.#14854
0cb8656Thanks @damianlegawiec! - Addedspree filters types, which writes TypeScript declarations for an app's own list filters and sort fields from its running backend (or frombin/rails spree:api:filter_tablesoutput with--from), so the SDKs accept and autocomplete them.#14858
b5208d0Thanks @damianlegawiec! -spree filters typesnow writes declarations into every app underapps/in one run, each for the SDK that app uses.--apiand--outwrite a single file for an app outside that layout.
3.2.2
Patch Changes
- #14748
012fcdbThanks @damianlegawiec! - Dashboards and seller panels added withspree addnow passtypecheckandlintout of the box: the seller panel no longer type-checks its Vite config without Node types, and the generatedbiome.jsonis formatted the way Biome expects.
3.2.1
Patch Changes
- #14843
6ff684eThanks @damianlegawiec! -spree upgradenow updates the@spree/*packages right after the server (gems or image) and before migrations and data backfills, so a failing migration or backfill no longer prevents the@spree/*packages from updating.
3.2.0
Minor Changes
- #14828
f61ff68Thanks @damianlegawiec! - Mergedspree updateintospree upgrade, which now upgrades both prebuilt-image and ejected projects and also updates the@spree/*packages of the project root and the dashboard apps.spree updatekeeps working for one release with a deprecation warning. New projects get anupgradescript instead ofupdate.
Patch Changes
#14758
d1b27e2Thanks @damianlegawiec! - Fixedspree ejectfailing on a fresh stack withservice "web" is not running. The development database is now created before the app server starts, since the server exits when that database is missing;spree initon an ejected project does the same. Eject also switches older dev compose files to a Postgres health check that only passes once the database server is really up.#14814
992b25eThanks @damianlegawiec! - Made the marketplace seller panel optional:create-spree-appnow asks whether to install it (yes by default) and accepts--no-seller-dashboard. Added--no-dashboardfor projects that are happy with the built-in admin dashboard;--react-dashboardis deprecated and does nothing. Apps are now set up in a consistent order — dashboard, seller panel, then storefront — and the storefront step looks the same as the others.spree initalso installs the seller panel's dependencies, and both tools now point projects without their own dashboard at the built-in one instead of saying no admin is installed.#14747
a0151c1Thanks @damianlegawiec! - Fixed the setup screen of a new project reloading while the merchant was filling it in. The generated route file now refers to installed packages by their stable location, andspree addgenerates it right after installing, so the first dev start has nothing to rewrite. Upgrades also no longer rewrite every line of that file, so its diff shows only the pages an upgrade added.
3.1.0
Minor Changes
- #14710
36df7c7Thanks @damianlegawiec! - Newspree encryption initcommand adds Active Record encryption keys (ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY,_DETERMINISTIC_KEY,_KEY_DERIVATION_SALT) to an existing project's.env, so Spree encrypts webhook signing secrets, payment gateway customer IDs and OAuth tokens at rest instead of storing them in plain text. It never overwrites keys that are already set.spree encryption init --printonly prints a fresh set, for your production host.
Patch Changes
#14703
9e41f7dThanks @damianlegawiec! -spree plugin newnow scaffolds a dashboard plugin that installs against the current dashboard. Its@spree/admin-sdkand@spree/dashboard-*peer ranges come from the versions released alongside the CLI, instead of old0.xranges no published package matched. The plugin package also gains abuildscript, sopnpm buildat the plugin root no longer fails, and asideEffectsentry so bundlers never drop the import that registers the plugin. The generated README no longer describes anengine/directory the CLI does not create.spree build --productionbuilds from the project root again with the current starter Dockerfile, so a customizedapps/dashboardis included in the image instead of being left out.#14697
f43bed2Thanks @damianlegawiec! -spree upgradeno longer reminds you to scheduleSpree::StockReservations::ExpireJob, a Spree 5.5 step that every 5.6 installation has already done. The "Next steps" panel now points you at your scheduled jobs and behavior changes in the upgrade guide and links to a page that exists.spree upgrade --plannow lists the same data backfills a real run executes after the Spree gems are bumped, instead of nothing.
3.0.2
Patch Changes
#14644
6723b99Thanks @damianlegawiec! -spree initsays where sample data comes from. A run that seeds no admin (no--admin-email) cannot load sample data, since its imports need an owner, so init now points at the setup screen's own "Load sample data" option instead of skipping silently. The--admin-emailand--no-sample-datahelp text says which flags belong to scripted installs.#14667
53008b4Thanks @damianlegawiec! - Scaffold dashboards with the layout they grow into, and the packages their first import needs.A new dashboard app shipped four files and no structure to follow, so the first customization had nowhere obvious to go. Both starters now carry the layout the dashboard uses internally —
pages/,hooks/,tables/,schemas/andlocales/, one file per resource — documented in the README, with anAGENTS.mdcovering the conventions a coding agent cannot infer.They also gain
@spree/dashboard-coreand@spree/dashboard-uias direct dependencies. Both were installed already but only as transitive ones, so under pnpm an import of either failed until you added it by hand.
3.0.1
Patch Changes
Fixed first-run setup failing partway through, and scaffolded both admin apps.
Several failures could leave a new project unusable: minting the CLI's API key raised "Name has already been taken" on any re-run, so a setup interrupted for any reason could never be completed; Mailpit's ports were not probed like the web port, so another Spree project or a local mail catcher failed
docker compose upwith a raw Docker daemon error; sample data was loaded before first-run setup created an admin to own it, aborting the run; and a failed key mint reported that the stack was not running, sending operators after a stack that was running fine.Scaffolds also create
apps/seller-dashboardalongsideapps/dashboard(spree add seller-dashboardadds it to an existing project). The React Dashboard is the admin in Spree 6, so it is no longer opt-in behind a flag, and first-run setup no longer prompts for an admin email and password — the account is created on the dashboard's own setup screen, which the browser opens automatically.
3.0.0
Major Changes
#14385
464df81Thanks @damianlegawiec! - Dropped the legacy Rails admin from the CLI.spree_adminis removed in Spree 6.0, so the CLI no longer references it:spree devandspree ejectno longer compile the admin Tailwind stylesheet or start its watcher — thespree:admin:tailwindcss:buildandspree:admin:tailwindcss:watchrake tasks went with the gem.spree dev,spree initandspree openno longer point athttp://localhost:<port>/admin, which now 404s. With a dashboard app present they open its Vite dev server; without one they open the store, and the summary card says to runspree add dashboard.
Admin UI now ships as the React dashboard. Run it with
spree dev(co-runs the dashboard dev server) or add it withspree add dashboard. Projects ejected before this release can delete the orphanedbackend/app/assets/builds/spree/admin/directory.#14431
aab4b5cThanks @damianlegawiec! -spree initasks who the admin is instead of seeding a known account.Spree 6.0 stops seeding
[email protected]/spree123, so the CLI no longer prints or assumes those credentials:spree initprompts for an admin email and password, or takes--admin-email/--admin-password. Both are validated before Docker starts, rather than failing minutes into the run, and passing only one is rejected.- A non-interactive run without those flags (CI, a piped invocation) creates no admin. The seed prints a one-time setup link instead, and the summary card shows it — open it to create the first account in the dashboard.
--opengoes straight there. - Sample data is skipped on that path, since its import needs an admin to own it. Load it after setup with
spree sample-data. spree devnames the admin emailspree initseeded; when no account was seeded it points at the setup link rather than guessing an address.- The exported
DEFAULT_ADMIN_EMAILandDEFAULT_ADMIN_PASSWORDconstants are gone.
Scripted installs that relied on the old credentials must now pass
--admin-emailand--admin-password.
Minor Changes
Added the marketplace Seller Panel to project scaffolding and deployment.
spree add seller-dashboardscaffolds the panel intoapps/seller-dashboard/, andcreate-spree-appnow creates both admin apps. The CLI bundles the seller-panel starter template alongside the dashboard one, so the Spree starter's Docker image can bake both and serve the panel at/sellers.
Patch Changes
#14417
7e35951Thanks @damianlegawiec! - Rich-text fields read as plain text plus HTML.Spree 6.0 stores rich text as sanitized HTML in plain text columns instead of Action Text. The write params are unchanged —
descriptionandinternal_notestill take the value, and that value is HTML.What changed is the read side:
internal_note_htmlis now readable onOrder, andinternal_note(plain text) onCustomer. Previously the order serializer returned only plain text and the customer serializer only HTML; both now return the pair.descriptionreturns tag-stripped plain text, with the markup underdescription_html. Hydrate an editor fromdescription_html, notdescription.
The field stores HTML, so send markup — a plain-text value with newlines in it renders as one run-on line.
#14376
a52a6daThanks @damianlegawiec! - Admin API additions from the 6.0 core rewrite:deliveryMethods.rulesCRUD anddeliveryMethods.ruleTypes()— delivery method eligibility rules (item total, weight).orders.discountCodes.create/delete— apply and remove coupon codes on draft orders with the storefront's pending semantics.expand=carton orders returns the originating cart (new adminCarttype); the embedded promotion summaries moved from thediscountskey toapplied_promotions(thediscountsname stays reserved for the typed money rows at/orders/:id/discounts).- Delivery methods accept
stock_location_idsfor pickup; delivery zones, delivery methods and stock locations are store-scoped. Ordergainscart_idandcoupon_code;DeliveryZone.membersrequiresexpand=members.
2.4.9
Patch Changes
- #14357
f811d1eThanks @damianlegawiec! - The bundled offline Admin API spec now documents thestoresarray on admin user responses, and thesearchable,sortable, andfilter_keyfields on custom field definitions.
2.4.8
Patch Changes
61f85afThanks @damianlegawiec! - Auto-enable the storefront wholesale B2B portal on sample-data scaffolds: create-spree-app writesSPREE_WHOLESALE_CHANNEL=wholesaleinto the storefront.env.local, and setup output points at the portal (/wholesale) with the buyer-approval flow. The portal runs on the default publishable key — no extra key or backend changes involved.
2.4.7
Patch Changes
- #14347
b78071fThanks @damianlegawiec! - All app-facing commands now fall back to a one-off container (docker compose run --rm) when the web container is not running, instead of failing ondocker compose exec. Previously onlyspree bundle,spree console,spree shell, andspree rspecdid this; the same behavior now coversspree migrate(+migrate:rollback,migrate:status),spree rails,spree rake,spree task,spree exec,spree routes,spree generate,spree seed,spree sample-data,spree user,spree api-key, andspree upgrade— which no longer refuses to run while the stack is down. The one-off container cold-starts and health-waits postgres, so these commands work from a fully stopped stack. On the fallback pathspree migratecollapses its two steps into a single invocation, paying the one-off container's cold Rails boot once.
2.4.6
Patch Changes
- #14339
b71e613Thanks @damianlegawiec! - The embedded dashboard-starter template now floats its@spree/*dependency ranges to the newest published release (floored at the versions the template was built against) instead of pinning the minor — scaffolded apps pick up new dashboard releases without waiting for a CLI release. The template also slims to@spree/dashboard+@spree/admin-sdk:defineDashboardPluginis re-exported from@spree/dashboard, and@spree/dashboard-core/@spree/dashboard-uiare added by the app only when building custom pages.
2.4.5
Patch Changes
spree build --productionis now a plaindocker buildfrom the project root: the updated spree-starter Dockerfile normalizes its own build context (detecting thebackend/layout and a customizedapps/dashboard), so the staged-copy and named-build-context machinery is gone, and what the CLI builds is byte-for-byte what Render/Railway build straight from the repo. A root.dockerignoreis written when missing so the context stays lean. Pre-normalization Dockerfiles keep the oldbackend/context, with a warning when a dashboard would be left out.Handle the Solid Queue single-container compose layout: new spree-starter projects have no
workerorredisservices (jobs run inside Puma, stored in Postgres), sospree dev,restart,build, anddb:resetnow target the services the compose file actually defines instead of hard-codingweb worker— Sidekiq-era projects keep working unchanged.spree logs workeron a worker-less project explains the in-process model and streams web logs, pointing at the/jobsdashboard.Removed the
render.yamlamendment fromspree add dashboard— the starter's Blueprint now deploys the backend as a Docker service built from the repo root, which bakesapps/dashboardinto the image by itself. The scaffolded dashboard also pins its package manager (packageManager+pnpm-workspace.yamlwithtrustLockfile) so image rebuilds don't break when pnpm changes install-policy defaults — pnpm 11'sminimumReleaseAgere-validation fails any rebuild whose lockfile references day-old packages, including every Spree release day (@spree/*is exempted from the gate).
2.4.4
Patch Changes
- Streamline the post-setup summary for projects with the React Dashboard.
The dashboard's dev server is presented as THE admin — the
cd apps/dashboard && pnpm devcommand with the admin credentials and a dim pointer to the classic admin — instead of listing two admins where only the classic one carried credentials. The image-served/dashboardbuild stays a deployment detail in the docs.spree dev(and first-run setup) now co-runs the dashboard's Vite dev server with the Docker stack — one command brings up the whole dev environment, its output joins the stream with adashboard |prefix, Ctrl+C stops everything, a dashboard crash warns without taking the API down, and--openwaits for Vite and opens the URL it actually reports (ports auto-bump when 5173 is taken).spree add dashboardgains--quietto skip its summary note when a wrapping tool (create-spree-app) prints its own. Projects without the dashboard keep the classic summary unchanged.
2.4.3
Patch Changes
- Fix dashboard logins dying on CORS in scaffolded apps.
spree add dashboardwroteVITE_SPREE_API_URL=http://localhost:<port>intoapps/dashboard/.env.local— but that variable is the SDK's switch to absolute cross-origin URLs (meant for production deploys on a different origin), so requests bypassed the Vite dev proxy and the browser blocked them (localhost:5173→localhost:3000is cross-origin; the auth cookie isSameSite=Laxon top). The scaffold now writesVITE_API_PROXY_TARGET(the proxy target — the SPA stays same-origin, the SDK stays on relative URLs), the dashboard template's Vite config reads it (vialoadEnv— Vite doesn't load.envfiles intoprocess.envfor configs), and the CLI writes or repairs.env.localautomatically: on scaffold, on everyspree devboot, and on aspree add dashboardre-run — covering fresh clones (the file is gitignored) and projects scaffolded by older CLI versions. Repair rewrites only the broken line; everything else in the file is preserved.
2.4.2
Patch Changes
spree devon a project that was never set up now runs the full first-run flow automatically (pull fresh images, start services, seed the database, configure API keys) instead of a baredocker compose up. A bareupnever pulls, so a mutable tag (latest) cached weeks ago by another project silently booted an old Spree whenever the first boot happened throughspree dev— a--no-startscaffold, an interrupted create-spree-app run, or a fresh clone. A setup that was itself interrupted partway (e.g. Ctrl+C during the first image pull) is also detected and completed on the nextspree dev, for projects scaffolded by create-spree-app 1.1.1+. The sample-data choice create-spree-app persists in.env(SPREE_SAMPLE_DATA) is honored, so a deferred first run keeps the answer given at scaffold time. Setup also installsapps/storefrontandapps/dashboarddependencies when they're missing (a fresh clone, or a scaffold whose install step failed) — mirroring create-spree-app's per-app install steps — so every app is runnable withpnpm devright after. Already-initialized projects are untouched: later boots never pull, dev stays offline-friendly, and upgrades stay explicit viaspree update.
2.4.1
Patch Changes
- Re-embed the dashboard-starter template against
@spree/dashboard0.10.1 and@spree/admin-sdk^0.6.0. 0.10.1 ships the Vite integration compiled to JS — registry installs of 0.10.0 failed the host build withERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPINGwhenvite.config.tsimported@spree/dashboard/vite— and admin-sdk 0.5.0 lacks the Admin API endpoints and types the dashboard consumes (the 0.x caret in the previous template pin never resolves to 0.6.0). Thespree dashboard pluginscaffold now pins@spree/admin-sdk^0.6.0 as well.
2.4.0
Minor Changes
- Add
spree add dashboard— scaffolds the React Dashboard starter (Developer Preview), bundled inside the CLI with version pins matching the release, intoapps/dashboard/of an existing project and points it at the project's API (--template <path|git-url>overrides the bundled copy). Also makespree plugin newfully non-interactive: every prompt has a flag (--ruby-name,--module-name,--npm-scope,--author,--author-email,--license,-y), with author details defaulting from git config.
2.3.9
Patch Changes
- Add
spree shell(alias:spree bash) — open an interactive bash shell inside the web container, the system-shell sibling ofspree console(Rails) andspree db:console(psql). When the web container is down — a crash-looping stack is exactly when a shell is most useful — it falls back to a one-off container against the same volumes, with postgres cold-started and health-waited first.
2.3.8
Patch Changes
- Add
spree rspec— run the RSpec suite inside the web container without spelling outspree bundle exec rspec. Everything afterrspecis forwarded verbatim (spree rspec spec/models/spree/brand_spec.rb:15,spree rspec --format documentation),RAILS_ENV=testis forced so tests always hit the test database, and when the stack is down the command falls back to a one-off container that cold-starts postgres first.
2.3.7
Patch Changes
- Compile the admin dashboard stylesheet on ejected projects. Ejecting bind-mounts
./backendover the image's precompiledapp/assets/builds, and the dev stack never runsassets:precompile, sospree/admin/application.csswas missing and every admin page 500'd.spree ejectnow compiles it, andspree devcompiles it if missing and then runs the Tailwind watcher so admin edits recompile live.
2.3.6
Patch Changes
- Fix
spree --versionreporting a stale hardcoded2.0.0instead of the installed CLI version. The version is now read from the package'spackage.jsonat runtime, sospree -Vandnpx spree -Valways match the release you have installed.
2.3.5
Patch Changes
- Fix
spree db:resetandspree consolewhen the stack is down or already serving.db:resetnow self-heals from any state: it stops the web + worker containers holding open Postgres connections (which a plainDROP DATABASErejects), then runs the drop/create/migrate/seed chain in a one-offdocker compose run --rm webcontainer whose dependencies cold-start automatically — so a reset works whether the stack is up, partially up, or fully stopped, and a stale host DB client (TablePlus/psql on port 5433) blocking the drop now produces an actionable hint instead of a raw error.spree consolefalls back to a one-off container when web is down (mirroringspree bundle) instead of failing, andspree db:consoleguides you to start the stack when Postgres isn't running. Both new fallbacks refuse cleanly in monorepo edge projects, consistent with the other commands.
2.3.4
Patch Changes
- Fix
spree upgradeon create-spree-app projects. Running it from thebackend/directory no longer fails on a missing.env— the CLI now resolves to the project root automatically. When the bundle is out of sync (e.g. an un-checked-out git gem source), it surfaces the real bundler error and points you atspree bundle installinstead of a misleading "No Spree gems detected". And it now refuses early with a clear message when the stack is down or in a monorepo edge project, rather than failing deep in a Docker command.
2.3.3
Patch Changes
- Fix an intermittent
failed to mkdir … file existserror on the firstspree eject/spree dev/spree init/spree updateof a fresh project. On a coldbundle_cachevolume thewebandworkercontainers raced to populate it; the CLI now bringswebup alone first so it seeds the volume uncontended before the rest of the stack starts.
2.3.2
Patch Changes
spree api statusnow shows the API key's live scopes fetched from the server instead of the stale snapshot saved at mint time. Falls back to the local snapshot (clearly labelled) when the server can't report scopes.
2.3.1
Patch Changes
- Fix
spree apiproduct-create examples in the CLI help text and docs. A product's price lives on its variants, so the example now ships apricesarray (for a simple product) instead of an unsupported top-levelpricescalar, and monetary amounts are quoted strings ("29.99") to match the API's read/write format and preserve localized input.
2.3.0
Minor Changes
spree initnow mints a read-only secret key and saves it to.spree/credentials.json, sospree apiworks immediately without a first-use minting round-trip. The setup summary shows both the Store API publishable key and the Admin API secret key.
2.2.1
Patch Changes
- Fix
npm installfailing withEUNSUPPORTEDPROTOCOL "workspace:".@spree/admin-sdkis bundled into the CLI at build time, so it's now a dev dependency — the publishedpackage.jsonno longer carries an unresolvableworkspace:runtime dependency.
2.2.0
Minor Changes
New
spree apiandspree authcommand groups — a generic Admin API client (get/post/patch/delete) built into the CLI:spree api get|post|patch|delete <path>— generic verbs with Ransack-qfilters,--sort/--page/--limit/--expand/--fields, and JSON bodies from inline/@file/stdinspree api endpoints/spree api schema— offline schema introspection over a bundled OpenAPI snapshot, including each endpoint's required scopespree api status— resolved credentials + server reachabilityspree auth login|status|logout|list— named profiles in~/.config/spree/config.jsonspree completion bash|zsh|fish— shell completion for resource paths, Ransack predicate stems, and scope names, resolved offline from the bundled spec- Zero-config credentials inside a project: a read-only key is minted via the dev stack on first use and stored in
.spree/credentials.json. For other servers,SPREE_API_KEYis enough — the host defaults tohttp://localhost:3000; setSPREE_BASE_URLor save a profile for a remote store.
Output is JSON: indented and colored in a terminal, compact and uncolored when piped (clean for
jq).Works against any Spree 5.5+ instance.
spree api-key createnow supports scopes for secret keys via--scopes(comma-separated, e.g.--scopes read_orders,write_products) or an interactive prompt defaulting toread_all. Required against Spree 5.5+ servers, where secret keys must carry at least one scope.
2.1.2
Patch Changes
spree generate controllernow forwards to the Railscontrollergenerator instead of the non-existentspree:controller.
2.1.1
Patch Changes
spree ejectnow repairs dev compose files scaffolded with the broken.:/railsbind-mount and runsdb:prepareafter switching to the dev stack. The dev image bypasses the entrypoint that creates the database in the prebuilt image, so without this the ejected stack booted against a missingspree_developmentdatabase.
2.1.0
Minor Changes
spree devnow runs the app in the foreground like every other dev server (vite dev,bin/dev): it streams web + worker logs andCtrl+Cstops them, while the database containers keep running for a fast next boot —spree stopremains the full shutdown. PreviouslyCtrl+Conly detached from the logs and left everything running. Real compose failures (daemon down, port conflict, bad config) now exit with the underlying code instead of printing a clean shutdown message; aCtrl+Cstop still ends cleanly.Add
spree restart— restartsweb+workerin place (same image, same volumes, fresh Rails process). Forconfig/initializerschanges and anything Zeitwerk doesn't reload; it does not pick up Gemfile or compose changes.spree bundlenow works when the stack is down: if thewebcontainer isn't running — for example after aGemfile.lockchange crash-loops the boot, which is exactly when bundler is needed — it runs bundler in a one-off container against the samebundle_cachevolume instead of failing onexec.spree devandspree builddetect monorepo edge projects (SPREE_PATHin.env) and refuse with a pointer to the matchingpnpm server:*script, instead of materializing the wrong compose config against the running edge stack.spree migrateprints a header for each step and a completion note — previously a fully up-to-date run produced no output at all, leaving no signal that anything ran.spree upgrade's closing "Next steps" panel now includes the SDK side of the upgrade: when the project has the conventionalapps/storefrontconsuming@spree/sdk, it names the currently-declared version and reminds you to bump it to the release matching the new Spree version.Add
spree generate,spree migrate(+migrate:rollback,migrate:status),spree build,spree db:reset,spree db:console, andspree routes.spree generateauto-prefixesspree:sospree generate model Brand name:stringinvokes the Spree generator.spree db:resetandspree build --reset-bundleare destructive and prompt by default; pass--yesto skip the prompt in CI.spree buildtargets the activedocker-compose.yml(the same filespree devruns) and refuses with a pointer tospree ejectwhen it has nobuild:section; in monorepo edge projects it points atpnpm server:build.spree ejectno longer runs a separatedocker compose buildstep (the dev compose builds on firstup -dautomatically). Its description and post-eject hints now point atspree bundle addfor gems andspree buildfor Dockerfile /.ruby-versionchanges.Add
spree exec,spree rails,spree bundle,spree rake, andspree taskas generic passthrough commands so any Rails / bundler / rake invocation is reachable throughspreewithoutdocker compose execincantations.spree task <name>auto-prefixesspree:to save the namespace prefix on the common path.spree consoleis rewired onto the same helper.Add
spree upgrade— sequencer around the dev upgrade flow. Runsbundle update, applies pending migrations, then delegates tobin/rake spree:upgrade(which executes the version-specific data backfills from a manifest shipped insidespree_core). On production, only the rake task runs — your deploy pipeline handlesbundle installanddb:migrate. Flags--plan,--step <id>,--to <version>,--yesmap to env vars (DRY_RUN,STEP,TO) on the rake task so the same arguments work on both surfaces.
Patch Changes
- Run
spree:search:reindexduringspree initafter sample data is loaded. This initializes the Meilisearch search index so product search works immediately after setup.
2.0.0
Major Release
Stable release of @spree/cli for Spree Commerce 5.4.0. Docker-based project management CLI with spree init, spree start, spree stop, spree eject, and spree update commands.
2.0.0-beta.7
Patch Changes
- Run
spree:search:reindexduringspree initafter sample data is loaded. This initializes the Meilisearch search index so product search works immediately after setup.
2.0.0-beta.6
Minor Changes
- Add
spree ejectcommand to switch from prebuilt Docker image to building from localbackend/directory. Also update port detection to readSPREE_PORTfrom.env.
2.0.0-beta.5
Patch Changes
- Automatically update storefront
.env.localwith the real API key duringspree init
2.0.0-beta.4
Patch Changes
- Pull latest Docker image during
spree initto ensure fresh setups always use the newest version - Show Docker pull progress output during
spree initandspree updateinstead of a spinner