@spree/cli 2.4.3 → 2.4.5

package/README.md

@@ -1,24 +1,8 @@
 # @spree/cli
 
-CLI for managing [Spree Commerce](https://spreecommerce.org) projects.
+CLI for managing [Spree Commerce](https://spreecommerce.org) projects — Docker-based dev stack, generators, API keys, and a gh-style Admin API client.
 
-Automatically included in projects created with [`create-spree-app`](https://www.npmjs.com/package/create-spree-app). Can also be installed standalone.
-
-## Installation
-
-Already included when you scaffold a project with `create-spree-app`. To install separately:
-
-```bash
-npm install @spree/cli
-```
-
-Or run directly with npx:
-
-```bash
-npx @spree/cli <command>
-```
-
-Or install globally:
+Automatically included in projects created with [`create-spree-app`](https://spreecommerce.org/docs/developer/create-spree-app/quickstart). Can also be installed standalone:
 
 ```bash
 npm install -g @spree/cli
@@ -27,220 +11,31 @@ spree <command>
 
 ## Commands
 
-Run these from your Spree project directory.
-
-### `spree dev`
-
-Run the app in the foreground — prints connection info, then streams web + worker logs (like `vite dev`).
-
-```bash
-spree dev
-```
-
-Press `Ctrl+C` to stop web + worker. The databases (postgres, redis, meilisearch) keep running for a fast next boot — `spree stop` shuts everything down.
-
-### `spree stop`
-
-Stop all running services.
-
-```bash
-spree stop
-```
-
-### `spree update`
-
-Pull the latest Spree Docker image and recreate containers. Database migrations run automatically on startup via `db:prepare`.
-
-```bash
-spree update
-```
-
-To pin a specific version, edit `SPREE_VERSION_TAG` in your `.env` file:
-
-```
-SPREE_VERSION_TAG=5.4
-```
-
-### `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
-spree eject
-```
-
-After ejecting, edit files in `backend/` and run `spree dev` to rebuild and restart.
-
-### `spree logs [service]`
-
-Stream logs from a service. Defaults to `web`.
-
-```bash
-spree logs          # web server logs
-spree logs worker   # background job logs
-```
-
-### `spree console`
-
-Open an interactive Rails console inside the running container.
-
-```bash
-spree console
-```
-
-### `spree shell`
-
-Open an interactive bash shell inside the web container. If the container is down, a one-off container is started against the same volumes instead.
-
-```bash
-spree shell
-spree bash    # alias
-```
-
-### `spree rspec`
-
-Run the RSpec test suite inside the web container with `RAILS_ENV=test`. Everything after `rspec` is passed through to RSpec.
-
-```bash
-spree rspec                                      # full suite
-spree rspec spec/models/product_spec.rb          # one file
-spree rspec spec/models/product_spec.rb:15       # one example
-spree rspec --format documentation
-```
-
-Before the first run, create the test database with `spree rails db:test:prepare`.
-
-### `spree user create`
-
-Create an admin user. Prompts interactively for email and password, or accepts flags for scripting.
-
-```bash
-# Interactive
-spree user create
-
-# Non-interactive
-spree user create --email admin@example.com --password secret123
-```
-
-The user is automatically assigned the `admin` role on the default store.
-
-### `spree api-key create`
-
-Create a Store API (publishable) or Admin API (secret) key. Prompts interactively for name and type, or accepts flags.
-
-```bash
-# Interactive
-spree api-key create
-
-# Non-interactive
-spree api-key create --name "My Storefront" --type publishable
-spree api-key create --name "Admin Integration" --type secret --scopes read_orders,write_products
-```
-
-Secret keys require at least one scope (`read_all` for a read-only key, `write_all` for full access, or granular `read_*`/`write_*` pairs).
-
-**Important:** Secret key tokens are displayed only once at creation time and cannot be retrieved later. Save them immediately.
-
-### `spree api-key list`
-
-List all API keys for the default store with their name, type, token/prefix, creation date, and status.
-
-```bash
-spree api-key list
-```
-
-### `spree api-key revoke`
-
-Revoke an API key by its token (publishable) or token prefix (secret).
-
-```bash
-spree api-key revoke pk_abc123def456...
-```
-
-### `spree api`
-
-Call the Admin API directly with generic `get`/`post`/`patch`/`delete` commands. Works against any Spree 5.5+ instance — inside a project it self-provisions a **read-only** key via the dev stack on first use (saved to `.spree/credentials.json`, gitignored). For other servers set `SPREE_API_KEY` (the host defaults to `http://localhost:3000`; add `SPREE_BASE_URL` for a remote store) or save a profile with `spree auth login`.
-
-```bash
-spree api get /products -q status_eq=active --sort -created_at --limit 10
-spree api get /orders/ord_x8k2J9aQ --expand items,payments
-spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'
-spree api patch /orders/ord_x8k2J9aQ/cancel
-spree api delete /products/prod_86Rf07xd
-
-spree api endpoints --resource orders     # endpoints + required scopes (offline)
-spree api schema "POST /orders"           # request/response schema (offline)
-spree api status                          # resolved credentials + server check
-```
-
-Output is JSON on stdout — indented and colored in a terminal, compact and uncolored when piped (so it feeds cleanly into `jq`). `--format table` renders collections for humans. `--fields name,price` trims the response (the `id` is always included). API errors exit `1` with the error envelope on stderr — scope denials include the exact `--scopes` remediation.
-
-### `spree completion`
-
-Output a shell completion script (`bash`, `zsh`, or `fish`). Tab-completion suggests resource paths, Ransack predicate stems, and scope names — offline from the bundled spec.
-
-```bash
-eval "$(spree completion zsh)"     # add to ~/.zshrc (bash/fish also supported)
-```
-
-### `spree auth`
-
-Manage saved Admin API credentials for remote stores (profiles in `~/.config/spree/config.json`).
-
-```bash
-spree auth login --profile prod --base-url https://store.example.com   # key read from a prompt
-spree api get /orders --profile prod
-spree auth status
-spree auth list
-spree auth logout --profile prod
-```
-
-### `spree seed`
-
-Run database seeds.
-
-```bash
-spree seed
-```
-
-### `spree sample-data`
-
-Load sample products, categories, customers, and images.
-
-```bash
-spree sample-data
-```
-
-## How It Works
-
-The CLI detects your project by looking for `docker-compose.yml` in the current directory. All commands execute via `docker compose` against the running Spree containers.
-
-- **Port** is read from `SPREE_PORT` in your `.env` file (default: `3000`)
-- **User and API key commands** run Ruby scripts via `docker compose exec web bin/rails runner`
-- **Service commands** (`dev`, `stop`, `update`) are thin wrappers around `docker compose`
-
-## Using with npm scripts
-
-Projects created with `create-spree-app` include convenience scripts in `package.json`:
-
-```bash
-npm run dev             # spree dev
-npm run stop            # spree stop
-npm run update          # spree update
-npm run eject           # spree eject
-npm run logs            # spree logs
-npm run logs:worker     # spree logs worker
-npm run console         # spree console
-npm run seed            # spree seed
-npm run load-sample-data # spree sample-data
-```
-
-## Learn More
-
-- [Spree Documentation](https://spreecommerce.org/docs)
-- [Store API Reference](https://spreecommerce.org/docs/api-reference/introduction)
-- [create-spree-app](https://www.npmjs.com/package/create-spree-app)
-- [Spree GitHub](https://github.com/spree/spree)
+Run from your Spree project directory:
+
+| Command | Description |
+|---------|-------------|
+| `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the React Dashboard dev server when `apps/dashboard` exists |
+| `spree stop` | Stop backend services |
+| `spree update` | Pull the latest Spree image and restart (runs migrations automatically) |
+| `spree eject` | Switch from the prebuilt image to building from `backend/` |
+| `spree add dashboard` | Add the React Dashboard (Developer Preview) to an existing project |
+| `spree build --production` | Build the production image — the Spree API plus your dashboard, in one |
+| `spree console` / `spree shell` / `spree logs` | Rails console, container shell, log tailing |
+| `spree migrate` / `spree seed` / `spree sample-data` | Database tasks |
+| `spree generate …` | Spree generators (models, API resources, subscribers, migrations) |
+| `spree user create` / `spree api-key …` | Admin users and scoped API keys |
+| `spree api get/post/patch/delete <path>` | Call the Admin API directly (`spree api endpoints` lists routes + scopes) |
+| `spree rspec` | Run the backend test suite inside the container |
+
+## Documentation
+
+The full command reference lives on the docs site — this README intentionally stays short:
+
+- [CLI quickstart](https://spreecommerce.org/docs/developer/cli/quickstart)
+- [Admin API from the CLI](https://spreecommerce.org/docs/developer/cli/admin-api) — credentials, scopes, profiles
+- [create-spree-app](https://spreecommerce.org/docs/developer/create-spree-app/quickstart)
+- [Deployment](https://spreecommerce.org/docs/developer/deployment/docker)
 
 ## License