Spree CLI - Spree Commerce documentation

The Spree CLI (@spree/cli) does two things from your terminal:

Manages your Spree project — boot the Docker stack, run generators and migrations, tail logs, open a console, upgrade versions.
Calls the Admin API — generic get/post/patch/delete commands to read, write, and explore your store’s data, with zero-config credentials in local dev. See Admin API from the CLI.

spree dev                                                  # boot the project
spree api get /orders -q status_eq=placed --limit 10     # query the Admin API
spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'  # create a resource
spree api endpoints --search refund                        # discover endpoints, offline

The spree api commands work against any Spree 5.5+ instance and are built for both humans and AI agents — see the dedicated Admin API from the CLI guide. The rest of this page covers project management.

Installation

The CLI is included automatically when you scaffold a project with create-spree-app. You can also install it globally:

npm install -g @spree/cli

Then run commands from your project directory:

spree dev

Or use npx without installing:

npx @spree/cli dev

Commands

`spree init`

First-run setup. Starts Docker services, seeds the database, generates an API key, and optionally loads sample data.

spree init
spree init --no-sample-data   # Skip sample data
spree init --no-open           # Skip opening browser

`spree dev`

Run the app in the foreground — streams web + worker logs; Ctrl+C stops them. The databases keep running for a fast next boot (spree stop shuts everything down). The Admin Dashboard opens in your browser as soon as it is ready.

spree dev
spree dev --no-open            # Skip opening browser

`spree stop`

Stop all services.

spree stop

`spree restart`

