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.
Backend-Agnostic CLI
Status: In Progress — 6.x renames, deprecation notices and the backend adapter are in; removing the deprecated names is left for Spree 7.0
Target: Spree 6.0 (renames + deprecations), Spree 7.0 (removals)
Depends on: 5.5-admin-api-cli.md, 6.0-cli-configurator.md, 6.0-cli-add-extensions.md
Author: Damian Legawiec
Last updated: 2026-10-26
Tracking: Linear — · GitHub —
Summary
The spree CLI is the main way developers drive a project, and several of its commands, flags and help texts were named after Rails tools (spree rails, spree rake, spree bundle, spree rspec, spree routes, --reset-bundle, --ruby-name). This plan makes the CLI's public surface describe what a developer wants (run tests, run a task, add an extension) rather than which Rails tool does it, so the commands stay the same however the backend runs them. Rails-named commands keep working through 6.x with a deprecation notice and are removed in Spree 7.0.
Key Decisions (do not deviate without discussion)
- The neutral command is the contract; the backend is an implementation detail. Every Rails invocation the CLI makes lives in
packages/cli/src/backend.ts. Changing how the backend runs an operation means changing that file; command files do not change. - Deprecate, never break, in 6.x. Old names stay registered as hidden commands or hidden flags, keep their exact behaviour, and print one line to stderr naming the replacement. stderr keeps captured output (
$(spree …)) clean. spree execis the only escape hatch. Anything only meaningful on Rails (bin/rails runner,bundle outdated) is reached asspree exec bin/rails …. No other Rails-named command is added.- Extensions are installed with
spree add <extension>(decided 2026-10-01), built by6.0-cli-add-extensions.md: catalog names (spree add stripe), orspree add --gem <gem>outside the catalog. The deprecation notice forspree bundle addpoints at whichever of the two applies. spree generatekeeps every generator (decided 2026-10-26). The command name is already neutral; only the generator names are Rails ideas, and the docs still teach decorators, subscribers and migrations as the way to customize Spree 6. No generator prints a notice, and docs never route a generator throughspree exec. Spree 7.0 drops the generators that do not apply to it.spree task <name>is kept and its task names become public. The documented task names (search:reindex,load_sample_data,setup:token,price_history:seed,channels:full_upgrade) are part of the CLI's contract.spree rspecbecomesspree test. The name says what it does, not which runner does it.- Command names are the contract; pass-through arguments are not. Arguments after
spree testandspree task <name>belong to the backend's own test and task runners (RSpec file paths and flags, RakeKEY=valuevalues), so they can change when the backend does. Docs say so, and no script should depend on them across a major release. migrate:statusandmigrate:rollbackare not guaranteed beyond the current backend. They map onto the backend's migration tooling, which may not offer status or down migrations.spree migrate(apply pending migrations) is the guaranteed part.- Encryption key names are frozen.
spree encryption initwritesACTIVE_RECORD_ENCRYPTION_*into.env. Data encrypted with them is unreadable without them, so these names are never renamed.
Design Details
Command mapping
| Deprecated in 6.0 | Replacement |
|---|---|
spree rails … |
spree exec bin/rails … |
spree rake spree:<x> … |
spree task <x> … |
spree rake <other> … |
spree exec bin/rake … |
spree bundle add <gem> |
spree add <extension> or spree add --gem <gem> |
spree bundle <other> … |
spree exec bundle … |
spree rspec … |
spree test … |
spree routes |
spree api endpoints, or spree exec bin/rails routes … to filter Rails routes |
spree migrate <raw args> |
spree migrate |
spree migrate:rollback STEP=n |
spree migrate:rollback --steps n |
spree build --reset-bundle |
spree build --reset-deps |
spree plugin new --ruby-name |
--backend-name |
spree plugin new --no-engine |
--no-backend |
Unchanged names, swappable internals
init, dev, stop, restart, logs, open, eject, build, seed, sample-data, user create, api-key, console, shell, exec, task, test, migrate, migrate:status, migrate:rollback, db:reset, db:console, upgrade, encryption, api, auth, completion. Their help text no longer mentions Rails, Rake, Bundler, Puma or Active Record.
Backend adapter
src/backend.ts builds the command each neutral operation runs in the app container: console, test run, Spree task, seed, migrate, rollback, migration status, database reset, generator, extension install. Captured tasks (spree:cli:*, used by init, user create and api-key) and the extension installer's gem, generator and migration steps go through the same module.
Migration Path
- 6.0 — neutral names, hidden deprecated aliases with notices, backend adapter, docs switched to neutral names.
- 6.x — move
user createandapi-key list/revokeonto the Admin API (spree apitransport), which makes them backend-neutral without an adapter.initkeeps a backend task for the first key. - 7.0 — remove the deprecated commands and flags.
Constraints on Current Work
- Do not add CLI commands, flags or help text named after a Rails tool. New backend operations go into
src/backend.tsbehind a neutral command. - Docs show neutral commands only. Rails-only steps use
spree exec bin/rails …. - New Spree rake tasks that developers run by hand belong in the
spree:namespace sospree taskreaches them, and their names are treated as public. - Do not rename or stop reading the
ACTIVE_RECORD_ENCRYPTION_*variables.
References
5.5-admin-api-cli.md—spree apitransport6.0-cli-configurator.md— configuration through the Admin API, not Ruby6.0-cli-add-extensions.md—spree add <extension>packages/cli/src/backend.ts