#14641·spree

Spree CLI configurator: declarative store configuration

Author: damianlegawiecCreated Sep 14, 2026Updated Sep 14, 2026

Add a command group to @spree/cli that treats a YAML file as the desired configuration of a store and reconciles a live instance against it through the Admin API: spree config diff shows what would change, deploy applies it, introspect writes the live configuration back out as YAML, validate checks the file offline. Records are matched on natural keys (slug, code, SKU, name), never on prefixed IDs, so the same file provisions a fresh local project, a staging environment and a hosted production store.

Today the only way to shape an environment is Ruby: db:seed, spree:load_sample_data, and the Ruby embedded in the dashboard's Playwright global setup. A declarative file is reviewable in a pull request, runs from CI against any instance, and needs no Ruby on the caller's machine. Every project scaffolded by create-spree-app ships with a spree.config.yml describing the store, its default channel and its default market, and spree init deploys it during setup. The dashboard e2e suite is the first consumer, so the tool is exercised on every CI run.

Migration path

  1. Natural key audit: for every managed section confirm the key is unique per store at the database level, on the Ransack allowlist, and writable through the Admin API.
  2. Engine and schemas under packages/cli/src/config/, exported as @spree/cli/config, with a published JSON Schema.
  3. Commands validate, diff, deploy, introspect in @spree/cli.
  4. Move the dashboard e2e bootstrap fixtures to YAML applied through the library.
  5. create-spree-app writes spree.config.yml; spree init deploys it.
  6. Docs page and schema publication.

Plan: https://github.com/spree/spree/blob/main/docs/plans/6.0-cli-configurator.md

Tracked in Linear as V-3633