Restart web and worker in place — same image, same volumes, fresh Rails process. Good for config/initializers/*.rb changes or anything Zeitwerk doesn’t auto-reload.

spree restart

Not appropriate for Gemfile changes (use spree bundle install, then Ctrl+C and re-run spree dev), Dockerfile / .ruby-version changes (use spree build), or compose file changes (Ctrl+C and re-run spree dev).

`spree build`

Rebuild the dev image after Dockerfile or .ruby-version changes. Only relevant after spree eject.

spree build
spree build --reset-bundle   # Also drop the bundle_cache volume so gems re-seed
spree build --yes            # Skip confirmation prompts (for CI)

spree bundle add does NOT require a rebuild — gems land in the bundle_cache volume which survives image rebuilds. --reset-bundle only drops bundle_cache. Postgres, Redis, Meilisearch, and storage volumes are preserved.

`spree upgrade`

Upgrade your project to the latest Spree release in one go. It works for both kinds of project:

Update the server — on a project that runs the prebuilt image, it pulls the latest Spree image. On an ejected project, it updates the Spree gems with bundle update.
Update the @spree/* packages — @spree/cli in the project root, and the dashboard packages and Admin SDK in apps/dashboard and apps/seller-dashboard. Each package moves to the newest release its declared range in package.json allows, the same way bundle update respects your Gemfile. To move to a new major version, change the range in package.json first.
Migrate the database — on a prebuilt-image project, it recreates the containers and the migrations run as they start. On an ejected project, it applies pending migrations.
Run data backfills — the version-specific steps from the upgrade manifest that convert existing records. An ejected project’s app is then restarted so it loads the new gems.

The packages are updated before the database steps, so a failed migration or backfill no longer stops them from moving to the newest release their ranges allow. Fix the cause and run spree upgrade again.

spree upgrade                  # Run every step, asking before each one
spree upgrade --plan           # List the data backfills without running anything
spree upgrade --to 6.1         # Set the target version for the data backfills
spree upgrade --step <id>      # Re-run a single data backfill (runs nothing else)
spree upgrade --yes            # Skip the prompts

Your storefront is your own code, so spree upgrade does not change it — it tells you which @spree/sdk version to move to. Production upgrades only need the data backfills — installing gems and migrating happen in your deploy pipeline. See Upgrades for the manual production path.

spree update is the old name for this command. It still works, prints a deprecation warning, and will be removed in a future release.

`spree eject`

Switch from the prebuilt Docker image to building from your local server/ directory. This lets you customize the Rails app — add gems, override models, add migrations, etc.

spree eject

After ejecting, the Docker image is built from server/Dockerfile. Edit files in server/ and run spree dev to rebuild and restart with your changes. See Customizing the Backend for details on what you can customize.

`spree add`

Add an optional part or an extension to an existing project.

spree add dashboard           # the Admin Dashboard app in apps/dashboard/, to customize it
spree add seller-dashboard    # the marketplace Seller Panel in apps/seller-dashboard/
spree add ai                  # Spree agent skills + the docs MCP server for coding agents
spree add stripe              # an extension, installed end to end

spree add ai installs the Spree agent skills and connects Claude Code, Cursor and VS Code to the docs MCP server. It keeps the MCP servers your config files already list and is safe to re-run. Pass --no-skills or --no-mcp to set up only one of the two.

Extensions

spree add <extension> installs an official extension in one step: it adds the gem, runs the extension’s installer if it has one, runs the migrations, installs its dashboard plugin if it has one, and restarts the server if it is running.

Extension	Command
Stripe	`spree add stripe`
PayPal	`spree add paypal`
Adyen	`spree add adyen`
Avalara AvaTax	`spree add avatax`
Klaviyo	`spree add klaviyo`
EasyPost	`spree add easypost`
Meilisearch	`spree add meilisearch`
MCP server	`spree add mcp`
OpenTelemetry	`spree add opentelemetry`

A few things to know:

A project on the prebuilt image is ejected first. The prebuilt image cannot load new gems, so the command offers to eject the project. Ejecting switches to a new development database without your current data, so it asks before doing it. Pass --yes to agree up front, for example in a script.
New projects already include some extensions. Stripe, EasyPost, Meilisearch and OpenTelemetry come with every new project. Until you eject, the command tells you there is nothing to install for those. After ejecting, it runs their installer and migrations again, which is harmless.
It is safe to run again. If an install fails partway, the command puts your Gemfile and config/ back as they were. Running it again finishes an install that stopped halfway, and keeps files the first run created.
Setup notes come from the extension. If an extension needs anything else, such as an environment variable, it says so while it installs.

To install an extension that is not in this list, name its gem or dashboard plugin package. The command asks you to confirm, since Spree does not vouch for it:

spree add --gem spree_acme_loyalty
spree add --gem spree_acme_loyalty --npm @acme/loyalty-dashboard

`spree logs`

Stream service logs.

spree logs         # Web service (default)
spree logs worker  # Worker service

`spree console`

Open a Rails console.

spree console

`spree shell`

Open an interactive bash shell inside the web container — the system-shell sibling of spree console (Rails) and spree db:console (psql). If the web container is down, it starts a one-off container against the same volumes instead. For one-off non-interactive commands, use spree exec.

spree shell
spree bash    # alias

`spree open`

Open the admin dashboard in the browser.

spree open

`spree seed`

Seed the database.

spree seed

`spree sample-data`

Load sample products, categories, and images.

spree sample-data

`spree user create`

Create an admin user. Prompts for email and password interactively, or pass them as flags:

spree user create
spree user create --email admin@example.com --password secret123

`spree api-key`

Manage Store and Admin API keys. Secret keys carry scopes and require at least one.

spree api-key list                                     # List all keys
spree api-key create                                   # Interactive
spree api-key create --name "Storefront" --type publishable             # Store API key
spree api-key create --name "Admin" --type secret --scopes read_all     # Admin API key
spree api-key revoke <id>                              # Revoke a key

`spree encryption init`

Generate Active Record encryption keys — Spree encrypts webhook signing secrets, payment gateway customer IDs and OAuth tokens with them. New projects already have keys; use this for projects created before they were generated at setup.

spree encryption init            # Add ACTIVE_RECORD_ENCRYPTION_* keys to the project's .env
spree encryption init --print    # Print a fresh set without writing anything (e.g. for your hosting provider)

It never overwrites keys .env already sets, and there is no --force: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new .env (spree dev — spree restart keeps the old environment), and back the keys up in your secret manager.

`spree api`

Call the Admin API with generic get/post/patch/delete commands — zero-config inside a project (a read-only key is minted on first use), env vars or profiles for remote stores. See Admin API from the CLI for the full guide.

spree api get /products -q status_eq=active --limit 10
spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'
spree api endpoints --resource orders    # endpoints + required scopes, offline
spree api schema "POST /orders"          # request/response schema, offline
spree api status

`spree auth`

Save Admin API credentials for remote stores as named profiles.

spree auth login --profile prod --base-url https://store.example.com
spree api get /orders --profile prod
spree auth status
spree auth logout --profile prod

Dev workflow commands

These mirror the Rails commands you’d run if you were running the app directly on your host — but each is routed through docker compose exec against the running stack.

`spree generate`

Run a generator inside the container. Bare generator names are auto-prefixed with spree: — model runs spree:model, api_resource runs spree:api_resource — so you get the Spree conventions (Spree:: namespace, spree_-prefixed table, prefixed IDs, null: false, no FK constraints) by default. Rails built-ins (migration, scaffold, mailer, job, …) and any name containing : are forwarded as-is.

spree generate model Brand name:string slug:string:uniq          # runs spree:model
spree generate api_resource Brand name:string slug:string:uniq   # runs spree:api_resource — model + v3 Store/Admin API
spree generate subscriber OmsOrderSync order.placed              # runs spree:subscriber — event subscriber + registration
spree generate migration AddPositionToSpreeBrands position:integer  # Rails built-in, forwarded as-is

spree:api_resource scaffolds the full v3 surface: model, migration, Store + Admin controllers and serializers, factory, controller specs, routes, and the read_<resources> / write_<resources> permissions that let staff roles and secret API keys reach the Admin API.

`spree filters types`

Generate TypeScript declarations for your app’s list filters, so the SDKs accept and autocomplete the filters and sort fields your app adds. It reads them from the running app and writes src/types/spree-filters.d.ts into each app under apps/ (storefront, dashboard, seller panel), for the SDK that app uses. Run it again after you change a filter.

spree filters types                                                    # every app under apps/
spree filters types --api store --out ../my-storefront/src/types/spree-filters.d.ts   # one app elsewhere
spree filters types --from filter-tables.json                         # from `bin/rails spree:api:filter_tables` output

See using your own filters from TypeScript.

`spree migrate`

Install pending Spree migrations from gems, then run db:migrate — the canonical post-update sequence.

spree migrate
spree migrate:status            # show the migration log (`db:migrate:status`)
spree migrate:rollback STEP=2   # roll back (`db:rollback`)

`spree db:reset`

Drop, recreate, migrate, and seed the database. Destructive — wipes everything. Asks for confirmation.

spree db:reset
spree db:reset --yes   # Skip confirmation (for CI)

`spree db:console`

Open a psql session against the dev Postgres database (runs inside the postgres container).

spree db:console

`spree routes`

Show Rails routes. All flags pass through to bin/rails routes.

spree routes
spree routes -g products                                 # Filter by pattern
spree routes -c Spree::Api::V3::Store::ProductsController   # Filter by controller
spree routes --expanded

`spree rspec`

Run the RSpec test suite inside the web container with RAILS_ENV=test, so tests hit the spree_test database — never your development data. Everything after rspec passes through, so file paths, line numbers, and flags work as usual.

spree rspec                                      # full suite
spree rspec spec/models/spree/brand_spec.rb      # one file
spree rspec spec/models/spree/brand_spec.rb:15   # one example
spree rspec --format documentation

Before the first run, create the test database with spree rails db:test:prepare. See the Testing tutorial for writing specs.

Running things inside the container

These are passthrough commands — anything after the subcommand reaches the inner Rails/Bundle/Rake invocation as-is. Useful for ad-hoc commands that don’t have a dedicated wrapper.

`spree exec`

Run an arbitrary command inside the web container.

spree exec ls -la
spree exec env
spree exec ruby -v

`spree rails`

Run a bin/rails command.

spree rails c                                  # Console (alias of `spree console`)
spree rails routes -g products                 # Alias of `spree routes -g products`
spree rails runner "puts Spree::Product.count"
spree rails new_subcommand arg1 arg2

`spree bundle`

Run a bundle command. Gems land in the bundle_cache volume (no image rebuild needed).

spree bundle install
spree bundle add faker
spree bundle update spree_core
spree bundle outdated

`spree rake`

Run a Rake task.

spree rake -T                          # List tasks
spree rake spree:upgrade               # Run the version-specific data backfills
spree rake spree:upgrade DRY_RUN=1     # Same, plan only

`spree task`

Shortcut for bin/rails <task> (Spree-style rake tasks registered as Rails tasks).

spree task load_sample_data
spree task spree:price_history:seed
spree task spree:price_history:prune

Pair with AI agents

The CLI’s predictable command surface is what AI coding agents drive when working on Spree projects. The Spree agent skills teach agents these commands and conventions (install them with spree add ai), and the Claude Code plugin adds /spree:doctor (stack diagnosis) and /spree:audit-upgrade (upgrade-readiness audit) on top. See Agentic Development.

​Installation

​Commands

​spree init

​spree dev

​spree stop

​spree restart

​spree build

​spree upgrade

​spree eject

​spree add

​Extensions

​spree logs

​spree console

​spree shell

​spree open

​spree seed

​spree sample-data

​spree user create

​spree api-key

​spree encryption init

​spree api

​spree auth

​Dev workflow commands

​spree generate

​spree filters types

​spree migrate

​spree db:reset

​spree db:console

​spree routes

​spree rspec

​Running things inside the container

​spree exec

​spree rails

​spree bundle

​spree rake

​spree task

​Pair with AI agents

Installation

Commands

`spree init`

`spree dev`

`spree stop`

`spree restart`

`spree build`

`spree upgrade`

`spree eject`

`spree add`

Extensions

`spree logs`

`spree console`

`spree shell`

`spree open`

`spree seed`

`spree sample-data`

`spree user create`

`spree api-key`

`spree encryption init`

`spree api`

`spree auth`

Dev workflow commands

`spree generate`

`spree filters types`

`spree migrate`

`spree db:reset`

`spree db:console`

`spree routes`

`spree rspec`

Running things inside the container

`spree exec`

`spree rails`

`spree bundle`

`spree rake`

`spree task`

Pair with AI agents