> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Spree CLI

> 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 theme={"theme":"night-owl"}
spree dev                                                  # boot the project
spree api get /orders -q status_eq=complete --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 theme={"theme":"night-owl"}
npm install -g @spree/cli
```

Then run commands from your project directory:

```bash theme={"theme":"night-owl"}
spree dev
```

Or use `npx` without installing:

```bash theme={"theme":"night-owl"}
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 theme={"theme":"night-owl"}
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).

```bash theme={"theme":"night-owl"}
spree dev
```

### `spree stop`

Stop all services.

```bash theme={"theme":"night-owl"}
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.

```bash theme={"theme":"night-owl"}
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 update`

Pull the latest Spree Docker image and recreate containers. Migrations run automatically on startup.

```bash theme={"theme":"night-owl"}
spree update
```

### `spree build`

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

```bash theme={"theme":"night-owl"}
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`

Walk a Spree version upgrade end-to-end inside the dev stack. Runs `bundle update`, applies pending migrations, then walks the version-specific data backfills from the upgrade manifest.

```bash theme={"theme":"night-owl"}
spree upgrade                  # Detect target, run the full sequence interactively
spree upgrade --plan           # Print the plan without executing (DRY_RUN=1)
spree upgrade --to 5.5         # Cap the walk at a specific target version
spree upgrade --step <id>      # Re-run a single step idempotently (skips bundle + migrate)
spree upgrade --yes            # Skip the per-step prompts
```

Production upgrades only need the third stage — `bundle install` and `db:migrate` happen in your deploy pipeline. The CLI runs all three for local development. See [Upgrades](/developer/upgrades) for the manual production path.

### `spree eject`

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

```bash theme={"theme":"night-owl"}
spree eject
```

After ejecting, the Docker image is built from `backend/Dockerfile`. Edit files in `backend/` 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 logs`

Stream service logs.

```bash theme={"theme":"night-owl"}
spree logs         # Web service (default)
spree logs worker  # Worker service
```

### `spree console`

Open a Rails console.

```bash theme={"theme":"night-owl"}
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`.

```bash theme={"theme":"night-owl"}
spree shell
spree bash    # alias
```

### `spree open`

Open the admin dashboard in the browser.

```bash theme={"theme":"night-owl"}
spree open
```

### `spree seed`

Seed the database.

```bash theme={"theme":"night-owl"}
spree seed
```

### `spree sample-data`

Load sample products, categories, and images.

```bash theme={"theme":"night-owl"}
spree sample-data
```

### `spree user create`

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

```bash theme={"theme":"night-owl"}
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](/api-reference/admin-api/authentication) and require at least one.

```bash theme={"theme":"night-owl"}
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 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 theme={"theme":"night-owl"}
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 theme={"theme":"night-owl"}
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.

```bash theme={"theme":"night-owl"}
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.completed           # 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, and routes.

### `spree migrate`

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

```bash theme={"theme":"night-owl"}
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.

```bash theme={"theme":"night-owl"}
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 theme={"theme":"night-owl"}
spree db:console
```

### `spree routes`

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

```bash theme={"theme":"night-owl"}
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.

```bash theme={"theme":"night-owl"}
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](/developer/tutorial/testing) 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.

```bash theme={"theme":"night-owl"}
spree exec ls -la
spree exec env
spree exec ruby -v
```

### `spree rails`

Run a `bin/rails` command.

```bash theme={"theme":"night-owl"}
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).

```bash theme={"theme":"night-owl"}
spree bundle install
spree bundle add stripe
spree bundle update spree_core
spree bundle outdated
```

### `spree rake`

Run a Rake task.

```bash theme={"theme":"night-owl"}
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).

```bash theme={"theme":"night-owl"}
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](/developer/agentic/agent-skills) teach agents these commands and conventions, 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).