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 configurator: declarative store configuration
Status: Design finalized — nothing built; open questions settled 2026-09-14
Target: Spree 6.0
Depends on: 5.5-admin-api-cli.md (credential resolution, Admin SDK transport), 6.0-admin-api.md (conventions, natural-key filters), 6.0-store-context-and-first-run-setup.md (what bootstrap owns), 5.6-admin-spa-csv-import.md (natural-key upsert precedent)
Author: Damian Legawiec ([email protected])
Last updated: 2026-09-14
Tracking: Linear V-3633 · GitHub spree/spree#14641
Summary
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: diff shows what would change, deploy applies it, introspect writes the live configuration back out as YAML. 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 sixty lines of Ruby embedded as strings 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, which matters because the default install is an API-only Docker app and headless teams often never open the Rails side. Every project scaffolded by create-spree-app ships 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 before a single spec starts.
Key Decisions (do not deviate without discussion)
- Built on the Admin API, run from the CLI, never in-process Ruby. An in-process
rake spree:config:applywould be faster and could call workflows directly, but it only works where you can run Rails, cannot target a hosted instance, and would not exercise the API. The whole point is a file that works from outside the app. The existingspree apitransport (credential layers,@spree/admin-sdk, retries, idempotency keys,X-Spree-Store-Id) is reused unchanged. - YAML is the canonical format; JSON is accepted for free. YAML carries comments and block text and diffs cleanly, which a hand-edited, reviewed file needs. YAML is a superset of JSON, so a generated file may be JSON with no second code path. The CLI already depends on the
yamlpackage. Nospree.config.tswith adefineConfig()helper: that reintroduces configuration as code that needs a runtime, which is what this removes. Teams that want loops generate YAML and commit the output. - A published JSON Schema makes the file self-describing. Every section is validated with Zod before any network call, and the same schemas emit a JSON Schema shipped with the CLI.
introspectwrites a# yaml-language-server: $schema=header so editors autocomplete and flag mistakes inline. - Records match on natural keys, never prefixed IDs. IDs differ per environment; a slug or code does not. References between records (a product's category, a delivery method's zone) are written as the target's natural key and resolved by the CLI. The key table below is part of the contract; a resource without a stable, unique, human-readable key cannot be managed until it gets one.
- Bootstrap stays in Ruby seeds; the configurator starts after it. The store row, the immutable admin role, the first admin user and the first API key have no API by design (
6.0-store-context-and-first-run-setup.md), and a Rails app must seed without Node.Spree::Seeds::Alldoes not shrink. The configurator assumes a bootstrapped store and a secret key with write scopes, whichspree initand the e2e global setup already provide. - Reconciliation is client-side in the first release. For each section the CLI lists live records filtered on the natural key, then creates, updates or skips. This needs no new endpoints beyond gaps the key audit finds (a missing Ransack allowlist entry, a missing key attribute). Server-side bulk upserts by natural key are a later optimisation for hot sections, added to the API only once the client-side path shows where they pay off.
prices/bulk_upsertandstock_levels/bulk_upsertare used where they already exist. - Transaction data is out of scope permanently. Orders, payments, fulfillments, returns, seller payouts and transfers are history, not configuration. They stay in Ruby sample data and in the e2e Ruby bootstrap. Customers are the one exception (see Design Details): they are reference data for promotions and groups, the CSV import already upserts them on email, and the e2e suite needs one.
- The engine is a library first and a command second, and it lives in
@spree/cli(decided 2026-09-14). The reconciliation code sits underpackages/cli/src/config/and is exported as@spree/cli/config; the commands inpackages/cli/src/commands/config.tsare a thin layer over it. The dashboard e2e global setup imports the library rather than shelling out tospree, so the suite does not depend on a built CLI binary. A separate@spree/configuratorpackage was rejected for now as one more package to version and release for a single consumer; putting it in@spree/admin-sdkwas rejected because the SDK stays a thin client and must not pullyamlandzodinto every consumer's bundle. Accepted trade-off: the dashboard e2e suite gains a workspace dependency on@spree/cli. If a third consumer appears, split the engine out then. - Deletes are opt-in per section (decided 2026-09-14).
deployonly creates and updates; live records missing from the file are deleted only in sections named in--prune <sections>, and--fail-on-deleterefuses any plan containing a delete. Full sync with a guard flag, as Saleor does, was rejected because a file that declares only delivery zones would then wipe every other section unless the operator remembered the flag. Accepted trade-off: a stale record can linger in staging unnoticed;diffreports live records absent from the file as "not managed" so they are visible. - The first release covers configuration, catalog and customers (decided 2026-09-14). Products with variants, prices and stock, and customers, are in scope from the start, because the dashboard e2e bootstrap needs them and dogfooding without them is theatre. Configuration-only was rejected as leaving most of the Ruby bootstrap in place. Accepted trade-off: products are the largest section and most of the implementation effort.
- Every new project ships with a config file, and project setup deploys it (decided 2026-09-14).
create-spree-appwritesspree.config.ymlat the project root with the store, its default channel and its default market filled in from the answers given at scaffold time, plus commented skeletons of the other sections.spree initrunsspree config deployagainst it right after seeding, non-interactively, so a fresh project's shape is in a file from day one and the same file is what CI later deploys to staging. Deploy needs write scopes, and the project's auto-minted key isread_allby design (5.5-admin-api-cli.md), sospree initmints a short-lived secret key with the scopes the file needs, deploys, and revokes it. Accepted trade-off: project setup now has an HTTP step against the freshly booted container and fails loudly if the API is not up, where before it only ran rake tasks. - The command noun is
config(decided 2026-09-14).spree config validate | diff | deploy | introspect, besidespree apiandspree auth. Top-level verbs were rejected becausespree deploynext tospree dev,spree buildandspree initreads as deploying the application;spree storewas rejected because it names one section of the file.
Design Details
Command surface
spree config diff --config store.yml # dry run, exit 0 when nothing would change
spree config deploy --config store.yml # diff, confirm, apply; non-TTY skips the prompt
spree config deploy --config store.yml --prune products,categories # allow deletes in these sections
spree config deploy --config store.yml --fail-on-delete # CI guard: refuse if the plan contains any delete
spree config introspect --out store.yml --include channels,delivery # live instance to YAML
spree config validate --config store.yml # schema check only, no network
Credentials resolve exactly as for spree api (flags, then env, then project auto-mint, then profiles). A deploy needs write scopes for every section present in the file; the plan step checks the key's scopes first and names the missing ones with the spree api-key create --scopes ... remediation, before touching anything.
File format
# yaml-language-server: $schema=https://spreecommerce.org/schemas/config/6.0.json
version: 1
store:
name: Acme Wholesale
default_currency: USD
supported_currencies: [USD, EUR]
channels:
- code: retail
name: Retail
- code: wholesale
name: Wholesale
customer_groups: [wholesale]
customer_groups:
- name: Wholesale
tax_categories:
- name: Default
default: true
- name: Non-taxable
delivery_zones:
- name: Europe
countries: [DE, FR, NL, PL]
delivery_methods:
- name: Standard EU
delivery_zone: Europe
calculator:
type: flat_rate
preferences: { amount: 9.90, currency: EUR }
product_types:
- name: Apparel
option_types: [size, color]
option_types:
- name: size
label: Size
values: [S, M, L, XL]
- name: color
label: Color
values: [Red, Blue, Black]
categories:
- permalink: clothing
name: Clothing
children:
- permalink: clothing/t-shirts
name: T-Shirts
products:
- slug: classic-tee
name: Classic Tee
product_type: Apparel
categories: [clothing/t-shirts]
channels: [retail, wholesale]
status: active
variants:
- sku: TEE-S-RED
options: { size: S, color: Red }
prices: { USD: 29.99, EUR: 27.90 }
stock: { Warehouse: 100 }
Only sections present in the file are reconciled. A file with just delivery_zones and delivery_methods touches nothing else. Inside a present section, records absent from the file are left alone unless that section is listed in --prune.
Natural keys
| Section | Key | Notes |
|---|---|---|
store |
singleton | update only; the row is bootstrap |
channels |
code |
unique per store today |
markets |
name |
unique per store today; a code column would be better and is part of the audit |
customer_groups |
name |
unique per store (soft-delete aware) |
tax_categories, tax_rates |
name |
|
delivery_zones, delivery_profiles, delivery_methods |
name |
|
payment_methods |
name |
credentials are never written from the file; see Secrets below |
stock_locations |
name |
|
product_types |
name |
unique per store, case-insensitive |
option_types |
name |
values keyed on name within the type |
categories |
permalink |
full path, so nesting is implied |
collections |
permalink |
|
products |
slug |
same key the CSV import uses |
variants |
sku |
nested under the product; same key the CSV import uses |
prices |
(sku, currency) |
via prices/bulk_upsert |
stock_levels |
(sku, stock location) |
via stock_levels/bulk_upsert |
price_lists |
name |
rows keyed on sku |
custom_field_definitions |
(resource_type, namespace, key) |
|
roles |
name |
the immutable admin role is skipped |
customers |
email |
same key the CSV import uses |
allowed_origins |
origin |
|
webhook_endpoints |
url |
|
api_keys |
name |
create only; the token is printed once and never written back |
integrations |
type |
one per store per type by validation |
commission_rates |
code |
|
seller_requirements |
type (or name for multi types) |
|
return_reasons, claim_reasons, refund_reasons, order_cancellation_reasons |
name |
|
sellers |
slug |
Where a key is not yet unique in the database, the audit adds the index and validation as part of this plan rather than letting the configurator pick the first match. Every key column must also be on the model's Ransack allowlist, since the client-side plan step filters on it.
Reconciliation
- Load and validate. Parse YAML, validate against the section schemas, resolve every reference to a key that exists either in the file or on the live instance. A dangling reference fails here, with the YAML path, before any write.
- Plan. For each present section, in dependency order, list live records filtered on the natural key and classify every file entry as create, update or unchanged. Update compares only the attributes the file sets. Live records not in the file become deletes only when the section is in
--prune. - Show the diff. Grouped by section, one line per record, attribute-level detail for updates. Machine-readable with
--format jsonso CI can post it. - Confirm and apply. Interactive TTY asks once; non-TTY proceeds unless
--fail-on-deletetrips. Writes go through the Admin SDK with idempotency keys, sequentially across sections and in small parallel batches within a section. A 422 is reported against the YAML path of the offending entry with the API's own messages, and the run continues with the remaining entries so one bad row does not hide the rest. - Report. Counts per section and per outcome; non-zero exit if anything failed.
Amended 2026-11-02 (
6.0-6.1-custom-fields-roadmap.md): custom field definitions come before every section whose records carry custom-field values (products, customers, sellers), so the order below moves them ahead of products. A definition'sfield_typeandresource_typeare fixed once created.resource_typeis part of the natural key, so an entry whoseresource_typediffers from a live definition's is a different definition: it plans as a create, and the live one is deleted only under--prune, like any other unmatched record. Afield_typethat differs on a matched entry is reported as an error in the plan step, never sent as an update. 6.1 addsstorefront_writableandvalidationsto the section schema; against an older instance, an entry that sets either is reported as an error in the plan step and never sent, because the Admin API drops attributes it does not know without an error.
Section order follows the reference graph: store, channels, customer groups, tax, delivery zones and profiles, delivery methods, payment methods, stock locations, option types, product types, categories, collections, custom field definitions, products (with variants, prices, stock), price lists, roles, customers, origins, webhooks, integrations, marketplace sections, api keys. Prune runs in reverse order.
Introspect
Reads every list endpoint of the requested sections, strips IDs, timestamps and computed fields, writes references as natural keys, and emits the file with the $schema header. Secrets never come back: payment method credentials, integration credentials and API key tokens are written as # managed outside this file. --include limits sections; the default is everything but products, since a large catalog belongs in the CSV import and export pipeline, not a hand-edited file.
Secrets
The file is meant to be committed. Provider credentials (payment gateway keys, integration tokens) are set by the file only through ${ENV_VAR} placeholders, which the CLI substitutes at deploy time and introspect never emits. A literal value in a credential attribute is rejected by validation.
Schemas
Section schemas are hand-written Zod in the engine package. They reuse the Admin SDK's generated attribute types where a section mirrors an API resource, and describe the file shape (nested variants, references by key, the ${ENV} placeholder) where it does not. zod-to-json-schema emits the published JSON Schema at build time. @spree/admin-sdk has no Zod today and gains none from this plan.
Dashboard e2e as the first consumer
packages/dashboard/e2e/global-setup.ts keeps two Ruby statements: Spree::Seeds::All.call and the admin user. Everything else in BOOTSTRAP_RUBY moves to packages/dashboard/e2e/fixtures/*.yml, applied through the library entry against the test server once it is up, with prune on. Products, the second channel, categories, the promo customer and group, stock locations and levels, and the supplier all fit the sections above. The ledger seller's payouts and transfers are transaction data and stay Ruby, in a much smaller block. Spec-level helpers that already seed through the Admin API (seedCatalogPickerProducts) are unchanged. The gain is twofold: the fixtures become readable, and every CI run exercises the Admin API write paths before the suite starts.
The seller panel has no e2e suite yet; when it gets one it starts from a YAML fixture, not another Ruby block. Core seeds, the worktree template and spree:load_sample_data do not change in this plan.
The project config file
create-spree-app writes spree.config.yml next to docker-compose.yml:
# yaml-language-server: $schema=https://spreecommerce.org/schemas/config/6.0.json
version: 1
store:
name: My Store # from the scaffold prompt
default_currency: USD
default_locale: en
default_country: US
channels:
- code: online
name: Online Store
markets:
- name: United States
countries: [US]
currency: USD
default: true
# delivery_zones:
# - name: Domestic
# countries: [US]
# delivery_methods:
# - name: Standard
# delivery_zone: Domestic
# calculator: { type: flat_rate, preferences: { amount: 5.00, currency: USD } }
spree init runs, in order: db:seed, spree:cli:ensure_api_key, then spree config deploy --config spree.config.yml with a secret key minted for that run and revoked afterwards. spree config deploy with no --config defaults to spree.config.yml in the project directory, so day-to-day use is spree config diff and spree config deploy with nothing else. The store section updates the seeded store rather than creating one; channels and markets are additive, so the wholesale channel that seeds create is left alone. The file is committed with the project, and the CLI quickstart teaches deploying it to a remote instance with a profile.
Recipes
spree config recipe <name> (a starter file for a wholesale store, a marketplace, an EU multi-currency setup) is a follow-up once the format has settled. The first release ships an examples/ directory in the CLI package and the e2e fixtures as living examples.
Documentation
A new docs/developer/cli/configurator.mdx covers the file format, the commands, the natural-key table, secrets, and CI usage, linked from the CLI quickstart and the Admin API page. The JSON Schema is published with the docs.
Migration Path
- Natural key audit. For every section in the table: confirm the key is unique per store at the database level, on the Ransack allowlist, and writable through the Admin API. Fix the gaps in
spree/coreandspree/apifirst, as their own small pull requests. - Engine and schemas. Section schemas, reference resolution, plan and apply, diff rendering. Unit tests with MSW against recorded Admin API shapes, plus one integration run against the API dummy app the way
packages/sdk/tests/integrationdoes. - Commands.
validate,diff,deploy,introspectin@spree/cli, sharing credential resolution withspree api. - Dashboard e2e. Move the bootstrap fixtures to YAML; the suite must stay green shard by shard.
- Project scaffold.
create-spree-appwritesspree.config.ymlfrom its prompts;spree initdeploys it with a per-run secret key.spree config deploydefaults to that file inside a project. - Docs and schema publication.
- Later, outside this plan: server-side bulk upserts by natural key for products and categories,
recipe, an MCP wrapper oncespree mcpexists.
Constraints on Current Work
- A new admin-manageable resource must have a stable, unique, human-readable key (code, slug or name, unique per store, enforced by an index) and that key must be on its Ransack allowlist. Without it the resource cannot be declared in a config file.
- New dashboard e2e fixtures go into the YAML fixtures once step 4 lands; until then, keep additions to
BOOTSTRAP_RUBYto what has no Admin API, so they move cleanly. - Do not add a Ruby-side YAML loader to core or the CLI's rake tasks; the configurator's contract is the Admin API.
- Credential attributes on payment methods and integrations must never be readable back through the Admin API in plain text;
introspectrelies on that.
Open Questions
None deferred. The four design questions (deletion policy, first-release scope, package placement, command noun) were settled on 2026-09-14 and are recorded under Key Decisions. The natural-key audit in Migration Path step 1 may surface resources whose key needs a schema change; those get decided in the audit pull requests, not here.
References
- Saleor Configurator: https://saleor.io/blog/configurator and https://github.com/saleor/configurator
docs/plans/5.5-admin-api-cli.md,docs/plans/6.0-admin-api.md,docs/plans/6.0-store-context-and-first-run-setup.md,docs/plans/5.6-admin-spa-csv-import.mdpackages/cli/src/commands/api.ts,packages/cli/src/config.tspackages/dashboard/e2e/global-setup.tsspree/core/app/services/spree/seeds/all.rb,spree/core/app/services/spree/sample_data/loader.rb