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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Spree CLI
sidebarTitle: Spree CLI
description: Install and use the @spree/cli to scaffold, run, build, and migrate Spree projects — and call the Admin API directly from the command line.
---
The Spree CLI (`@spree/cli`) does two things from your terminal:
1. **Manages your Spree project** — boot the Docker stack, run generators and migrations, tail logs, open a console, upgrade versions.
2. **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](/developer/cli/admin-api).
```bash
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](/developer/cli/admin-api) 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:
```bash
npm install -g @spree/cli
```
Then run commands from your project directory:
```bash
spree dev
```
Or use `npx` without installing:
```bash
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.
```bash
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.
```bash
spree dev
spree dev --no-open # Skip opening browser
```
### `spree stop`
Stop all services.
```bash
spree stop
```
### `spree restart`
Restart `web` and `worker` in place — same image, same volumes, fresh backend process. Good for configuration changes the backend doesn't reload on its own.
```bash
spree restart
```
Not appropriate for dependency changes (Ctrl+C and re-run `spree dev`), Dockerfile or runtime 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 runtime version changes. Only relevant after `spree eject`.
```bash
spree build
spree build --reset-deps # Also drop the cached backend dependencies so they re-install
spree build --yes # Skip confirmation prompts (for CI)
```
`spree add <extension>` does NOT require a rebuild — dependencies land in a cache volume which survives image rebuilds.
`--reset-deps` only drops that 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:
1. **Update the server** — on a project that runs the prebuilt image, it pulls the latest Spree image. On an [ejected](#spree-eject) project, it updates the Spree gems with `bundle update`.
2. **Update the `@spree/*` packages** — `@spree/cli` in the project root, and the dashboard packages and SDKs in `apps/dashboard` and `apps/seller-dashboard`. The dashboard packages and SDKs move to the Spree version your server now runs. `@spree/cli` moves to the newest release its range in `package.json` allows.
3. **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.
4. **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.
```bash
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](/developer/upgrades) for the manual production path.
<Note>
`spree update` is the old name for this command. It still works, prints a deprecation warning, and will be removed in a future release.
</Note>
### `spree eject`
Switch from the prebuilt Docker image to building from your local `server/` directory. This lets you customize the backend — add extensions, override models, add migrations, etc.
```bash
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](/developer/create-spree-app/quickstart#customizing-the-backend) for details on what you can customize.
### `spree add`
Add an optional part or an extension to an existing project.
```bash
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](/developer/agentic/agent-skills) and connects Claude Code, Cursor and VS Code to the [docs MCP server](/developer/agentic/docs-mcp). 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](/integrations/payments/stripe) | `spree add stripe` |
| [PayPal](/integrations/payments/paypal) | `spree add paypal` |
| [Adyen](/integrations/payments/adyen) | `spree add adyen` |
| [Avalara AvaTax](/integrations/tax/avalara) | `spree add avatax` |
| [Klaviyo](/integrations/marketing/klaviyo) | `spree add klaviyo` |
| [EasyPost](/integrations/shipping/easypost) | `spree add easypost` |
| [Meilisearch](/integrations/search/meilisearch) | `spree add meilisearch` |
| [MCP server](/developer/mcp/quick-start) | `spree add mcp` |
| [OpenTelemetry](/developer/providers/observability) | `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](#spree-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:
```bash
spree add --gem spree_acme_loyalty
spree add --gem spree_acme_loyalty --npm @acme/loyalty-dashboard
```
### `spree logs`
Stream service logs.
```bash
spree logs # Web service (default)
spree logs worker # Worker service
```
### `spree console`
Open an interactive backend console.
```bash
spree console
```
### `spree shell`
Open an interactive bash shell inside the web container — the system-shell sibling of `spree console` 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`.
```bash
spree shell
spree bash # alias
```
### `spree open`
Open the admin dashboard in the browser.
```bash
spree open
```
### `spree seed`
Seed the database.
```bash
spree seed
```
### `spree sample-data`
Load sample products, categories, and images.
```bash
spree sample-data
```
### `spree user create`
Create an admin user. Prompts for email and password interactively, or pass them as flags:
```bash
spree user create
spree user create --email [email protected] --password secret123
```
### `spree api-key`
Manage Store and Admin API keys. Secret keys carry [scopes](/api-reference/admin-api/authentication) and require at least one.
```bash
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](/developer/deployment/environment_variables#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.
```bash
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](/developer/cli/admin-api) for the full guide.
```bash
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.
```bash
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 commands run inside the project's containers against the running stack. The one exception is `spree filters types --from`, which reads a saved file and needs no 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.
```bash
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.
```bash
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 `spree task api:filter_tables` output
```
See [using your own filters from TypeScript](/developer/core-concepts/search-filtering#using-your-own-filters-from-typescript).
### `spree migrate`
Install pending Spree migrations, then run them — the canonical post-update sequence.
```bash
spree migrate
spree migrate:status # show which migrations have run
spree migrate:rollback # roll back the last migration
spree migrate:rollback --steps 2 # roll back the last two
```
`spree migrate:status` and `spree migrate:rollback` use the backend's own migration tooling, so they may change in a future major release. `spree migrate` itself stays the same.
### `spree db:reset`
Drop, recreate, migrate, and seed the database. **Destructive** — wipes everything. Asks for confirmation.
```bash
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).
```bash
spree db:console
```
### `spree test`
Run the backend test suite inside the web container against the test database — never your development data. Everything after `test` goes to the backend's test runner (RSpec today), so file paths, line numbers and flags follow that runner's format.
```bash
spree test # full suite
spree test spec/models/spree/brand_spec.rb # one file
spree test spec/models/spree/brand_spec.rb:15 # one example
spree test --format documentation
```
The test database is created on the first run. See the [Testing tutorial](/developer/tutorial/testing) for writing specs.
## Running things inside the container
### `spree task`
Run a Spree maintenance task. The task names are stable; anything after the name goes to the task in the task runner's own format.
```bash
spree task load_sample_data
spree task search:reindex
spree task price_history:seed
spree task price_history:prune
```
### `spree exec`
Run an arbitrary command inside the `web` container. Use it for anything without a dedicated command.
```bash
spree exec ls -la
spree exec env
spree exec bin/rails runner "puts Spree::Product.count"
spree exec bundle outdated
```
## 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](/developer/agentic/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](/developer/agentic/overview).