# Spree Commerce

Rails commerce platform whose official CLI calls the Admin API directly, built for scripts and agents.

Open-source headless e-commerce platform in Ruby on Rails with an admin dashboard, REST Admin and Store APIs with OpenAPI spec, a TypeScript SDK, and a Next.js storefront. The Builder ships @spree/cli, whose spree api get/post/patch/delete commands drive the Admin API with zero-config local credentials, plus 25 agent skills and a docs MCP. BSD-3-Clause; Enterprise is paid.

Alternative to: Shopify, Adobe Commerce

- Capabilities: adaptable, operable
- Vertical: ecommerce
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/spree/spree (BSD-3-Clause), 15661 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/spree--spree.html
- JSON: apps/spree--spree.json

## Use it when

- I want a Rails store for cross-border or B2B selling that my coding agent can extend using the Builder's own skills
- my agent should query and update the store from the terminal with one API key

## Gotchas

- The MCP the Builder publishes is docs-only (search and read); store operations go through the CLI or REST
- Auto-minted local keys are read_all only; write scopes need an explicit key
- Needs Node 22+ and Docker for the quickstart

## Editions

- Open source: Free, open source
  - source: npx create-spree-app@latest my-store
  - hosted: https://console.spree.sh
- Enterprise: Free, closed source
  - hosted: https://spreecommerce.org

## Adaptable: make it yours

Effort: light-edit (6 things to edit)

create-spree-app scaffolds a Rails project you own (backend, admin, Next.js storefront). Store settings, markets, channels, and themes are managed in the admin. The CLI reads SPREE_API_KEY and SPREE_BASE_URL, keeps profiles in ~/.config/spree/config.json and project keys in .spree/credentials.json. Custom resources and storefront changes are small edits in generated files, guided by the Builder's agent skills.

- Env vars: SPREE_API_KEY, SPREE_BASE_URL
- Config files: config/initializers/spree.rb, .spree/credentials.json, ~/.config/spree/config.json
- Prompt files: agent skills from spree/agent-skills (npx skills add spree/agent-skills)
- Accounts you'll need: Spree Cloud sandbox (optional); Stripe (storefront payments)

## Operable: what an agent can drive

Operability: official. Interface: cli at https://spreecommerce.org/docs/developer/cli/admin-api (published by the builder, both).

### Reach (partial coverage)

- Manage products, variants, prices: reachable. README: spree api post /products example; Admin API
- Manage orders: reachable. README: spree api get /orders -q status_eq=complete
- Customers, companies, customer groups: reachable. Admin API resources; spree api endpoints lists routes and scopes
- Promotions and gift cards: reachable. Admin API; feature list names promotions engine
- Markets, price lists, sales channels: reachable. Admin API resources per feature list
- Storefront shopping and checkout: reachable. Store API with publishable keys; TypeScript SDK
- Generate new API resources and run migrations: reachable. spree generate api_resource, spree dev
- Read the docs: reachable. docs MCP at spreecommerce.org/docs/mcp (search and read only)
- Enterprise-only features: not reachable. paid Enterprise edition

## Code stack

- Languages: Ruby, TypeScript
- Frameworks: Ruby on Rails, Next.js 16
- Package manager: bundler
- Database: PostgreSQL
- Hosting target: Docker, Spree Cloud sandbox

## Skills

bundled: Spree publishes an agent-skills plugin covering the admin, API, checkout, catalog and customization surface; the core repo separately carries contributor-only design skills.
- Paths: skills/*/SKILL.md
- Install: /plugin marketplace add spree/agent-skills

## Evidence and confidence

- formFactor: README: Rails backend with admin dashboard and Next.js storefront (confidence 0.95)
- executionModel: no model at runtime (confidence 0.95)
- operability: packages/cli in the spree repo; docs at spreecommerce.org describe spree api commands 'built for scripts and AI agents' (confidence 0.9)
- effort: CLI docs name SPREE_API_KEY and SPREE_BASE_URL and config paths; generators documented (confidence 0.75)
- editions: README: everything in the repo is BSD-3; Enterprise exists per triage (confidence 0.6)
- active: pushedAt 2026-09-02
- reach:  (confidence 0.85)

## Open questions

- Enterprise pricing and feature split
- Rails-side env var names (DATABASE_URL, SECRET_KEY_BASE) in the generated project

## Sources

- https://github.com/spree/spree (sourcing:ecommerce:github)
- https://spreecommerce.org/docs/developer/agentic/mcp (analysis)
- https://spreecommerce.org/docs/developer/cli/admin-api (analysis)