Skip to content

armgit / spree

Public Imported from GitHub
0

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.

6.2 KB
Raw Blame

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 exec is the only escape hatch. Anything only meaningful on Rails (bin/rails runner, bundle outdated) is reached as spree exec bin/rails …. No other Rails-named command is added.
  • Extensions are installed with spree add <extension> (decided 2026-10-01), built by 6.0-cli-add-extensions.md: catalog names (spree add stripe), or spree add --gem <gem> outside the catalog. The deprecation notice for spree bundle add points at whichever of the two applies.
  • spree generate keeps 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 through spree 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 rspec becomes spree 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 test and spree task <name> belong to the backend's own test and task runners (RSpec file paths and flags, Rake KEY=value values), so they can change when the backend does. Docs say so, and no script should depend on them across a major release.
  • migrate:status and migrate:rollback are 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 init writes ACTIVE_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

  1. 6.0 — neutral names, hidden deprecated aliases with notices, backend adapter, docs switched to neutral names.
  2. 6.x — move user create and api-key list/revoke onto the Admin API (spree api transport), which makes them backend-neutral without an adapter. init keeps a backend task for the first key.
  3. 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.ts behind 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 so spree task reaches 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 api transport
  • 6.0-cli-configurator.md — configuration through the Admin API, not Ruby
  • 6.0-cli-add-extensions.md — spree add <extension>
  • packages/cli/src/backend.ts